Document channel format and excise most mentions of manifests and nix-pull

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 c4cc04ce24d8..b777c6b6b73c 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 &lt;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 598c651b5091..eb471677b63f 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 312f5966452d..69ae1ef27041 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 69c955c1dd11..540d3ec223cc 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 094e11fe3b15..15c119fcb1f9 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 ae28c485f076..05a06d6f48fe 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 ad5e92aeb64b..932e58302ace 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>