diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index eedc992a3..56be7e1b8 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 aa461d708..6abff02d9 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 61b59c1e0..969faf9d1 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 000000000..4e9735a02 --- /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 6643b4a3b..a1132b978 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) diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 1453ed9cc..d9f39aad1 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -18,6 +18,7 @@ install-exec-local: download-using-manifests.pl copy-from-other-stores.pl downlo $(INSTALL) -d $(DESTDIR)$(libexecdir)/nix/substituters $(INSTALL_PROGRAM) download-using-manifests.pl copy-from-other-stores.pl download-from-binary-cache.pl $(DESTDIR)$(libexecdir)/nix/substituters $(INSTALL) -d $(DESTDIR)$(sysconfdir)/nix + ln -sf nix-build $(DESTDIR)$(bindir)/nix-shell include ../substitute.mk diff --git a/scripts/nix-build.in b/scripts/nix-build.in index 899882952..a7f23df41 100755 --- a/scripts/nix-build.in +++ b/scripts/nix-build.in @@ -9,7 +9,7 @@ use File::Temp qw(tempdir); my $dryRun = 0; my $verbose = 0; -my $runEnv = 0; +my $runEnv = $0 =~ /nix-shell$/; my $pure = 0; my @instArgs = (); @@ -20,8 +20,10 @@ my $shell = $ENV{SHELL} || "/bin/sh"; my $envCommand = ""; # interactive shell my @envExclude = (); +my $myName = $runEnv ? "nix-shell" : "nix-build"; -my $tmpDir = tempdir("nix-build.XXXXXX", CLEANUP => 1, TMPDIR => 1) + +my $tmpDir = tempdir("$myName.XXXXXX", CLEANUP => 1, TMPDIR => 1) or die "cannot create a temporary directory"; my $outLink = "./result"; @@ -35,11 +37,11 @@ for (my $n = 0; $n < scalar @ARGV; $n++) { my $arg = $ARGV[$n]; if ($arg eq "--help") { - exec "man nix-build" or die; + exec "man $myName" or die; } elsif ($arg eq "--version") { - print "nix-build (Nix) $Nix::Config::version\n"; + print "$myName (Nix) $Nix::Config::version\n"; exit 0; } @@ -119,7 +121,7 @@ for (my $n = 0; $n < scalar @ARGV; $n++) { push @instArgs, $arg; } - elsif ($arg eq "--run-env") { + elsif ($arg eq "--run-env") { # obsolete $runEnv = 1; } @@ -164,7 +166,7 @@ foreach my $expr (@exprs) { } if ($runEnv) { - die "$0: ‘--run-env’ requires a single derivation\n" if scalar @drvPaths != 1; + die "$0: a single derivation is required\n" if scalar @drvPaths != 1; my $drvPath = readlink $drvPaths[0] or die "cannot read symlink `$drvPaths[0]'"; my $drv = derivationFromPath($drvPath); @@ -197,7 +199,7 @@ foreach my $expr (@exprs) { '[ -e $stdenv/setup ] && source $stdenv/setup; ' . ($pure ? '' : 'PATH=$PATH:$p; ') . 'set +e; ' . - 'PS1="\n\[\033[1;32m\][nix-build:\w]$\[\033[0m\] "; ' . + 'PS1="\n\[\033[1;32m\][nix-shell:\w]$\[\033[0m\] "; ' . $envCommand); exec($ENV{NIX_BUILD_SHELL} // "bash", "--rcfile", $rcfile); die;