diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/advanced-topics/distributed-builds.xml | 15 | ||||
| -rw-r--r-- | doc/manual/command-ref/conf-file.xml | 82 | ||||
| -rw-r--r-- | doc/manual/command-ref/env-common.xml | 133 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-env.xml | 2 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-instantiate.xml | 18 | ||||
| -rw-r--r-- | doc/manual/expressions/builtins.xml | 47 | ||||
| -rw-r--r-- | doc/manual/introduction/about-nix.xml | 8 | ||||
| -rw-r--r-- | doc/manual/introduction/quick-start.xml | 2 | ||||
| -rw-r--r-- | doc/manual/release-notes/rl-1.11.xml | 7 | ||||
| -rw-r--r-- | doc/manual/release-notes/rl-1.12.xml | 7 |
10 files changed, 110 insertions, 211 deletions
diff --git a/doc/manual/advanced-topics/distributed-builds.xml b/doc/manual/advanced-topics/distributed-builds.xml index d5bc1c592553..1957e1105e68 100644 --- a/doc/manual/advanced-topics/distributed-builds.xml +++ b/doc/manual/advanced-topics/distributed-builds.xml @@ -22,10 +22,7 @@ will call whenever it wants to build a derivation. The build hook will perform it in the usual way if possible, or it can accept it, in which case it is responsible for somehow getting the inputs of the build to another machine, doing the build there, and getting the -results back. The details of the build hook protocol are described in -the documentation of the <link -linkend="envar-build-hook"><envar>NIX_BUILD_HOOK</envar> -variable</link>.</para> +results back.</para> <example xml:id='ex-remote-systems'><title>Remote machine configuration: <filename>remote-systems.conf</filename></title> @@ -103,14 +100,6 @@ requiredSystemFeatures = [ "kvm" ]; </orderedlist> -You should also set up the environment variable -<envar>NIX_CURRENT_LOAD</envar> to point at a directory (e.g., -<filename>/var/run/nix/current-load</filename>) that -<filename>build-remote</filename> uses to remember how many builds -it is currently executing remotely. It doesn't look at the actual -load on the remote machine, so if you have multiple instances of Nix -running, they should use the same <envar>NIX_CURRENT_LOAD</envar> -file. Maybe in the future <filename>build-remote</filename> will -look at the actual remote load.</para> +</para> </chapter> diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml index 6952829e8f71..616983bc7f0e 100644 --- a/doc/manual/command-ref/conf-file.xml +++ b/doc/manual/command-ref/conf-file.xml @@ -17,13 +17,32 @@ <refsection><title>Description</title> -<para>A number of persistent settings of Nix are stored in the file -<filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename> or -<filename>$NIX_CONF_DIR/nix.conf</filename> if <envar>NIX_CONF_DIR</envar> is set. -This file is a list of <literal><replaceable>name</replaceable> = +<para>Nix reads settings from two configuration files:</para> + +<itemizedlist> + + <listitem> + <para>The system-wide configuration file + <filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename> + (i.e. <filename>/etc/nix/nix.conf</filename> on most systems), or + <filename>$NIX_CONF_DIR/nix.conf</filename> if + <envar>NIX_CONF_DIR</envar> is set.</para> + </listitem> + + <listitem> + <para>The user configuration file + <filename>$XDG_CONFIG_HOME/nix/nix.conf</filename>, or + <filename>~/.config/nix/nix.conf</filename> if + <envar>XDG_CONFIG_HOME</envar> is not set.</para> + </listitem> + +</itemizedlist> + +<para>The configuration files consist of +<literal><replaceable>name</replaceable> = <replaceable>value</replaceable></literal> pairs, one per line. -Comments start with a <literal>#</literal> character. Here is an example -configuration file:</para> +Comments start with a <literal>#</literal> character. Here is an +example configuration file:</para> <programlisting> gc-keep-outputs = true # Nice for developers @@ -31,8 +50,9 @@ gc-keep-derivations = true # Idem env-keep-derivations = false </programlisting> -<para>You can override settings using the <option>--option</option> -flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para> +<para>You can override settings on the command line using the +<option>--option</option> flag, e.g. <literal>--option gc-keep-outputs +false</literal>.</para> <para>The following settings are currently available: @@ -334,25 +354,16 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para> </varlistentry> - <varlistentry><term><literal>use-binary-caches</literal></term> - - <listitem><para>If set to <literal>true</literal> (the default), - Nix will check the binary caches specified by - <option>binary-caches</option> and related options to obtain - binary substitutes.</para></listitem> - - </varlistentry> + <varlistentry><term><literal>substituters</literal></term> - - <varlistentry><term><literal>binary-caches</literal></term> - - <listitem><para>A list of URLs of binary caches, separated by + <listitem><para>A list of URLs of substituters, separated by whitespace. The default is <literal>https://cache.nixos.org</literal>.</para></listitem> </varlistentry> + <!-- <varlistentry><term><literal>binary-caches-files</literal></term> <listitem><para>A list of names of files that will be read to @@ -365,28 +376,28 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para> option to read files created by untrusted users!</para></listitem> </varlistentry> + --> - <varlistentry><term><literal>trusted-binary-caches</literal></term> + <varlistentry><term><literal>trusted-substituters</literal></term> - <listitem><para>A list of URLs of binary caches, separated by + <listitem><para>A list of URLs of substituters, separated by whitespace. These are not used by default, but can be enabled by users of the Nix daemon by specifying <literal>--option - binary-caches <replaceable>urls</replaceable></literal> on the + substituters <replaceable>urls</replaceable></literal> on the command line. Unprivileged users are only allowed to pass a - subset of the URLs listed in <literal>binary-caches</literal> and - <literal>trusted-binary-caches</literal>.</para></listitem> + subset of the URLs listed in <literal>substituters</literal> and + <literal>trusted-substituters</literal>.</para></listitem> </varlistentry> - <varlistentry><term><literal>extra-binary-caches</literal></term> + <varlistentry><term><literal>extra-substituters</literal></term> <listitem><para>Additional binary caches appended to those - specified in <option>binary-caches</option> and - <option>binary-caches-files</option>. When used by unprivileged - users, untrusted binary caches (i.e. those not listed in - <option>trusted-binary-caches</option>) are silently + specified in <option>substituters</option>. When used by + unprivileged users, untrusted substituters (i.e. those not listed + in <option>trusted-substituters</option>) are silently ignored.</para></listitem> </varlistentry> @@ -413,7 +424,7 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para> </varlistentry> - <varlistentry><term><literal>binary-caches-parallel-connections</literal></term> + <varlistentry><term><literal>http-connections</literal></term> <listitem><para>The maximum number of parallel TCP connections used to fetch files from binary caches and by other downloads. It @@ -422,15 +433,6 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para> </varlistentry> - <varlistentry><term><literal>verify-https-binary-caches</literal></term> - - <listitem><para>Whether HTTPS binary caches are required to have a - certificate that can be verified. Defaults to - <literal>true</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>netrc-file</literal></term> <listitem><para>If set to an absolute path to a <filename>netrc</filename> diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml index c757cb17bd10..a83aeaf2e575 100644 --- a/doc/manual/command-ref/env-common.xml +++ b/doc/manual/command-ref/env-common.xml @@ -148,139 +148,6 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen> </varlistentry> -<varlistentry xml:id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term> - - <listitem> - - <para>Specifies the location of the <emphasis>build hook</emphasis>, - which is a program (typically some script) that Nix will call - whenever it wants to build a derivation. This is used to implement - distributed builds<phrase condition="manual"> (see <xref - linkend="chap-distributed-builds" />)</phrase>.</para> - - <!-- - The protocol by - which the calling Nix process and the build hook communicate is as - follows. - - <para>The build hook is called with the following command-line - arguments: - - <orderedlist> - - <listitem><para>A boolean value <literal>0</literal> or - <literal>1</literal> specifying whether Nix can locally execute - more builds, as per the <link - linkend="opt-max-jobs"><option>- -max-jobs</option> option</link>. - The purpose of this argument is to allow the hook to not have to - maintain bookkeeping for the local machine.</para></listitem> - - <listitem><para>The Nix platform identifier for the local machine - (e.g., <literal>i686-linux</literal>).</para></listitem> - - <listitem><para>The Nix platform identifier for the derivation, - i.e., its <link linkend="attr-system"><varname>system</varname> - attribute</link>.</para></listitem> - - <listitem><para>The store path of the derivation.</para></listitem> - - </orderedlist> - - </para> - - <para>On the basis of this information, and whatever persistent - state the build hook keeps about other machines and their current - load, it has to decide what to do with the build. It should print - out on standard error one of the following responses (terminated by - a newline, <literal>"\n"</literal>): - - <variablelist> - - <varlistentry><term><literal># decline</literal></term> - - <listitem><para>The build hook is not willing or able to perform - the build; the calling Nix process should do the build itself, - if possible.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal># postpone</literal></term> - - <listitem><para>The build hook cannot perform the build now, but - can do so in the future (e.g., because all available build slots - on remote machines are in use). The calling Nix process should - postpone this build until at least one currently running build - has terminated.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal># accept</literal></term> - - <listitem><para>The build hook has accepted the - build.</para></listitem> - - </varlistentry> - - </variablelist> - - </para> - - <para>After sending <literal># accept</literal>, the hook should - read one line from standard input, which will be the string - <literal>okay</literal>. It can then proceed with the build. - Before sending <literal>okay</literal>, Nix will store in the hook’s - current directory a number of text files that contain information - about the derivation: - - <variablelist> - - <varlistentry><term><filename>inputs</filename></term> - - <listitem><para>The set of store paths that are inputs to the - build process (one per line). These have to be copied - <emphasis>to</emphasis> the remote machine (in addition to the - store derivation itself).</para></listitem> - - </varlistentry> - - <varlistentry><term><filename>outputs</filename></term> - - <listitem><para>The set of store paths that are outputs of the - derivation (one per line). These have to be copied - <emphasis>from</emphasis> the remote machine if the build - succeeds.</para></listitem> - - </varlistentry> - - <varlistentry><term><filename>references</filename></term> - - <listitem><para>The reference graph of the inputs, in the format - accepted by the command <command>nix-store - - -register-validity</command>. It is necessary to run this - command on the remote machine after copying the inputs to inform - Nix on the remote machine that the inputs are valid - paths.</para></listitem> - - </varlistentry> - - </variablelist> - - </para> - - <para>The hook should copy the inputs to the remote machine, - register the validity of the inputs, perform the remote build, and - copy the outputs back to the local machine. An exit code other than - <literal>0</literal> indicates that the hook has failed. An exit - code equal to 100 means that the remote build failed (as opposed to, - e.g., a network error).</para> - --> - - </listitem> - - -</varlistentry> - - <varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term> <listitem><para>This variable should be set to diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml index 85f10e0760bc..8462cf8a0270 100644 --- a/doc/manual/command-ref/nix-env.xml +++ b/doc/manual/command-ref/nix-env.xml @@ -1136,7 +1136,7 @@ user environment elements, etc. --> <listitem><para>Print all of the meta-attributes of the derivation. This option is only available with - <option>--xml</option>.</para></listitem> + <option>--xml</option> or <option>--json</option>.</para></listitem> </varlistentry> diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml index 1e556c7ed7c4..3d03358bea3f 100644 --- a/doc/manual/command-ref/nix-instantiate.xml +++ b/doc/manual/command-ref/nix-instantiate.xml @@ -117,21 +117,19 @@ input.</para> <varlistentry><term><option>--xml</option></term> - <listitem><para>When used with <option>--parse</option> and - <option>--eval</option>, print the resulting expression as an - XML representation of the abstract syntax tree rather than as an - ATerm. The schema is the same as that used by the <link - linkend="builtin-toXML"><function>toXML</function> - built-in</link>.</para></listitem> + <listitem><para>When used with <option>--eval</option>, print the resulting + value as an XML representation of the abstract syntax tree rather than as + an ATerm. The schema is the same as that used by the <link + linkend="builtin-toXML"><function>toXML</function> built-in</link>. + </para></listitem> </varlistentry> <varlistentry><term><option>--json</option></term> - <listitem><para>When used with <option>--parse</option> and - <option>--eval</option>, print the resulting expression as an - JSON representation of the abstract syntax tree rather than as an - ATerm.</para></listitem> + <listitem><para>When used with <option>--eval</option>, print the resulting + value as an JSON representation of the abstract syntax tree rather + than as an ATerm.</para></listitem> </varlistentry> diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index e9baff65961a..f46a93ae0d5d 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -65,7 +65,7 @@ available as <function>builtins.derivation</function>.</para> <replaceable>set</replaceable></term> <listitem><para>Return the names of the attributes in the set - <replaceable>set</replaceable> in a sorted list. For instance, + <replaceable>set</replaceable> in an alphabetically sorted list. For instance, <literal>builtins.attrNames { y = 1; x = "foo"; }</literal> evaluates to <literal>[ "x" "y" ]</literal>.</para></listitem> @@ -213,10 +213,11 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting> <varlistentry><term><function>builtins.match</function> <replaceable>regex</replaceable> <replaceable>str</replaceable></term> - <listitem><para>Returns a list if - <replaceable>regex</replaceable> matches - <replaceable>str</replaceable> precisely, otherwise returns <literal>null</literal>. - Each item in the list is a regex group. + <listitem><para>Returns a list if the <link + xlink:href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04">extended + POSIX regular expression</link> <replaceable>regex</replaceable> + matches <replaceable>str</replaceable> precisely, otherwise returns + <literal>null</literal>. Each item in the list is a regex group. <programlisting> builtins.match "ab" "abc" @@ -236,6 +237,11 @@ builtins.match "a(b)(c)" "abc" Evaluates to <literal>[ "b" "c" ]</literal>. +<programlisting> +builtins.match "[[:space:]]+([[:upper:]]+)[[:space:]]+" " FOO " +</programlisting> + +Evaluates to <literal>[ "foo" ]</literal>. </para></listitem> </varlistentry> @@ -292,6 +298,24 @@ with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixo stdenv.mkDerivation { … } </programlisting> + Note that when obtaining the hash with <varname>nix-prefetch-url + </varname> the option <varname>--unpack</varname> is required. + </para> + + <para>This function can also verify the contents against a hash. + In that case, the function takes a set instead of a URL. The set + requires the attribute <varname>url</varname> and the attribute + <varname>sha256</varname>, e.g. + +<programlisting> +with import (fetchTarball { + url = https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz; + sha256 = "1jppksrfvbk5ypiqdz4cddxdl8z6zyzdb2srq8fcffr327ld5jj2"; +}) {}; + +stdenv.mkDerivation { … } +</programlisting> + </para> <para>This function is not available if <link @@ -1163,6 +1187,19 @@ stdenv.mkDerivation (rec { </varlistentry> + <varlistentry><term><function>builtins.tryEval</function> + <replaceable>e</replaceable></term> + + <listitem><para>Try to evaluate <replaceable>e</replaceable>. + Return a set containing the attributes <literal>success</literal> + (<literal>true</literal> if <replaceable>e</replaceable> evaluated + successfully, <literal>false</literal> if an error was thrown) and + <literal>value</literal>, equalling <replaceable>e</replaceable> + if successful and <literal>false</literal> otherwise. + </para></listitem> + + </varlistentry> + <varlistentry><term><function>builtins.typeOf</function> <replaceable>e</replaceable></term> diff --git a/doc/manual/introduction/about-nix.xml b/doc/manual/introduction/about-nix.xml index 0c58984ac489..be065da3eb2d 100644 --- a/doc/manual/introduction/about-nix.xml +++ b/doc/manual/introduction/about-nix.xml @@ -93,7 +93,7 @@ time window in which the package has some files from the old version and some files from the new version — which would be bad because a program might well crash if it’s started during that period.</para> -<para>And since package aren’t overwritten, the old versions are still +<para>And since packages aren’t overwritten, the old versions are still there after an upgrade. This means that you can <emphasis>roll back</emphasis> to the old version:</para> @@ -261,6 +261,12 @@ xlink:href="http://nixos.org/">NixOS homepage</link>.</para> xlink:href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">GNU LGPLv2.1 or (at your option) any later version</link>.</para> +<para>Nix uses the <link +xlink:href="https://github.com/antirez/linenoise">linenoise +library</link>, which has the following license:</para> + +<programlisting><xi:include href="../../../src/linenoise/LICENSE" parse="text" /></programlisting> + </simplesect> diff --git a/doc/manual/introduction/quick-start.xml b/doc/manual/introduction/quick-start.xml index 5ae9f6ad543b..aa239b7538b4 100644 --- a/doc/manual/introduction/quick-start.xml +++ b/doc/manual/introduction/quick-start.xml @@ -40,7 +40,7 @@ libxslt-1.1.28 <step><para>Install some packages from the channel: <screen> -$ nix-env -i hello <replaceable>...</replaceable> </screen> +$ nix-env -i hello</screen> This should download pre-built packages; it should not build them locally (if it does, something went wrong).</para></step> diff --git a/doc/manual/release-notes/rl-1.11.xml b/doc/manual/release-notes/rl-1.11.xml index efb03d61393f..fe422dd1f893 100644 --- a/doc/manual/release-notes/rl-1.11.xml +++ b/doc/manual/release-notes/rl-1.11.xml @@ -122,13 +122,6 @@ $ diffoscope /nix/store/11a27shh6n2i…-zlib-1.2.8 /nix/store/11a27shh6n2i…-zl </listitem> <listitem> - <para>The Nix language now supports floating point numbers. They are - based on regular C++ <literal>float</literal> and compatible with - existing integers and number-related operations. Export and import to and - from JSON and XML works, too. - </para> - </listitem> - <listitem> <para>All "chroot"-containing strings got renamed to "sandbox". In particular, some Nix options got renamed, but the old names are still accepted as lower-priority aliases. diff --git a/doc/manual/release-notes/rl-1.12.xml b/doc/manual/release-notes/rl-1.12.xml index d6864b3f55d1..b7f45fc44a36 100644 --- a/doc/manual/release-notes/rl-1.12.xml +++ b/doc/manual/release-notes/rl-1.12.xml @@ -17,6 +17,13 @@ have write access to the Nix database.</para> </listitem> + <listitem> + <para>The Nix language now supports floating point numbers. They are + based on regular C++ <literal>float</literal> and compatible with + existing integers and number-related operations. Export and import to and + from JSON and XML works, too. + </para> + </listitem> </itemizedlist> <para>This release has contributions from TBD.</para> |