diff options
| -rw-r--r-- | doc/manual/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 17 | ||||
| -rw-r--r-- | doc/manual/nix-build.xml | 78 | ||||
| -rw-r--r-- | doc/manual/nix-shell.xml | 142 | ||||
| -rw-r--r-- | doc/manual/release-notes.xml | 37 | ||||
| -rw-r--r-- | scripts/Makefile.am | 1 | ||||
| -rwxr-xr-x | scripts/nix-build.in | 16 |
7 files changed, 201 insertions, 92 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index eedc992a38..56be7e1b88 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 aa461d7081..6abff02d9e 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -19,15 +19,15 @@ </author> <copyright> - <year>2004-2012</year> + <year>2004-2013</year> <holder>Eelco Dolstra</holder> </copyright> - <date>May 2012</date> - + <date>July 2013</date> + </info> - + <xi:include href="introduction.xml" /> <xi:include href="quick-start.xml" /> <xi:include href="installation.xml" /> @@ -40,17 +40,18 @@ <title>Command Reference</title> <xi:include href="opt-common.xml" /> <xi:include href="env-common.xml" /> - + <section> <title>Main commands</title> <xi:include href="nix-env.xml" /> <xi:include href="nix-instantiate.xml" /> <xi:include href="nix-store.xml" /> </section> - + <section> <title>Utilities</title> <xi:include href="nix-build.xml" /> + <xi:include href="nix-shell.xml" /> <xi:include href="nix-channel.xml" /> <xi:include href="nix-collect-garbage.xml" /> <xi:include href="nix-copy-closure.xml" /> @@ -66,7 +67,7 @@ <title>Files</title> <xi:include href="conf-file.xml" /> </section> - + </appendix> <xi:include href="troubleshooting.xml" /> @@ -78,5 +79,5 @@ <xi:include href="release-notes.xml" xpointer="xmlns(x=http://docbook.org/ns/docbook)xpointer(x:article/x:section)" /> </appendix> - + </book> diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index 61b59c1e0a..969faf9d16 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -38,12 +38,6 @@ </group> <replaceable>outlink</replaceable> </arg> - <arg> - <option>--run-env</option> - <arg><option>--command</option> <replaceable>cmd</replaceable></arg> - <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg> - <arg><option>--pure</option></arg> - </arg> <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -76,14 +70,6 @@ a root of the Nix garbage collector. This root disappears automatically when the <filename>result</filename> symlink is deleted or renamed. So don’t rename the symlink.</para></warning> -<para>The subcommand <command>nix-build --run-env</command> 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 <literal>$stdenv/setup</literal> -has been sourced. This is useful for reproducing the environment of a -derivation for development.</para> - </refsection> @@ -136,50 +122,12 @@ also <xref linkend="sec-common-options" />.</phrase></para> </variablelist> +<para>The following common options are supported:</para> + <variablelist condition="manpage"> <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> </variablelist> -<para>The following options apply to <command>nix-build --run-env</command>.</para> - -<variablelist> - - <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> - - <listitem><para>In the environment of the derivation, run the - shell command <replaceable>cmd</replaceable> instead of starting - an interactive shell. However, if you end the shell command with - <literal>return</literal>, you still get an interactive shell. - This can be useful for doing any additional - initialisation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term> - - <listitem><para>Do not build any dependencies whose store path - matches the regular expression <replaceable>regexp</replaceable>. - This option may be specified multiple times.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--pure</option></term> - - <listitem><para>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 - <envar>HOME</envar>, <envar>USER</envar> and - <envar>DISPLAY</envar>, are retained. Note that - <filename>~/.bashrc</filename> and (depending on your Bash - installation) <filename>/etc/bashrc</filename> are still sourced, - so any variables set there will affect the interactive - shell.</para></listitem> - - </varlistentry> - -</variablelist> - </refsection> @@ -196,28 +144,6 @@ lrwxrwxrwx <replaceable>...</replaceable> result -> /nix/store/d18hyl92g30l... $ ls ./result/bin/ firefox firefox-config</screen> -<para>To build the dependencies of the package Pan, and start an -interactive shell in which to build it: - -<screen> -$ nix-build '<nixpkgs>' --run-env -A pan -$ unpackPhase -$ cd pan-* -$ configurePhase -$ buildPhase -$ ./pan/gui/pan -</screen> - -To clear the environment first, and do some additional automatic -initialisation of the interactive shell: - -<screen> -$ nix-build '<nixpkgs>' --run-env -A pan --pure \ - --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' -</screen> - -</para> - <para>If a derivation has multiple outputs, <command>nix-build</command> 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 0000000000..4e9735a023 --- /dev/null +++ b/doc/manual/nix-shell.xml @@ -0,0 +1,142 @@ +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="sec-nix-shell"> + +<refmeta> + <refentrytitle>nix-shell</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">Nix</refmiscinfo> + <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> +</refmeta> + +<refnamediv> + <refname>nix-shell</refname> + <refpurpose>start an interactive shell based on a Nix expression</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>nix-shell</command> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> + <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> + <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--attr</option></arg> + <arg choice='plain'><option>-A</option></arg> + </group> + <replaceable>attrPath</replaceable> + </arg> + <arg><option>--command</option> <replaceable>cmd</replaceable></arg> + <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg> + <arg><option>--pure</option></arg> + <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsection><title>Description</title> + +<para>The command <command>nix-shell --run-env</command> 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 <literal>$stdenv/setup</literal> +has been sourced. This is useful for reproducing the environment of a +derivation for development.</para> + +</refsection> + + +<refsection><title>Options</title> + +<para>All options not listed here are passed to <command>nix-store +--realise</command>, except for <option>--arg</option> and +<option>--attr</option> / <option>-A</option> which are passed to +<command>nix-instantiate</command>. <phrase condition="manual">See +also <xref linkend="sec-common-options" />.</phrase></para> + +<variablelist> + + <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> + + <listitem><para>In the environment of the derivation, run the + shell command <replaceable>cmd</replaceable> instead of starting + an interactive shell. However, if you end the shell command with + <literal>return</literal>, you still get an interactive shell. + This can be useful for doing any additional + initialisation.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term> + + <listitem><para>Do not build any dependencies whose store path + matches the regular expression <replaceable>regexp</replaceable>. + This option may be specified multiple times.</para></listitem> + + </varlistentry> + + <varlistentry><term><option>--pure</option></term> + + <listitem><para>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 + <envar>HOME</envar>, <envar>USER</envar> and + <envar>DISPLAY</envar>, are retained. Note that + <filename>~/.bashrc</filename> and (depending on your Bash + installation) <filename>/etc/bashrc</filename> are still sourced, + so any variables set there will affect the interactive + shell.</para></listitem> + + </varlistentry> + +</variablelist> + +<para>The following common options are supported:</para> + +<variablelist condition="manpage"> + <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> +</variablelist> + +</refsection> + + +<refsection><title>Examples</title> + +<para>To build the dependencies of the package Pan, and start an +interactive shell in which to build it: + +<screen> +$ nix-shell '<nixpkgs>' -A pan +$ unpackPhase +$ cd pan-* +$ configurePhase +$ buildPhase +$ ./pan/gui/pan +</screen> + +To clear the environment first, and do some additional automatic +initialisation of the interactive shell: + +<screen> +$ nix-shell '<nixpkgs>' -A pan --pure \ + --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' +</screen> + +</para> + +</refsection> + + +<refsection condition="manpage"><title>Environment variables</title> + +<variablelist> + <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> +</variablelist> + +</refsection> + + +</refentry> diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml index 6643b4a3b9..a1132b978e 100644 --- a/doc/manual/release-notes.xml +++ b/doc/manual/release-notes.xml @@ -8,6 +8,43 @@ <!--==================================================================--> +<section xml:id="ssec-relnotes-1.6.0"><title>Release 1.6.0 (TBA)</title> + +<itemizedlist> + + <listitem> + <para>The command <command>nix-build --run-env</command> has been + renamed to <command>nix-shell</command>.</para> + </listitem> + + <listitem> + <para><command>nix-shell</command> now sources + <filename>$stdenv/setup</filename> <emphasis>inside</emphasis> the + interactive shell, rather than in a parent shell. This ensures + that shell functions defined by <literal>stdenv</literal> can be + used in the interactive shell.</para> + </listitem> + + <listitem> + <para><command>nix-shell</command> has a new flag + <option>--pure</option> to clear the environment, so you get an + environment that more closely corresponds to the “real” Nix build. + </para> + </listitem> + + <listitem> + <para><command>nix-shell</command> now sets the shell prompt + (<envar>PS1</envar>) to ensure that Nix shells are distinguishable + from your regular shells.</para> + </listitem> + +</itemizedlist> + +</section> + + +<!--==================================================================--> + <section xml:id="ssec-relnotes-1.5.3"><title>Release 1.5.3 (June 17, 2013)</title> <para>This is primarily a bug fix release. The following changes are diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 1453ed9cc1..d9f39aad1b 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 899882952b..a7f23df41a 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; |