diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/command-ref/nix-channel.xml | 56 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-pull.xml | 7 | ||||
| -rw-r--r-- | doc/manual/installation/multi-user.xml | 10 | ||||
| -rw-r--r-- | doc/manual/packages/basic-package-mgmt.xml | 138 | ||||
| -rw-r--r-- | doc/manual/packages/channels.xml | 44 | ||||
| -rw-r--r-- | doc/manual/packages/garbage-collection.xml | 2 | ||||
| -rw-r--r-- | doc/manual/packages/profiles.xml | 6 |
7 files changed, 164 insertions, 99 deletions
diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml index c4cc04ce2..b777c6b6b 100644 --- a/doc/manual/command-ref/nix-channel.xml +++ b/doc/manual/command-ref/nix-channel.xml @@ -33,8 +33,8 @@ <para>A Nix channel is mechanism that allows you to automatically stay up-to-date with a set of pre-built Nix expressions. A Nix channel is -just a URL that points to a place containing a set of Nix expressions -and a <command>nix-push</command> manifest. <phrase +just a URL that points to a place containing both a set of Nix +expressions and a pointer to a binary cache. <phrase condition="manual">See also <xref linkend="sec-channels" />.</phrase></para> @@ -99,13 +99,6 @@ an update.</para> <para>The list of subscribed channels is stored in <filename>~/.nix-channels</filename>.</para> -<para>A channel consists of two elements: a bzipped Tar archive -containing the Nix expressions, and a manifest created by -<command>nix-push</command>. These must be stored under -<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal> and -<literal><replaceable>url</replaceable>/MANIFEST</literal>, -respectively.</para> - </refsection> <refsection><title>Examples</title> @@ -163,4 +156,49 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.nixpkgsVersion' </refsection> +<refsection><title>Channel format</title> + +<para>A channel URL should point to a directory containing the +following files:</para> + +<variablelist> + + <varlistentry><term><filename>nixexprs.tar.xz</filename></term> + + <listitem><para>A tarball containing Nix expressions and files + referenced by them (such as build scripts and patches). At + top-level, the tarball should contain a single directory. That + directory must contain a file <filename>default.nix</filename> + that serves as the channel’s “entry point”.</para></listitem> + + </varlistentry> + + <varlistentry><term><filename>binary-cache-url</filename></term> + + <listitem><para>A file containing the URL to a binary cache (such + as <uri>https://cache.nixos.org</uri>. Nix will automatically + check this cache for pre-built binaries, if the user has + sufficient rights to add binary caches. For instance, in a + multi-user Nix setup, the binary caches provided by the channels + of the root user are used automatically, but caches corresponding + to the channels of non-root users are ignored. Binary caches can + be created and maintained using + <command>nix-push</command>.</para></listitem> + + </varlistentry> + + <varlistentry><term><filename>MANIFEST.bz2</filename></term> + + <listitem><para>(Deprecated in favour of binary caches.) A + manifest as created by <command>nix-push</command>. Only used if + <filename>binary-cache-url</filename> is not present or if the + <filename>nix.conf</filename> option + <option>force-manifest</option> is set.</para></listitem> + + </varlistentry> + +</variablelist> + +</refsection> + </refentry> diff --git a/doc/manual/command-ref/nix-pull.xml b/doc/manual/command-ref/nix-pull.xml index 598c651b5..eb471677b 100644 --- a/doc/manual/command-ref/nix-pull.xml +++ b/doc/manual/command-ref/nix-pull.xml @@ -13,7 +13,7 @@ <refnamediv> <refname>nix-pull</refname> - <refpurpose>pull substitutes from a network cache</refpurpose> + <refpurpose>register availability of pre-built binaries (deprecated)</refpurpose> </refnamediv> <refsynopsisdiv> @@ -26,6 +26,9 @@ <refsection><title>Description</title> +<note><para>This command and the use of manifests is deprecated. It is +better to use binary caches.</para></note> + <para>The command <command>nix-pull</command> obtains a list of pre-built store paths from the URL <replaceable>url</replaceable>, and for each of these store paths, registers a substitute derivation that @@ -43,7 +46,7 @@ with the files created by <replaceable>nix-push</replaceable>.</para> <refsection><title>Examples</title> <screen> -$ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST</screen> +$ nix-pull https://nixos.org/releases/nixpkgs/nixpkgs-15.05pre54468.69858d7/MANIFEST</screen> </refsection> diff --git a/doc/manual/installation/multi-user.xml b/doc/manual/installation/multi-user.xml index 312f59664..69ae1ef27 100644 --- a/doc/manual/installation/multi-user.xml +++ b/doc/manual/installation/multi-user.xml @@ -23,11 +23,11 @@ daemon</emphasis> running under the owner of the Nix store/database that performs the operation.</para> <note><para>Multi-user mode has one important limitation: only -<systemitem class="username">root</systemitem> can run <command -linkend="sec-nix-pull">nix-pull</command> to register the availability -of pre-built binaries. However, those registrations are shared by all -users, so they still get the benefit from <command>nix-pull</command>s -done by <systemitem class="username">root</systemitem>.</para></note> +<systemitem class="username">root</systemitem> and a set of trusted +users specified in <filename>nix.conf</filename> can specify arbitrary +binary caches. So while unprivileged users may install packages from +arbitrary Nix expressions, they may not get pre-built +binaries.</para></note> <simplesect> diff --git a/doc/manual/packages/basic-package-mgmt.xml b/doc/manual/packages/basic-package-mgmt.xml index 69c955c1d..540d3ec22 100644 --- a/doc/manual/packages/basic-package-mgmt.xml +++ b/doc/manual/packages/basic-package-mgmt.xml @@ -28,40 +28,71 @@ Nix expressions called the Nix Package collection that contains packages ranging from basic development stuff such as GCC and Glibc, to end-user applications like Mozilla Firefox. (Nix is however not tied to the Nix Package collection; you could write your own Nix -expressions based on it, or completely new ones.) You can download -the latest version from <link -xlink:href='http://nixos.org/nixpkgs/download.html' />.</para> +expressions based on it, or completely new ones.)</para> + +<para>You can manually download the latest version of Nixpkgs from +<link xlink:href='http://nixos.org/nixpkgs/download.html'/>. However, +it’s much more convenient to use the Nixpkgs +<emphasis>channel</emphasis>, since it makes it easy to stay up to +date with new versions of Nixpkgs. (Channels are described in more +detail in <xref linkend="sec-channels"/>.) Nixpkgs is automatically +added to your list of “subscribed” channels when when you install +Nix. If this is not the case for some reason, you can add it as +follows: -<para>Assuming that you have downloaded and unpacked a release of Nix -Packages, you can view the set of available packages in the release: +<screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable +$ nix-channel --update +</screen> + +</para> + +<note><para>On NixOS, you’re automatically subscribed to a NixOS +channel corresponding to your NixOS major release +(e.g. <uri>http://nixos.org/channels/nixos-14.12</uri>). A NixOS +channel is identical to the Nixpkgs channel, except that it contains +only Linux binaries and is updated only if a set of regression tests +succeed.</para></note> + +<para>You can view the set of available packages in Nixpkgs: <screen> -$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*' -ant-blackdown-1.4.2 +$ nix-env -qa aterm-2.2 bash-3.0 binutils-2.15 bison-1.875d blackdown-1.4.2 bzip2-1.0.2 -...</screen> - -where <literal>nixpkgs-<replaceable>version</replaceable></literal> is -where you’ve unpacked the release. The flag <option>-q</option> -specifies a query operation; <option>-a</option> means that you want -to show the “available” (i.e., installable) packages, as opposed to -the installed packages; and <option>-f</option> -<filename>nixpkgs-<replaceable>version</replaceable></filename> -specifies the source of the packages. The argument -<literal>'*'</literal> shows all installable packages. (The quotes are -necessary to prevent shell expansion.) You can also select specific -packages by name: +…</screen> + +The flag <option>-q</option> specifies a query operation, and +<option>-a</option> means that you want to show the “available” (i.e., +installable) packages, as opposed to the installed packages. If you +downloaded Nixpkgs yourself, or if you checked it out from GitHub, +then you need to pass the path to your Nixpkgs tree using the +<option>-f</option> flag: + +<screen> +$ nix-env -qaf <replaceable>/path/to/nixpkgs</replaceable> +</screen> + +where <replaceable>/path/to/nixpkgs</replaceable> is where you’ve +unpacked or checked out Nixpkgs.</para> + +<para>You can select specific packages by name: + +<screen> +$ nix-env -qa firefox +firefox-34.0.5 +firefox-with-plugins-34.0.5 +</screen> + +and using regular expressions: <screen> -$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc -gcc-3.4.6 -gcc-4.0.3 -gcc-4.1.1</screen> +$ nix-env -qa 'firefox.*' +</screen> </para> @@ -70,12 +101,12 @@ available packages, i.e., whether they are installed into the user environment and/or present in the system: <screen> -$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*' -... +$ nix-env -qas +… -PS bash-3.0 --S binutils-2.15 IPS bison-1.875d -...</screen> +…</screen> The first character (<literal>I</literal>) indicates whether the package is installed in your current user environment. The second @@ -88,40 +119,33 @@ just means that Nix knows that it can fetch a pre-built package from somewhere (typically a network server) instead of building it locally.</para> -<para>So now that we have a set of Nix expressions we can build the -packages contained in them. This is done using <literal>nix-env --i</literal>. For instance, +<para>You can install a package using <literal>nix-env -i</literal>. +For instance, <screen> -$ nix-env -f nixpkgs-<replaceable>version</replaceable> -i subversion</screen> +$ nix-env -i subversion</screen> will install the package called <literal>subversion</literal> (which is, of course, the <link xlink:href='http://subversion.tigris.org/'>Subversion version management system</link>).</para> -<para>When you do this for the first time, Nix will start building -Subversion and all its dependencies. This will take quite a while — -typically an hour or two on modern machines. Fortunately, there is a -faster way (so do a Ctrl-C on that install operation!): you just need -to tell Nix that pre-built binaries of all those packages are -available somewhere. This is done using the -<command>nix-pull</command> command, which must be supplied with a URL -containing a <emphasis>manifest</emphasis> describing what binaries -are available. This URL should correspond to the Nix Packages release -that you’re using. For instance, if you obtained a release from <link -xlink:href='http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x' -/>, then you should do: - -<screen> -$ nix-pull http://nixos.org/releases/nixpkgs/nixpkgs-0.12pre11712-4lrp7j8x/MANIFEST</screen> - -If you then issue the installation command, it should start -downloading binaries from <systemitem -class='fqdomainname'>nixos.org</systemitem>, instead of building -them from source. This might still take a while since all -dependencies must be downloaded, but on a reasonably fast connection -such as a DSL line it’s on the order of a few minutes.</para> +<note><para>When you ask Nix to install a package, it will first try +to get it in pre-compiled form from a <emphasis>binary +cache</emphasis>. By default, Nix will use the binary cache +<uri>https://cache.nixos.org</uri>; it contains binaries for most +packages in Nixpkgs. Only if no binary is available in the binary +cache, Nix will build the package from source. So if <literal>nix-env +-i subversion</literal> results in Nix building stuff from source, +then either the package is not built for your platform by the Nixpkgs +build servers, or your version of Nixpkgs is too old or too new. For +instance, if you have a very recent checkout of Nixpkgs, then the +Nixpkgs build servers may not have had a chance to build everything +and upload the resulting binaries to +<uri>https://cache.nixos.org</uri>. The Nixpkgs channel is only +updated after all binaries have been uploaded to the cache, so if you +stick to the Nixpkgs channel (rather than using a Git checkout of the +Nixpkgs tree), you will get binaries for most packages.</para></note> <para>Naturally, packages can also be uninstalled: @@ -134,7 +158,7 @@ $ nix-env -e subversion</screen> release of Nix Packages, you can do: <screen> -$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u subversion</screen> +$ nix-env -u subversion</screen> This will <emphasis>only</emphasis> upgrade Subversion if there is a “newer” version in the new set of Nix expressions, as @@ -149,17 +173,17 @@ whatever version is already installed.</para> versions: <screen> -$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen> +$ nix-env -u</screen> </para> <para>Sometimes it’s useful to be able to ask what <command>nix-env</command> would do, without actually doing it. For instance, to find out what packages would be upgraded by -<literal>nix-env -u '*'</literal>, you can do +<literal>nix-env -u</literal>, you can do <screen> -$ nix-env ... -u '*' --dry-run +$ nix-env -u --dry-run (dry run; not doing anything) upgrading `libxslt-1.1.0' to `libxslt-1.1.10' upgrading `graphviz-1.10' to `graphviz-1.12' @@ -167,4 +191,4 @@ upgrading `coreutils-5.0' to `coreutils-5.2.1'</screen> </para> -</chapter>
\ No newline at end of file +</chapter> diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml index 094e11fe3..15c119fcb 100644 --- a/doc/manual/packages/channels.xml +++ b/doc/manual/packages/channels.xml @@ -8,10 +8,9 @@ <para>If you want to stay up to date with a set of packages, it’s not very convenient to manually download the latest set of Nix expressions -for those packages, use <command>nix-pull</command> to register -pre-built binaries (if available), and upgrade using -<command>nix-env</command>. Fortunately, there’s a better way: -<emphasis>Nix channels</emphasis>.</para> +for those packages and upgrade using <command>nix-env</command>. +Fortunately, there’s a better way: <emphasis>Nix +channels</emphasis>.</para> <para>A Nix channel is just a URL that points to a place that contains a set of Nix expressions and a manifest. Using the command <link @@ -23,35 +22,36 @@ URL.</para> <command>nix-channel --add</command>, e.g., <screen> -$ nix-channel --add http://nixos.org/channels/nixpkgs-unstable</screen> +$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable</screen> subscribes you to a channel that always contains that latest version -of the Nix Packages collection. (Instead of -<literal>nixpkgs-unstable</literal> you could also subscribe to -<literal>nixpkgs-stable</literal>, which should have a higher level of -stability, but right now is just outdated.) Subscribing really just -means that the URL is added to the file -<filename>~/.nix-channels</filename>. Right now there is no command -to “unsubscribe”; you should just edit that file manually -and delete the offending URL.</para> +of the Nix Packages collection. (Subscribing really just means that +the URL is added to the file <filename>~/.nix-channels</filename>, +where it is read by subsequent calls to <command>nix-channel +--update</command>.) You can “unsubscribe” using <command>nix-channel +--remove</command>: + +<screen> +$ nix-channel --remove nixpkgs +</screen> +</para> <para>To obtain the latest Nix expressions available in a channel, do <screen> $ nix-channel --update</screen> -This downloads the Nix expressions in every channel (downloaded from -<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>) -and registers any available pre-built binaries in every channel -(by <command>nix-pull</command>ing -<literal><replaceable>url</replaceable>/MANIFEST</literal>). It also -makes the union of each channel’s Nix expressions the default for -<command>nix-env</command> operations. Consequently, you can then say +This downloads and unpacks the Nix expressions in every channel +(downloaded from <literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal>). +It also makes the union of each channel’s Nix expressions available by +default to <command>nix-env</command> operations (via the symlink +<filename>~/.nix-defexpr/channels</filename>). Consequently, you can +then say <screen> -$ nix-env -u '*'</screen> +$ nix-env -u</screen> to upgrade all packages in your profile to the latest versions available in the subscribed channels.</para> -</chapter>
\ No newline at end of file +</chapter> diff --git a/doc/manual/packages/garbage-collection.xml b/doc/manual/packages/garbage-collection.xml index ae28c485f..05a06d6f4 100644 --- a/doc/manual/packages/garbage-collection.xml +++ b/doc/manual/packages/garbage-collection.xml @@ -67,4 +67,4 @@ is a quick and easy way to clean up your system.</para> <xi:include href="garbage-collector-roots.xml" /> -</chapter>
\ No newline at end of file +</chapter> diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml index ad5e92aeb..932e58302 100644 --- a/doc/manual/packages/profiles.xml +++ b/doc/manual/packages/profiles.xml @@ -73,9 +73,9 @@ generated based on the current one. For instance, generation 43 was created from generation 42 when we did <screen> -$ nix-env -i subversion mozilla</screen> +$ nix-env -i subversion firefox</screen> -on a set of Nix expressions that contained Mozilla and a new version +on a set of Nix expressions that contained Firefox and a new version of Subversion.</para> <para>Generations are grouped together into @@ -156,4 +156,4 @@ $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion</screen> This will <emphasis>not</emphasis> change the <command>~/.nix-profile</command> symlink.</para> -</chapter>
\ No newline at end of file +</chapter> |