From 2bc5de86357fddcc52e2ce0c1b432a9509dea27e Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 19 Jul 2013 12:02:44 +0200 Subject: Rename ‘nix-build --run-env’ to ‘nix-shell’ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/manual/Makefile.am | 2 +- doc/manual/manual.xml | 17 +++--- doc/manual/nix-build.xml | 78 +----------------------- doc/manual/nix-shell.xml | 142 +++++++++++++++++++++++++++++++++++++++++++ doc/manual/release-notes.xml | 37 +++++++++++ 5 files changed, 191 insertions(+), 85 deletions(-) create mode 100644 doc/manual/nix-shell.xml (limited to 'doc/manual') diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index eedc992a3851..56be7e1b88ed 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -16,7 +16,7 @@ dblatex_opts = \ # Note: we use GIF for now, since the PNGs shipped with Docbook aren't # transparent. -man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \ +man1_MANS = nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \ nix-collect-garbage.1 nix-push.1 nix-pull.1 \ nix-prefetch-url.1 nix-channel.1 \ nix-install-package.1 nix-hash.1 nix-copy-closure.1 diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index aa461d7081bf..6abff02d9ef4 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -19,15 +19,15 @@ - 2004-2012 + 2004-2013 Eelco Dolstra - May 2012 - + July 2013 + - + @@ -40,17 +40,18 @@ Command Reference - +
Main commands
- +
Utilities + @@ -66,7 +67,7 @@ Files
- + @@ -78,5 +79,5 @@ - + diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index 61b59c1e0adc..969faf9d1694 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -38,12 +38,6 @@ outlink - - - cmd - regexp - - paths @@ -76,14 +70,6 @@ a root of the Nix garbage collector. This root disappears automatically when the result symlink is deleted or renamed. So don’t rename the symlink. -The subcommand nix-build --run-env will build -the dependencies of the derivation, but not the derivation itself. It -will then start an interactive shell in which all environment -variables defined by the derivation have been set to their -corresponding values, and the script $stdenv/setup -has been sourced. This is useful for reproducing the environment of a -derivation for development. - @@ -136,50 +122,12 @@ also . +The following common options are supported: + -The following options apply to nix-build --run-env. - - - - cmd - - In the environment of the derivation, run the - shell command cmd instead of starting - an interactive shell. However, if you end the shell command with - return, you still get an interactive shell. - This can be useful for doing any additional - initialisation. - - - - regexp - - Do not build any dependencies whose store path - matches the regular expression regexp. - This option may be specified multiple times. - - - - - - If this flag is specified, the environment is - almost entirely cleared before the interactive shell is started, - so you get an environment that more closely corresponds to the - “real” Nix build. A few variables, in particular - HOME, USER and - DISPLAY, are retained. Note that - ~/.bashrc and (depending on your Bash - installation) /etc/bashrc are still sourced, - so any variables set there will affect the interactive - shell. - - - - - @@ -196,28 +144,6 @@ lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l... $ ls ./result/bin/ firefox firefox-config -To build the dependencies of the package Pan, and start an -interactive shell in which to build it: - - -$ nix-build '<nixpkgs>' --run-env -A pan -$ unpackPhase -$ cd pan-* -$ configurePhase -$ buildPhase -$ ./pan/gui/pan - - -To clear the environment first, and do some additional automatic -initialisation of the interactive shell: - - -$ nix-build '<nixpkgs>' --run-env -A pan --pure \ - --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' - - - - If a derivation has multiple outputs, nix-build will build the default (first) output. You can also build all outputs: diff --git a/doc/manual/nix-shell.xml b/doc/manual/nix-shell.xml new file mode 100644 index 000000000000..4e9735a02367 --- /dev/null +++ b/doc/manual/nix-shell.xml @@ -0,0 +1,142 @@ + + + + nix-shell + 1 + Nix + + + + + nix-shell + start an interactive shell based on a Nix expression + + + + + nix-shell + + name value + name value + + + + + + attrPath + + cmd + regexp + + paths + + + +Description + +The command nix-shell --run-env will build +the dependencies of the specified derivation, but not the derivation +itself. It will then start an interactive shell in which all +environment variables defined by the derivation have been set to their +corresponding values, and the script $stdenv/setup +has been sourced. This is useful for reproducing the environment of a +derivation for development. + + + + +Options + +All options not listed here are passed to nix-store +--realise, except for and + / which are passed to +nix-instantiate. See +also . + + + + cmd + + In the environment of the derivation, run the + shell command cmd instead of starting + an interactive shell. However, if you end the shell command with + return, you still get an interactive shell. + This can be useful for doing any additional + initialisation. + + + + regexp + + Do not build any dependencies whose store path + matches the regular expression regexp. + This option may be specified multiple times. + + + + + + If this flag is specified, the environment is + almost entirely cleared before the interactive shell is started, + so you get an environment that more closely corresponds to the + “real” Nix build. A few variables, in particular + HOME, USER and + DISPLAY, are retained. Note that + ~/.bashrc and (depending on your Bash + installation) /etc/bashrc are still sourced, + so any variables set there will affect the interactive + shell. + + + + + +The following common options are supported: + + + + + + + + +Examples + +To build the dependencies of the package Pan, and start an +interactive shell in which to build it: + + +$ nix-shell '<nixpkgs>' -A pan +$ unpackPhase +$ cd pan-* +$ configurePhase +$ buildPhase +$ ./pan/gui/pan + + +To clear the environment first, and do some additional automatic +initialisation of the interactive shell: + + +$ nix-shell '<nixpkgs>' -A pan --pure \ + --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' + + + + + + + +Environment variables + + + + + + + + + diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml index 6643b4a3b990..a1132b978ead 100644 --- a/doc/manual/release-notes.xml +++ b/doc/manual/release-notes.xml @@ -6,6 +6,43 @@ + + +
Release 1.6.0 (TBA) + + + + + The command nix-build --run-env has been + renamed to nix-shell. + + + + nix-shell now sources + $stdenv/setup inside the + interactive shell, rather than in a parent shell. This ensures + that shell functions defined by stdenv can be + used in the interactive shell. + + + + nix-shell has a new flag + to clear the environment, so you get an + environment that more closely corresponds to the “real” Nix build. + + + + + nix-shell now sets the shell prompt + (PS1) to ensure that Nix shells are distinguishable + from your regular shells. + + + + +
+ +
Release 1.5.3 (June 17, 2013) -- cgit 1.4.1