diff options
Diffstat (limited to 'doc/manual')
| -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 |
5 files changed, 191 insertions, 85 deletions
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 @@ </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 61b59c1e0adc..969faf9d1694 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 000000000000..4e9735a02367 --- /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 6643b4a3b990..a1132b978ead 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 |