diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/command-ref/env-common.xml | 16 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-build.xml | 16 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-env.xml | 95 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-shell.xml | 19 | ||||
| -rw-r--r-- | doc/manual/expressions/builtins.xml | 39 |
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><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 < 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> |