[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

361/376: Document channel format and excise most mentions of manifests a

From: Ludovic Courtès
Subject: 361/376: Document channel format and excise most mentions of manifests and nix-pull
Date: Wed, 28 Jan 2015 22:06:11 +0000

civodul pushed a commit to tag 1.8
in repository guix.

commit 3b88d037145c8d0f26b0797f8269e65c4c6df4ff
Author: Eelco Dolstra <address@hidden>
Date:   Sat Dec 13 23:16:08 2014 +0100

    Document channel format and excise most mentions of manifests and nix-pull
 doc/manual/command-ref/nix-channel.xml     |   56 ++++++++++--
 doc/manual/command-ref/nix-pull.xml        |    7 +-
 doc/manual/installation/multi-user.xml     |   10 +-
 doc/manual/packages/basic-package-mgmt.xml |  138 ++++++++++++++++------------
 doc/manual/packages/channels.xml           |   44 +++++-----
 doc/manual/packages/garbage-collection.xml |    2 +-
 doc/manual/packages/profiles.xml           |    6 +-
 7 files changed, 164 insertions(+), 99 deletions(-)

diff --git a/doc/manual/command-ref/nix-channel.xml 
index c4cc04c..b777c6b 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"
@@ -99,13 +99,6 @@ an update.</para>
 <para>The list of subscribed channels is stored in
-<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
@@ -163,4 +156,49 @@ $ nix-instantiate --eval -E '(import &lt;nixpkgs> 
+<refsection><title>Channel format</title>
+<para>A channel URL should point to a directory containing the
+following files:</para>
+  <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></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>
diff --git a/doc/manual/command-ref/nix-pull.xml 
index 598c651..eb47167 100644
--- a/doc/manual/command-ref/nix-pull.xml
+++ b/doc/manual/command-ref/nix-pull.xml
@@ -13,7 +13,7 @@
-  <refpurpose>pull substitutes from a network cache</refpurpose>
+  <refpurpose>register availability of pre-built binaries 
@@ -26,6 +26,9 @@
+<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 
-$ nix-pull</screen>
+$ nix-pull</screen>
diff --git a/doc/manual/installation/multi-user.xml 
index 312f596..69ae1ef 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 
 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
diff --git a/doc/manual/packages/basic-package-mgmt.xml 
index 69c955c..540d3ec 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 
 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='' />.</para>
+expressions based on it, or completely new ones.)</para>
+<para>You can manually download the latest version of Nixpkgs from
+<link xlink:href=''/>. 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
-<para>Assuming that you have downloaded and unpacked a release of Nix
-Packages, you can view the set of available packages in the release:
+$ nix-channel --add
+$ nix-channel --update
+<note><para>On NixOS, you’re automatically subscribed to a NixOS
+channel corresponding to your NixOS major release
+(e.g. <uri></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
+<para>You can view the set of available packages in Nixpkgs:
-$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*'
+$ nix-env -qa
-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>
-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:
+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:
+$ nix-env -qaf <replaceable>/path/to/nixpkgs</replaceable>
+where <replaceable>/path/to/nixpkgs</replaceable> is where you’ve
+unpacked or checked out Nixpkgs.</para>
+<para>You can select specific packages by name:
+$ nix-env -qa firefox
+and using regular expressions:
-$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> gcc
+$ nix-env -qa 'firefox.*'
@@ -70,12 +101,12 @@ available packages, i.e., whether they are installed into 
the user
 environment and/or present in the system:
-$ nix-env -qasf nixpkgs-<replaceable>version</replaceable> '*'
+$ nix-env -qas
 -PS bash-3.0
 --S binutils-2.15
 IPS bison-1.875d
 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
-<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,
-$ 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=''>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
-/>, then you should do:
-$ nix-pull</screen>
-If you then issue the installation command, it should start
-downloading binaries from <systemitem
-class='fqdomainname'></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></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></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:
-$ 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>
-$ nix-env -f nixpkgs-<replaceable>version</replaceable> -u '*'</screen>
+$ nix-env -u</screen>
 <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
-$ 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>
\ No newline at end of file
diff --git a/doc/manual/packages/channels.xml b/doc/manual/packages/channels.xml
index 094e11f..15c119f 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
 <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.,
-$ nix-channel --add</screen>
+$ nix-channel --add</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
+$ nix-channel --remove nixpkgs
 <para>To obtain the latest Nix expressions available in a channel, do
 $ nix-channel --update</screen>
-This downloads the Nix expressions in every channel (downloaded from
-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 
+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
-$ 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>
\ No newline at end of file
diff --git a/doc/manual/packages/garbage-collection.xml 
index ae28c48..05a06d6 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" />
\ No newline at end of file
diff --git a/doc/manual/packages/profiles.xml b/doc/manual/packages/profiles.xml
index ad5e92a..932e583 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
-$ 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 
 This will <emphasis>not</emphasis> change the
 <command>~/.nix-profile</command> symlink.</para>
\ No newline at end of file

reply via email to

[Prev in Thread] Current Thread [Next in Thread]