diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/advanced-topics/advanced-topics.xml | 1 | ||||
| -rw-r--r-- | doc/manual/advanced-topics/distributed-builds.xml | 1 | ||||
| -rw-r--r-- | doc/manual/command-ref/conf-file.xml | 12 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-store.xml | 2 | ||||
| -rw-r--r-- | doc/manual/expressions/advanced-attributes.xml | 34 | ||||
| -rw-r--r-- | doc/manual/expressions/builtins.xml | 82 | ||||
| -rw-r--r-- | doc/manual/expressions/language-constructs.xml | 2 | ||||
| -rw-r--r-- | doc/manual/glossary/glossary.xml | 3 | ||||
| -rw-r--r-- | doc/manual/hacking.xml | 2 | ||||
| -rw-r--r-- | doc/manual/installation/env-variables.xml | 4 | ||||
| -rw-r--r-- | doc/manual/installation/installing-binary.xml | 178 | ||||
| -rw-r--r-- | doc/manual/installation/prerequisites-source.xml | 3 | ||||
| -rw-r--r-- | doc/manual/installation/supported-platforms.xml | 2 | ||||
| -rw-r--r-- | doc/manual/installation/upgrading.xml | 21 | ||||
| -rw-r--r-- | doc/manual/manual.xml | 1 | ||||
| -rw-r--r-- | doc/manual/release-notes/rl-2.1.xml | 88 |
16 files changed, 381 insertions, 55 deletions
diff --git a/doc/manual/advanced-topics/advanced-topics.xml b/doc/manual/advanced-topics/advanced-topics.xml index 338aa6f3a238..b710f9f2b518 100644 --- a/doc/manual/advanced-topics/advanced-topics.xml +++ b/doc/manual/advanced-topics/advanced-topics.xml @@ -1,6 +1,7 @@ <part xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="part-advanced-topics" version="5.0"> <title>Advanced Topics</title> diff --git a/doc/manual/advanced-topics/distributed-builds.xml b/doc/manual/advanced-topics/distributed-builds.xml index 20fd6a0cfb0d..bbb573e35400 100644 --- a/doc/manual/advanced-topics/distributed-builds.xml +++ b/doc/manual/advanced-topics/distributed-builds.xml @@ -81,6 +81,7 @@ or a newline, e.g. <para>Each machine specification consists of the following elements, separated by spaces. Only the first element is required. +To leave a field at its default, set it to <literal>-</literal>. <orderedlist> diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml index 1865bb37c860..26fe58d043b7 100644 --- a/doc/manual/command-ref/conf-file.xml +++ b/doc/manual/command-ref/conf-file.xml @@ -437,7 +437,10 @@ builtins.fetchurl { <listitem><para>This option defines the maximum number of jobs that Nix will try to build in parallel. The default is <literal>1</literal>. The special value <literal>auto</literal> - causes Nix to use the number of CPUs in your system. It can be + causes Nix to use the number of CPUs in your system. <literal>0</literal> + is useful when using remote builders to prevent any local builds (except for + <literal>preferLocalBuild</literal> derivation attribute which executes locally + regardless). It can be overridden using the <option linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>) command line switch.</para></listitem> @@ -524,7 +527,12 @@ password <replaceable>my-password</replaceable> For the exact syntax, see <link xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the - <literal>curl</literal> documentation.</link></para></listitem> + <literal>curl</literal> documentation.</link></para> + + <note><para>This must be an absolute path, and <literal>~</literal> + is not resolved. For example, <filename>~/.netrc</filename> won't + resolve to your home directory's <filename>.netrc</filename>.</para></note> + </listitem> </varlistentry> diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml index 5fff64a18f93..c827d85b3815 100644 --- a/doc/manual/command-ref/nix-store.xml +++ b/doc/manual/command-ref/nix-store.xml @@ -275,7 +275,7 @@ as a means of providing Nix store access to a restricted ssh user. <listitem><para>Allow the connected client to request the realization of derivations. In effect, this can be used to make the host act - as a build slave.</para></listitem> + as a remote builder.</para></listitem> </varlistentry> diff --git a/doc/manual/expressions/advanced-attributes.xml b/doc/manual/expressions/advanced-attributes.xml index dfd013b5cf31..9422e82ff362 100644 --- a/doc/manual/expressions/advanced-attributes.xml +++ b/doc/manual/expressions/advanced-attributes.xml @@ -50,6 +50,40 @@ allowedRequisites = [ foobar ]; </varlistentry> + <varlistentry><term><varname>disallowedReferences</varname></term> + + <listitem><para>The optional attribute + <varname>disallowedReferences</varname> specifies a list of illegal + references (dependencies) of the output of the builder. For + example, + +<programlisting> +disallowedReferences = [ foo ]; +</programlisting> + + enforces that the output of a derivation cannot have a direct runtime + dependencies on the derivation <varname>foo</varname>.</para></listitem> + + </varlistentry> + + + <varlistentry><term><varname>disallowedRequisites</varname></term> + + <listitem><para>This attribute is similar to + <varname>disallowedReferences</varname>, but it specifies illegal + requisites for the whole closure, so all the dependencies + recursively. For example, + +<programlisting> +disallowedRequisites = [ foobar ]; +</programlisting> + + enforces that the output of a derivation cannot have any + runtime dependency on <varname>foobar</varname> or any other derivation + depending recursively on <varname>foobar</varname>.</para></listitem> + + </varlistentry> + <varlistentry><term><varname>exportReferencesGraph</varname></term> diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 07d8357b40b5..873f30b062ee 100644 --- a/doc/manual/expressions/builtins.xml +++ b/doc/manual/expressions/builtins.xml @@ -398,6 +398,84 @@ stdenv.mkDerivation { … } </listitem> </varlistentry> </variablelist> + + <example> + <title>Fetching a private repository over SSH</title> + <programlisting>builtins.fetchGit { + url = "git@github.com:my-secret/repository.git"; + ref = "master"; + rev = "adab8b916a45068c044658c4158d81878f9ed1c3"; +}</programlisting> + </example> + + <example> + <title>Fetching a repository's specific commit on an arbitrary branch</title> + <para> + If the revision you're looking for is in the default branch + of the gift repository you don't strictly need to specify + the branch name in the <varname>ref</varname> attribute. + </para> + <para> + However, if the revision you're looking for is in a future + branch for the non-default branch you will need to specify + the the <varname>ref</varname> attribute as well. + </para> + <programlisting>builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; + ref = "1.11-maintenance"; +}</programlisting> + <note> + <para> + It is nice to always specify the branch which a revision + belongs to. Without the branch being specified, the + fetcher might fail if the default branch changes. + Additionally, it can be confusing to try a commit from a + non-default branch and see the fetch fail. If the branch + is specified the fault is much more obvious. + </para> + </note> + </example> + + <example> + <title>Fetching a repository's specific commit on the default branch</title> + <para> + If the revision you're looking for is in the default branch + of the gift repository you may omit the + <varname>ref</varname> attribute. + </para> + <programlisting>builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452"; +}</programlisting> + </example> + + <example> + <title>Fetching a tag</title> + <programlisting>builtins.fetchGit { + url = "https://github.com/nixos/nix.git"; + ref = "tags/1.9"; +}</programlisting> + <note><para>Due to a bug (<link + xlink:href="https://github.com/NixOS/nix/issues/2385">#2385</link>), + only non-annotated tags can be fetched.</para></note> + </example> + + <example> + <title>Fetching the latest version of a remote branch</title> + <para> + <function>builtins.fetchGit</function> can behave impurely + fetch the latest version of a remote branch. + </para> + <note><para>Nix will refetch the branch in accordance to + <option>tarball-ttl</option>.</para></note> + <note><para>This behavior is disabled in + <emphasis>Pure evaluation mode</emphasis>.</para></note> + <programlisting>builtins.fetchGit { + url = "ssh://git@github.com/nixos/nix.git"; + ref = "master"; +}</programlisting> + </example> </listitem> </varlistentry> @@ -1244,8 +1322,8 @@ in foo</programlisting> This is not allowed because it would cause a cyclic dependency in the computation of the cryptographic hashes for <varname>foo</varname> and <varname>bar</varname>.</para> - <para>It is also not possible to reference the result of a derivation. - If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to + <para>It is also not possible to reference the result of a derivation. + If you are using Nixpkgs, the <literal>writeTextFile</literal> function is able to do that.</para></listitem> </varlistentry> diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml index 47d95f8a13e3..f961ed921bca 100644 --- a/doc/manual/expressions/language-constructs.xml +++ b/doc/manual/expressions/language-constructs.xml @@ -41,7 +41,7 @@ encountered</quote>).</para></footnote>.</para> </simplesect> -<simplesect><title>Let-expressions</title> +<simplesect xml:id="sect-let-expressions"><title>Let-expressions</title> <para>A let-expression allows you define local variables for an expression. For instance, diff --git a/doc/manual/glossary/glossary.xml b/doc/manual/glossary/glossary.xml index 4977825578f1..e3162ed8d469 100644 --- a/doc/manual/glossary/glossary.xml +++ b/doc/manual/glossary/glossary.xml @@ -1,5 +1,6 @@ <appendix xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink"> + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="part-glossary"> <title>Glossary</title> diff --git a/doc/manual/hacking.xml b/doc/manual/hacking.xml index 183aed7adff2..b671811d3a30 100644 --- a/doc/manual/hacking.xml +++ b/doc/manual/hacking.xml @@ -30,7 +30,7 @@ To build Nix itself in this shell: [nix-shell]$ configurePhase [nix-shell]$ make </screen> -To install it in <literal>$(pwd)/nix</literal> and test it: +To install it in <literal>$(pwd)/inst</literal> and test it: <screen> [nix-shell]$ make install [nix-shell]$ make installcheck diff --git a/doc/manual/installation/env-variables.xml b/doc/manual/installation/env-variables.xml index 1fd6bafee7e3..d1ee0bb2e096 100644 --- a/doc/manual/installation/env-variables.xml +++ b/doc/manual/installation/env-variables.xml @@ -39,7 +39,7 @@ bundle.</para> <step><para>Set the environment variable and install Nix</para> <screen> $ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt -$ curl https://nixos.org/nix/install | sh +$ sh <(curl https://nixos.org/nix/install) </screen></step> <step><para>In the shell profile and rc files (for example, @@ -55,7 +55,7 @@ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt the Nix installer will detect the presense of Nix configuration, and abort.</para></note> -<section> +<section xml:id="sec-nix-ssl-cert-file-with-nix-daemon-and-macos"> <title><envar>NIX_SSL_CERT_FILE</envar> with macOS and the Nix daemon</title> <para>On macOS you must specify the environment variable for the Nix diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml index 7e8dfb0db3d4..394d8053b942 100644 --- a/doc/manual/installation/installing-binary.xml +++ b/doc/manual/installation/installing-binary.xml @@ -6,13 +6,30 @@ <title>Installing a Binary Distribution</title> -<para>If you are using Linux or macOS, the easiest way to install -Nix is to run the following command: +<para>If you are using Linux or macOS, the easiest way to install Nix +is to run the following command: <screen> -$ bash <(curl https://nixos.org/nix/install) + $ sh <(curl https://nixos.org/nix/install) </screen> +As of Nix 2.1.0, the Nix installer will always default to creating a +single-user installation, however opting in to the multi-user +installation is highly recommended. +</para> + +<section xml:id="sect-single-user-installation"> + <title>Single User Installation</title> + + <para> + To explicitly select a single-user installation on your system: + + <screen> + sh <(curl https://nixos.org/nix/install) --no-daemon +</screen> + </para> + +<para> This will perform a single-user installation of Nix, meaning that <filename>/nix</filename> is owned by the invoking user. You should run this under your usual user account, <emphasis>not</emphasis> as @@ -33,58 +50,141 @@ and <filename>.profile</filename> to source the <command>NIX_INSTALLER_NO_MODIFY_PROFILE</command> environment variable before executing the install script to disable this behaviour. - </para> -<!-- -<para>You can also manually download and install a binary package. -Binary packages of the latest stable release are available for Fedora, -Debian, Ubuntu, macOS and various other systems from the <link -xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>. -You can also get builds of the latest development release from our -<link -xlink:href="http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents">continuous -build system</link>.</para> -<para>For Fedora, RPM packages are available. These can be installed -or upgraded using <command>rpm -U</command>. For example, +<para>You can uninstall Nix simply by running: <screen> -$ rpm -U nix-1.8-1.i386.rpm</screen> +$ rm -rf /nix +</screen> </para> - -<para>For Debian and Ubuntu, you can download a Deb package and -install it like this: +</section> + +<section xml:id="sect-multi-user-installation"> + <title>Multi User Installation</title> + <para> + The multi-user Nix installation creates system users, and a system + service for the Nix daemon. + </para> + + <itemizedlist> + <title>Supported Systems</title> + + <listitem> + <para>Linux running systemd, with SELinux disabled</para> + </listitem> + <listitem><para>macOS</para></listitem> + </itemizedlist> + + <para> + You can instruct the installer to perform a multi-user + installation on your system: + + <screen> + sh <(curl https://nixos.org/nix/install) --daemon +</screen> + </para> + + <para> + The multi-user installation of Nix will create build users between + the user IDs 30001 and 30032, and a group with the group ID 30000. + + You should run this under your usual user account, + <emphasis>not</emphasis> as root. The script will invoke + <command>sudo</command> as needed. + </para> + + <note><para> + If you need Nix to use a different group ID or user ID set, you + will have to download the tarball manually and <link + linkend="sect-nix-install-binary-tarball">edit the install + script</link>. + </para></note> + + <para> + The installer will modify <filename>/etc/bashrc</filename>, and + <filename>/etc/zshrc</filename> if they exist. The installer will + first back up these files with a + <literal>.backup-before-nix</literal> extension. The installer + will also create <filename>/etc/profile.d/nix.sh</filename>. + </para> + + <para>You can uninstall Nix with the following commands: <screen> -$ dpkg -i nix_1.8-1_amd64.deb</screen> +sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels + +# If you are on Linux with systemd, you will need to run: +sudo systemctl stop nix-daemon.socket +sudo systemctl stop nix-daemon.service +sudo systemctl disable nix-daemon.socket +sudo systemctl disable nix-daemon.service +sudo systemctl daemon-reload + +# If you are on macOS, you will need to run: +sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist +sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist +</screen> -</para> ---> + There may also be references to Nix in + <filename>/etc/profile</filename>, + <filename>/etc/bashrc</filename>, and + <filename>/etc/zshrc</filename> which you may remove. + </para> -<para>You can also download a binary tarball that contains Nix and all -its dependencies. (This is what the install script at -<uri>https://nixos.org/nix/install</uri> does automatically.) You -should unpack it somewhere (e.g. in <filename>/tmp</filename>), and -then run the script named <command>install</command> inside the binary -tarball: +</section> -<screen> -alice$ cd /tmp -alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2 -alice$ cd nix-1.8-x86_64-darwin -alice$ ./install -</screen> +<section xml:id="sect-nix-install-pinned-version-url"> + <title>Installing a pinned Nix version from a URL</title> -</para> + <para> + NixOS.org hosts version-specific installation URLs for all Nix + versions since 1.11.16, at + <literal>https://nixos.org/releases/nix/nix-VERSION/install</literal>. + </para> -<para>You can uninstall Nix simply by running: + <para> + These install scripts can be used the same as the main + NixOS.org installation script: -<screen> -$ rm -rf /nix + <screen> + sh <(curl https://nixos.org/nix/install) </screen> + </para> -</para> + <para> + In the same directory of the install script are sha256 sums, and + gpg signature files. + </para> +</section> + +<section xml:id="sect-nix-install-binary-tarball"> + <title>Installing from a binary tarball</title> + <para> + You can also download a binary tarball that contains Nix and all + its dependencies. (This is what the install script at + <uri>https://nixos.org/nix/install</uri> does automatically.) You + should unpack it somewhere (e.g. in <filename>/tmp</filename>), + and then run the script named <command>install</command> inside + the binary tarball: + + +<screen> +alice$ cd /tmp +alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2 +alice$ cd nix-1.8-x86_64-darwin +alice$ ./install +</screen> + </para> + + <para> + If you need to edit the multi-user installation script to use + different group ID or a different user ID range, modify the + variables set in the file named + <filename>install-multi-user</filename>. + </para> +</section> </chapter> diff --git a/doc/manual/installation/prerequisites-source.xml b/doc/manual/installation/prerequisites-source.xml index 01e9688d635f..ef14a1d753db 100644 --- a/doc/manual/installation/prerequisites-source.xml +++ b/doc/manual/installation/prerequisites-source.xml @@ -29,7 +29,8 @@ <literal>libbz2</literal> library. Thus you must have bzip2 installed, including development headers and libraries. If your distribution does not provide these, you can obtain bzip2 from <link - xlink:href="http://www.bzip.org/"/>.</para></listitem> + xlink:href="https://web.archive.org/web/20180624184756/http://www.bzip.org/" + />.</para></listitem> <listitem><para><literal>liblzma</literal>, which is provided by XZ Utils. If your distribution does not provide this, you can diff --git a/doc/manual/installation/supported-platforms.xml b/doc/manual/installation/supported-platforms.xml index 6858573ff407..3e74be49d1f7 100644 --- a/doc/manual/installation/supported-platforms.xml +++ b/doc/manual/installation/supported-platforms.xml @@ -10,7 +10,7 @@ <itemizedlist> - <listitem><para>Linux (i686, x86_64).</para></listitem> + <listitem><para>Linux (i686, x86_64, aarch64).</para></listitem> <listitem><para>macOS (x86_64).</para></listitem> diff --git a/doc/manual/installation/upgrading.xml b/doc/manual/installation/upgrading.xml new file mode 100644 index 000000000000..a3f86ade95cd --- /dev/null +++ b/doc/manual/installation/upgrading.xml @@ -0,0 +1,21 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-upgrading-nix"> + + <title>Upgrading Nix</title> + + <para> + Multi-user Nix users on macOS can upgrade Nix by running + <command>sudo -i sh -c 'nix-channel --update && nix-env + -iA nixpkgs.nix'; sudo launchctl stop org.nixos.nix-daemon; sudo + launchctl start org.nixos.nix-daemon</command>. + </para> + + <para> + Single-user installations of Nix should run <command>nix-channel + --update; nix-env -iA nixpkgs.nix</command>. + </para> + +</chapter> diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index b408b6817727..87d9de28ab14 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -32,6 +32,7 @@ <xi:include href="introduction/introduction.xml" /> <xi:include href="installation/installation.xml" /> + <xi:include href="installation/upgrading.xml" /> <xi:include href="packages/package-management.xml" /> <xi:include href="expressions/writing-nix-expressions.xml" /> <xi:include href="advanced-topics/advanced-topics.xml" /> diff --git a/doc/manual/release-notes/rl-2.1.xml b/doc/manual/release-notes/rl-2.1.xml index c628d04a7071..16c243fc191a 100644 --- a/doc/manual/release-notes/rl-2.1.xml +++ b/doc/manual/release-notes/rl-2.1.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ssec-relnotes-2.1"> -<title>Release 2.1 (2018-08-??)</title> +<title>Release 2.1 (2018-09-02)</title> <para>This is primarily a bug fix release. It also reduces memory consumption in certain situations. In addition, it has the following @@ -13,6 +13,29 @@ new features:</para> <itemizedlist> <listitem> + <para>The Nix installer will no longer default to the Multi-User + installation for macOS. You can still <link + linkend="sect-multi-user-installation">instruct the installer to + run in multi-user mode</link>. + </para> + </listitem> + + <listitem> + <para>The Nix installer now supports performing a Multi-User + installation for Linux computers which are running systemd. You + can <link + linkend="sect-multi-user-installation">select a Multi-User installation</link> by passing the + <option>--daemon</option> flag to the installer: <command>sh <(curl + https://nixos.org/nix/install) --daemon</command>. + </para> + + <para>The multi-user installer cannot handle systems with SELinux. + If your system has SELinux enabled, you can <link + linkend="sect-single-user-installation">force the installer to run + in single-user mode</link>.</para> + </listitem> + + <listitem> <para>New builtin functions: <literal>builtins.bitAnd</literal>, <literal>builtins.bitOr</literal>, @@ -41,13 +64,70 @@ new features:</para> <listitem> <para><command>nix-daemon</command> now respects - <option>--store</option>, so it can be run as a non-root - user.</para> + <option>--store</option>.</para> + </listitem> + + <listitem> + <para><command>nix run</command> now respects + <varname>nix-support/propagated-user-env-packages</varname>.</para> </listitem> </itemizedlist> -<para>This release has contributions from TODO. +<para>This release has contributions from + +Adrien Devresse, +Aleksandr Pashkov, +Alexandre Esteves, +Amine Chikhaoui, +Andrew Dunham, +Asad Saeeduddin, +aszlig, +Ben Challenor, +Ben Gamari, +Benjamin Hipple, +Bogdan Seniuc, +Corey O'Connor, +Daiderd Jordan, +Daniel Peebles, +Daniel Poelzleithner, +Danylo Hlynskyi, +Dmitry Kalinkin, +Domen Kožar, +Doug Beardsley, +Eelco Dolstra, +Erik Arvstedt, +Félix Baylac-Jacqué, +Gleb Peregud, +Graham Christensen, +Guillaume Maudoux, +Ivan Kozik, +John Arnold, +Justin Humm, +Linus Heckemann, +Lorenzo Manacorda, +Matthew Justin Bauer, +Matthew O'Gorman, +Maximilian Bosch, +Michael Bishop, +Michael Fiano, +Michael Mercier, +Michael Raskin, +Michael Weiss, +Nicolas Dudebout, +Peter Simons, +Ryan Trinkle, +Samuel Dionne-Riel, +Sean Seefried, +Shea Levy, +Symphorien Gibol, +Tim Engler, +Tim Sears, +Tuomas Tynkkynen, +volth, +Will Dietz, +Yorick van Pelt and +zimbatm. </para> </section> |