From da196ec68f8b34e0c4c7ee32beb9073b31b1531e Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Mon, 1 Jun 2015 15:14:44 +0200 Subject: [PATCH] Document tarball downloading --- doc/manual/command-ref/env-common.xml | 16 ++++- doc/manual/command-ref/nix-build.xml | 16 +++++ doc/manual/command-ref/nix-env.xml | 95 +++++++++++++++++++++++---- doc/manual/command-ref/nix-shell.xml | 19 ++++++ doc/manual/expressions/builtins.xml | 39 +++++++++++ src/libexpr/download.cc | 1 + 6 files changed, 171 insertions(+), 15 deletions(-) diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml index 39e3e9cff..cb1ecfee1 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 <nixpkgs/path> in /home/eelco/Dev/nixpkgs-branch/path and - /etc/nixos/nixpkgs/path. - + /etc/nixos/nixpkgs/path. + + If a path in the Nix search path starts with + http:// or https://, 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 + NIX_PATH to + + +nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz + + tells Nix to download the latest revision in the Nixpkgs/NixOS + 14.12 channel. The search path can be extended using the option, which takes precedence over diff --git a/doc/manual/command-ref/nix-build.xml b/doc/manual/command-ref/nix-build.xml index dc5841c27..d6b2e5e5a 100644 --- a/doc/manual/command-ref/nix-build.xml +++ b/doc/manual/command-ref/nix-build.xml @@ -58,6 +58,13 @@ and so on). nix-build will use default.nix in the current directory, if it exists. +If an element of paths starts with +http:// or https://, 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 +default.nix. + nix-build is essentially a wrapper around nix-instantiate @@ -175,6 +182,15 @@ bar +Build the GNU Hello package from the latest revision of the +master branch of Nixpkgs: + + +$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello + + + + diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml index 45a99b27d..5e40317f1 100644 --- a/doc/manual/command-ref/nix-env.xml +++ b/doc/manual/command-ref/nix-env.xml @@ -154,7 +154,15 @@ also . , , and operations to obtain derivations. The default is - ~/.nix-defexpr. + ~/.nix-defexpr. + + If the argument starts with http:// or + https://, 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 default.nix. + + @@ -496,6 +504,18 @@ the following paths will be substituted: +To install Firefox from the latest revision in the Nixpkgs/NixOS +14.12 channel: + + +$ nix-env -f https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz -iA firefox + + +(The GitHub repository nixpkgs-channels is updated +automatically from the main nixpkgs repository +after certain tests have succeeded and binaries have been built and +uploaded to the binary cache at cache.nixos.org.) + @@ -1129,54 +1149,103 @@ user environment elements, etc. --> Examples +To show installed packages: + -$ nix-env -q (show installed derivations) +$ nix-env -q bison-1.875c docbook-xml-4.2 firefox-1.0.4 MPlayer-1.0pre7 ORBit2-2.8.3 -... +… + -$ nix-env -qa (show available derivations) + + +To show available packages: + + +$ nix-env -qa firefox-1.0.7 GConf-2.4.0.1 MPlayer-1.0pre7 ORBit2-2.8.3 -... +… + -$ nix-env -qas (show status of available derivations) + + +To show the status of available packages: + + +$ nix-env -qas -P- firefox-1.0.7 (not installed but present) --S GConf-2.4.0.1 (not present, but there is a substitute for fast installation) --S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!) IP- ORBit2-2.8.3 (installed and by definition present) -... +… + -(show available derivations in the Nix expression foo.nix) + + +To show available packages in the Nix expression foo.nix: + + $ nix-env -f ./foo.nix -qa foo-1.2.3 + -$ nix-env -qc (compare installed versions to what’s available) + + +To compare installed versions to what’s available: + + +$ nix-env -qc ... acrobat-reader-7.0 - ? (package is not available at all) autoconf-2.59 = 2.59 (same version) firefox-1.0.4 < 1.0.7 (a more recent version is available) ... + -$ nix-env -qa '.*zip.*' (show all packages with “zip” in the name) + + +To show all packages with “zip” in the name: + + +$ nix-env -qa '.*zip.*' bzip2-1.0.6 gzip-1.6 zip-3.0 -... +… + -$ nix-env -qa '.*(firefox|chromium).*' (show all packages with “firefox” or “chromium” in the name) + + +To show all packages with “firefox” or +“chromium” in the name: + + +$ 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 -... +… + + +To show all packages in the latest revision of the Nixpkgs +repository: + + +$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa + + + + diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml index 77dd32653..9e3e6d188 100644 --- a/doc/manual/command-ref/nix-shell.xml +++ b/doc/manual/command-ref/nix-shell.xml @@ -61,6 +61,13 @@ derivation for development. shell.nix if it exists, and default.nix otherwise. +If path starts with +http:// or https://, 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 +default.nix. + If the derivation defines the variable shellHook, it will be evaluated after $stdenv/setup 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 … +The -p flag looks up Nixpkgs in the Nix search +path. You can override it by passing or setting +NIX_PATH. For example, the following gives you a shell +containing the Pan package from a specific revision of Nixpkgs: + + +$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz + +[nix-shell:~]$ pan --version +Pan 0.139 + + diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml index 3cdf4e28f..6bdfdd55c 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 "" + builtins.fetchurl + url + + Download the specified URL and return the path of + the downloaded file. This function is not available if restricted evaluation mode is + enabled. + + + + + fetchTarball + url + + Download the specified URL, unpack it and return + the path of the unpacked tree. The file must be a tape archive + (.tar) compressed with + gzip, bzip2 or + xz. 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. + + +with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {}; + +stdenv.mkDerivation { … } + + + + + This function is not available if restricted evaluation mode is + enabled. + + + + builtins.filter f xs diff --git a/src/libexpr/download.cc b/src/libexpr/download.cc index 18ab6fbcd..062622000 100644 --- a/src/libexpr/download.cc +++ b/src/libexpr/download.cc @@ -212,6 +212,7 @@ Path downloadFileCached(const string & url, bool unpack) printMsg(lvlInfo, format("unpacking ‘%1%’...") % url); Path tmpDir = createTempDir(); AutoDelete autoDelete(tmpDir, true); + // FIXME: this requires GNU tar for decompression. runProgram("tar", true, {"xf", storePath, "-C", tmpDir, "--strip-components", "1"}, ""); unpackedStorePath = store->addToStore(name, tmpDir, true, htSHA256, defaultPathFilter, false); }