Document tarball downloading

5 files changed, 170 insertions, 15 deletions

diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml
index 39e3e9cff2e3..cb1ecfee123e 100644
--- a/doc/manual/command-ref/env-common.xml
+++ b/doc/manual/command-ref/env-common.xml
@@ -36,8 +36,20 @@ nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen>
     <literal>&lt;nixpkgs/<replaceable>path</replaceable>></literal> in
     <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename>
     and
-    <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.
-    </para>
+    <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para>
+
+    <para>If a path in the Nix search path starts with
+    <literal>http://</literal> or <literal>https://</literal>, it is
+    interpreted as the URL of a tarball that will be downloaded and
+    unpacked to a temporary location. The tarball must consist of a
+    single top-level directory. For example, setting
+    <envar>NIX_PATH</envar> to
+
+    <screen>
+nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz</screen>
+
+    tells Nix to download the latest revision in the Nixpkgs/NixOS
+    14.12 channel.</para>
 
     <para>The search path can be extended using the <option
     linkend="opt-I">-I</option> option, which takes precedence over
diff --git a/doc/manual/command-ref/nix-build.xml b/doc/manual/command-ref/nix-build.xml
index dc5841c27a5a..d6b2e5e5adb7 100644
--- a/doc/manual/command-ref/nix-build.xml
+++ b/doc/manual/command-ref/nix-build.xml
@@ -58,6 +58,13 @@ and so on).</para>
 <command>nix-build</command> will use <filename>default.nix</filename>
 in the current directory, if it exists.</para>
 
+<para>If an element of <replaceable>paths</replaceable> starts with
+<literal>http://</literal> or <literal>https://</literal>, it is
+interpreted as the URL of a tarball that will be downloaded and
+unpacked to a temporary location. The tarball must include a single
+top-level directory containing at least a file named
+<filename>default.nix</filename>.</para>
+
 <para><command>nix-build</command> is essentially a wrapper around
 <link
 linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
@@ -175,6 +182,15 @@ bar
 
 </para>
 
+<para>Build the GNU Hello package from the latest revision of the
+master branch of Nixpkgs:
+
+<screen>
+$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+</screen>
+
+</para>
+
 </refsection>
 
 
diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml
index 45a99b27d7bd..5e40317f189d 100644
--- a/doc/manual/command-ref/nix-env.xml
+++ b/doc/manual/command-ref/nix-env.xml
@@ -154,7 +154,15 @@ also <xref linkend="sec-common-options" />.</phrase></para>
     <option>--install</option>, <option>--upgrade</option>, and
     <option>--query --available</option> operations to obtain
     derivations.  The default is
-    <filename>~/.nix-defexpr</filename>.</para></listitem>
+    <filename>~/.nix-defexpr</filename>.</para>
+
+    <para>If the argument starts with <literal>http://</literal> or
+    <literal>https://</literal>, it is interpreted as the URL of a
+    tarball that will be downloaded and unpacked to a temporary
+    location. The tarball must include a single top-level directory
+    containing at least a file named <filename>default.nix</filename>.</para>
+
+    </listitem>
 
   </varlistentry>
 
@@ -496,6 +504,18 @@ the following paths will be substituted:
 
 </para>
 
+<para>To install Firefox from the latest revision in the Nixpkgs/NixOS
+14.12 channel:
+
+<screen>
+$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox
+</screen>
+
+(The GitHub repository <literal>nixpkgs-channels</literal> is updated
+automatically from the main <literal>nixpkgs</literal> repository
+after certain tests have succeeded and binaries have been built and
+uploaded to the binary cache at <uri>cache.nixos.org</uri>.)</para>
+
 </refsection>
 
 </refsection>
@@ -1129,54 +1149,103 @@ user environment elements, etc. -->
 
 <refsection><title>Examples</title>
 
+<para>To show installed packages:
+
 <screen>
-$ nix-env -q <lineannotation>(show installed derivations)</lineannotation>
+$ nix-env -q
 bison-1.875c
 docbook-xml-4.2
 firefox-1.0.4
 MPlayer-1.0pre7
 ORBit2-2.8.3
-...
+<replaceable>…</replaceable>
+</screen>
+
+</para>
 
-$ nix-env -qa <lineannotation>(show available derivations)</lineannotation>
+<para>To show available packages:
+
+<screen>
+$ nix-env -qa
 firefox-1.0.7
 GConf-2.4.0.1
 MPlayer-1.0pre7
 ORBit2-2.8.3
-...
+<replaceable>…</replaceable>
+</screen>
+
+</para>
+
+<para>To show the status of available packages:
 
-$ nix-env -qas      <lineannotation>(show status of available derivations)</lineannotation>
+<screen>
+$ nix-env -qas
 -P- firefox-1.0.7   <lineannotation>(not installed but present)</lineannotation>
 --S GConf-2.4.0.1   <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation>
 --S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation>
 IP- ORBit2-2.8.3    <lineannotation>(installed and by definition present)</lineannotation>
-...
+<replaceable>…</replaceable>
+</screen>
+
+</para>
+
+<para>To show available packages in the Nix expression <filename>foo.nix</filename>:
 
