diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/nix-build.xml | 10 | ||||
| -rw-r--r-- | doc/manual/nix-instantiate.xml | 116 | ||||
| -rw-r--r-- | doc/manual/nix-shell.xml | 22 | ||||
| -rw-r--r-- | doc/manual/opt-common.xml | 64 |
4 files changed, 126 insertions, 86 deletions
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml index 969faf9d1694..3832f5fc3450 100644 --- a/doc/manual/nix-build.xml +++ b/doc/manual/nix-build.xml @@ -164,6 +164,16 @@ $ nix-build '<nixpkgs>' -A openssl.man </screen> This will create a symlink <literal>result-man</literal>.</para> +<para>Build a Nix expression given on the command line: + +<screen> +$ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"' +$ cat ./result +bar +</screen> + +</para> + </refsection> diff --git a/doc/manual/nix-instantiate.xml b/doc/manual/nix-instantiate.xml index a3d67debe66a..a780302e1971 100644 --- a/doc/manual/nix-instantiate.xml +++ b/doc/manual/nix-instantiate.xml @@ -2,7 +2,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-nix-instantiate"> - + <refmeta> <refentrytitle>nix-instantiate</refentrytitle> <manvolnum>1</manvolnum> @@ -18,7 +18,15 @@ <refsynopsisdiv> <cmdsynopsis> <command>nix-instantiate</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/*)" /> + <group> + <arg choice='plain'><option>--parse-only</option></arg> + <arg choice='plain'> + <option>--eval-only</option> + <arg><option>--strict</option></arg> + <arg><option>--xml</option></arg> + </arg> + </group> + <arg><option>--read-write-mode</option></arg> <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> <arg> <group choice='req'> @@ -29,18 +37,14 @@ </arg> <arg><option>--add-root</option> <replaceable>path</replaceable></arg> <arg><option>--indirect</option></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--parse-only</option></arg> - <arg choice='plain'> - <option>--eval-only</option> - <arg><option>--strict</option></arg> - <arg><option>--read-write-mode</option></arg> - </arg> - <arg choice='plain'><option>--find-file</option></arg> - </group> - <arg><option>--xml</option></arg> - </arg> + <group choice='req'> + <arg choice='plain'><option>--expr</option></arg> + <arg choice='plain'><option>-E</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> + <sbr/> + <command>nix-instantiate</command> + <arg choice='plain'><option>--file-file</option></arg> <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -50,8 +54,8 @@ <para>The command <command>nix-instantiate</command> generates <link linkend="gloss-derivation">store derivations</link> from (high-level) -Nix expressions. It loads and evaluates the Nix expressions in each -of <replaceable>files</replaceable> (which defaults to +Nix expressions. It evaluates the Nix expressions in each of +<replaceable>files</replaceable> (which defaults to <replaceable>./default.nix</replaceable>). Each top-level expression should evaluate to a derivation, a list of derivations, or a set of derivations. The paths of the resulting store derivations are printed @@ -61,12 +65,6 @@ on standard output.</para> <literal>-</literal>, then a Nix expression will be read from standard input.</para> -<para>Most users and developers don’t need to use this command -(<command>nix-env</command> and <command>nix-build</command> perform -store derivation instantiation from Nix expressions automatically). -It is most commonly used for implementing new deployment -policies.</para> - <para condition="manual">See also <xref linkend="sec-common-options" /> for a list of common options.</para> @@ -86,25 +84,24 @@ policies.</para> </varlistentry> - <varlistentry><term><option>--parse-only</option></term> - + <listitem><para>Just parse the input files, and print their abstract syntax trees on standard output in ATerm format.</para></listitem> - + </varlistentry> - + <varlistentry><term><option>--eval-only</option></term> - + <listitem><para>Just parse and evaluate the input files, and print the resulting values on standard output. No instantiation of store derivations takes place.</para></listitem> - + </varlistentry> <varlistentry><term><option>--find-file</option></term> - + <listitem><para>Look up the given files in Nix’s search path (as specified by the <envar>NIX_PATH</envar> environment variable). If found, print the corresponding absolute paths on standard @@ -113,9 +110,9 @@ policies.</para> <literal>nix-instantiate --find-file nixpkgs/default.nix</literal> will print <literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem> - + </varlistentry> - + <varlistentry><term><option>--xml</option></term> <listitem><para>When used with <option>--parse-only</option> and @@ -180,19 +177,34 @@ dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib </para> +<para>You can also give a Nix expression on the command line: + +<screen> +$ nix-instantiate -E 'with import <nixpkgs> { }; hello' +/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv +</screen> + +This is equivalent to: + +<screen> +$ nix-instantiate '<nixpkgs>' -A hello +</screen> + +</para> + <para>Parsing and evaluating Nix expressions: <screen> -$ echo '"foo" + "bar"' | nix-instantiate --parse-only - -OpPlus(Str("foo"),Str("bar")) +$ nix-instantiate --parse-only -E '1 + 2' +1 + 2 -$ echo '"foo" + "bar"' | nix-instantiate --eval-only - -Str("foobar") +$ nix-instantiate --eval-only -E '1 + 2' +3 -$ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml - +$ nix-instantiate --eval-only --xml -E '1 + 2' <![CDATA[<?xml version='1.0' encoding='utf-8'?> <expr> - <string value="foobar" /> + <int value="3" /> </expr>]]></screen> </para> @@ -200,28 +212,28 @@ $ echo '"foo" + "bar"' | nix-instantiate --eval-only --xml - <para>The difference between non-strict and strict evaluation: <screen> -$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml - +$ nix-instantiate --eval-only --xml -E 'rec { x = "foo"; y = x; }' <replaceable>...</replaceable><![CDATA[ - <attr name="x"> - <string value="foo" /> - </attr> - <attr name="y"> - <unevaluated /> - </attr>]]> + <attr name="x"> + <string value="foo" /> + </attr> + <attr name="y"> + <unevaluated /> + </attr>]]> <replaceable>...</replaceable></screen> Note that <varname>y</varname> is left unevaluated (the XML representation doesn’t attempt to show non-normal forms). <screen> -$ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict - +$ nix-instantiate --eval-only --xml --strict -E 'rec { x = "foo"; y = x; }' <replaceable>...</replaceable><![CDATA[ - <attr name="x"> - <string value="foo" /> - </attr> - <attr name="y"> - <string value="foo" /> - </attr>]]> + <attr name="x"> + <string value="foo" /> + </attr> + <attr name="y"> + <string value="foo" /> + </attr>]]> <replaceable>...</replaceable></screen> </para> @@ -236,6 +248,6 @@ $ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict </variablelist> </refsection> - + </refentry> diff --git a/doc/manual/nix-shell.xml b/doc/manual/nix-shell.xml index 4b369662e2af..8178cea69fe8 100644 --- a/doc/manual/nix-shell.xml +++ b/doc/manual/nix-shell.xml @@ -61,11 +61,11 @@ the derivation attribute <programlisting> shellHook = '' - echo "Hello shell!" + echo "Hello shell" ''; </programlisting> -will cause <command>nix-shell</command> to print <literal>Hello shell!</literal>.</para> +will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para> </refsection> @@ -132,11 +132,11 @@ interactive shell in which to build it: <screen> $ nix-shell '<nixpkgs>' -A pan -$ unpackPhase -$ cd pan-* -$ configurePhase -$ buildPhase -$ ./pan/gui/pan +[nix-shell]$ unpackPhase +[nix-shell]$ cd pan-* +[nix-shell]$ configurePhase +[nix-shell]$ buildPhase +[nix-shell]$ ./pan/gui/pan </screen> To clear the environment first, and do some additional automatic @@ -147,6 +147,14 @@ $ nix-shell '<nixpkgs>' -A pan --pure \ --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' </screen> +Nix expressions can also be given on the command line. For instance, +the following starts a shell containing the packages +<literal>sqlite</literal> and <literal>libX11</literal>: + +<screen> +$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""' +</screen> + </para> </refsection> diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml index a877b536a5c7..f8584f4d62ed 100644 --- a/doc/manual/opt-common.xml +++ b/doc/manual/opt-common.xml @@ -8,15 +8,15 @@ <variablelist xml:id="opt-common"> <varlistentry><term><option>--help</option></term> - + <listitem><para>Prints out a summary of the command syntax and exits.</para></listitem> - + </varlistentry> <varlistentry><term><option>--version</option></term> - + <listitem><para>Prints out the Nix version number on standard output and exits.</para></listitem> </varlistentry> @@ -26,7 +26,7 @@ <term><option>-v</option></term> <listitem> - + <para>Increases the level of verbosity of diagnostic messages printed on standard error. For each Nix operation, the information printed on standard output is well-defined; any diagnostic @@ -37,18 +37,18 @@ following verbosity levels exist:</para> <variablelist> - + <varlistentry><term>0</term> <listitem><para>“Errors only”: only print messages explaining why the Nix invocation failed.</para></listitem> </varlistentry> - + <varlistentry><term>1</term> <listitem><para>“Informational”: print <emphasis>useful</emphasis> messages about what Nix is doing. This is the default.</para></listitem> </varlistentry> - + <varlistentry><term>2</term> <listitem><para>“Talkative”: print more informational messages.</para></listitem> @@ -68,11 +68,11 @@ <listitem><para>“Vomit”: print vast amounts of debug information.</para></listitem> </varlistentry> - + </variablelist> </listitem> - + </varlistentry> @@ -85,7 +85,7 @@ builder's standard output and error are always written to a log file in <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem> - + </varlistentry> @@ -99,7 +99,7 @@ configuration setting, which itself defaults to <literal>1</literal>. A higher value is useful on SMP systems or to exploit I/O latency.</para></listitem> - + </varlistentry> @@ -117,7 +117,7 @@ configuration setting, if set, or <literal>1</literal> otherwise. The value <literal>0</literal> means that the builder should use all available CPU cores in the system.</para></listitem> - + </varlistentry> @@ -151,7 +151,7 @@ derivation itself. Without this option, Nix stops if any build fails (except for builds of substitutes), possibly killing builds in progress (in case of parallel or distributed builds).</para></listitem> - + </varlistentry> @@ -188,7 +188,7 @@ resources).</para> </listitem> - + </varlistentry> @@ -197,7 +197,7 @@ <listitem><para>When this option is used, no attempt is made to open the Nix database. Most Nix operations do need database access, so those operations will fail.</para></listitem> - + </varlistentry> @@ -247,12 +247,12 @@ </varlistentry> - </variablelist> - + </variablelist> + </para> </listitem> - + </varlistentry> @@ -310,10 +310,10 @@ <varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option> <replaceable>attrPath</replaceable></term> - <listitem><para>In <command>nix-env</command>, - <command>nix-instantiate</command> and <command>nix-build</command>, - <option>--attr</option> allows you to select an attribute from the - top-level Nix expression being evaluated. The <emphasis>attribute + <listitem><para>Select an attribute from the top-level Nix + expression being evaluated. (<command>nix-env</command>, + <command>nix-instantiate</command>, <command>nix-build</command> and + <command>nix-shell</command> only.) The <emphasis>attribute path</emphasis> <replaceable>attrPath</replaceable> is a sequence of attribute names separated by dots. For instance, given a top-level Nix expression <replaceable>e</replaceable>, the attribute path @@ -333,8 +333,18 @@ </varlistentry> +<varlistentry><term><option>--expr</option> / <option>-E</option></term> + + <listitem><para>Interpret the command line arguments as a list of + Nix expressions to be parsed and evaluated, rather than as a list + of file names of Nix expressions. + (<command>nix-instantiate</command>, <command>nix-build</command> + and <command>nix-shell</command> only.)</para></listitem> + +</varlistentry> + <varlistentry><term><option>--show-trace</option></term> - + <listitem><para>Causes Nix to print out a stack trace in case of Nix expression evaluation errors.</para></listitem> @@ -342,23 +352,23 @@ <varlistentry><term><option>-I</option> <replaceable>path</replaceable></term> - + <listitem><para>Add a path to the Nix expression search path. This option may be given multiple times. See the <envar>NIX_PATH</envar> environment variable for information on the semantics of the Nix search path. Paths added through <option>-I</option> take precedence over <envar>NIX_PATH</envar>.</para></listitem> - + </varlistentry> <varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - + <listitem><para>Set the Nix configuration option <replaceable>name</replaceable> to <replaceable>value</replaceable>. This overrides settings in the Nix configuration file (see <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem> - + </varlistentry> |