-<lineannotation>(show available derivations in the Nix expression <!-- !!! <filename>-->foo.nix<!-- </filename> -->)</lineannotation>
+<screen>
 $ nix-env -f ./foo.nix -qa
 foo-1.2.3
+</screen>
+
+</para>
+
+<para>To compare installed versions to what’s available:
 
-$ nix-env -qc <lineannotation>(compare installed versions to what’s available)</lineannotation>
+<screen>
+$ nix-env -qc
 <replaceable>...</replaceable>
 acrobat-reader-7.0 - ?      <lineannotation>(package is not available at all)</lineannotation>
 autoconf-2.59      = 2.59   <lineannotation>(same version)</lineannotation>
 firefox-1.0.4      &lt; 1.0.7  <lineannotation>(a more recent version is available)</lineannotation>
 <replaceable>...</replaceable>
+</screen>
 
-$ nix-env -qa '.*zip.*' <lineannotation>(show all packages with “zip” in the name)</lineannotation>
+</para>
+
+<para>To show all packages with “<literal>zip</literal>” in the name:
+
+<screen>
+$ nix-env -qa '.*zip.*'
 bzip2-1.0.6
 gzip-1.6
 zip-3.0
-<replaceable>...</replaceable>
+<replaceable>…</replaceable>
+</screen>
 
-$ nix-env -qa '.*(firefox|chromium).*' <lineannotation>(show all packages with “firefox” or “chromium” in the name)</lineannotation>
+</para>
+
+<para>To show all packages with “<literal>firefox</literal>” or
+“<literal>chromium</literal>” in the name:
+
+<screen>
+$ nix-env -qa '.*(firefox|chromium).*'
 chromium-37.0.2062.94
 chromium-beta-38.0.2125.24
 firefox-32.0.3
 firefox-with-plugins-13.0.1
-<replaceable>...</replaceable>
+<replaceable>…</replaceable>
+</screen>
+
+</para>
+
+<para>To show all packages in the latest revision of the Nixpkgs
+repository:
+
+<screen>
+$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
 </screen>
 
+</para>
+
 </refsection>
 
 </refsection>
diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
index 77dd32653433..9e3e6d1882ba 100644
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -61,6 +61,13 @@ derivation for development.</para>
 <filename>shell.nix</filename> if it exists, and
 <filename>default.nix</filename> otherwise.</para>
 
+<para>If <replaceable>path</replaceable> starts with
+<literal>http://</literal> or <literal>https://</literal>, it is
+interpreted as the URL of a tarball that will be downloaded and
+unpacked to a temporary location. The tarball must include a single
+top-level directory containing at least a file named
+<filename>default.nix</filename>.</para>
+
 <para>If the derivation defines the variable
 <varname>shellHook</varname>, it will be evaluated after
 <literal>$stdenv/setup</literal> has been sourced.  Since this hook is
@@ -207,6 +214,18 @@ $ nix-shell -p sqlite xorg.libX11
 … -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
 </screen>
 
+The <command>-p</command> flag looks up Nixpkgs in the Nix search
+path. You can override it by passing <option>-I</option> or setting
+<envar>NIX_PATH</envar>. For example, the following gives you a shell
+containing the Pan package from a specific revision of Nixpkgs:
+
+<screen>
+$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
+
+[nix-shell:~]$ pan --version
+Pan 0.139
+</screen>
+
 </para>
 
 </refsection>
diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml
index 3cdf4e28fe6a..6bdfdd55c4b6 100644
--- a/doc/manual/expressions/builtins.xml
+++ b/doc/manual/expressions/builtins.xml
@@ -211,6 +211,45 @@ if builtins ? getEnv then builtins.getEnv "PATH" else ""</programlisting>
   </varlistentry>
 
 
+  <varlistentry><term><function>builtins.fetchurl</function>
+  <replaceable>url</replaceable></term>
+
+    <listitem><para>Download the specified URL and return the path of
+    the downloaded file. This function is not available if <link
+    linkend="conf-restrict-eval">restricted evaluation mode</link> is
+    enabled.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><function>fetchTarball</function>
+  <replaceable>url</replaceable></term>
+
+    <listitem><para>Download the specified URL, unpack it and return
+    the path of the unpacked tree. The file must be a tape archive
+    (<filename>.tar</filename>) compressed with
+    <literal>gzip</literal>, <literal>bzip2</literal> or
+    <literal>xz</literal>. The top-level path component of the files
+    in the tarball is removed, so it is best if the tarball contains a
+    single directory at top level. The typical use of the function is
+    to obtain external Nix expression dependencies, such as a
+    particular version of Nixpkgs, e.g.
+
+<programlisting>
+with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {};
+
+stdenv.mkDerivation { … }
+</programlisting>
+
+    </para>
+
+    <para>This function is not available if <link
+    linkend="conf-restrict-eval">restricted evaluation mode</link> is
+    enabled.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><function>builtins.filter</function>
   <replaceable>f</replaceable> <replaceable>xs</replaceable></term>