Document channel format and excise most mentions of manifests and nix-pull
This commit is contained in:
Eelco Dolstra
parent
e5a51fab24
commit
3b88d03714
7 changed files with 163 additions and 98 deletions
|
|
@ -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 <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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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>Assuming that you have downloaded and unpacked a release of Nix
|
||||
Packages, you can view the set of available packages in the release:
|
||||
<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:
|
||||
|
||||
<screen>
|
||||
$ nix-env -qaf nixpkgs-<replaceable>version</replaceable> '*'
|
||||
ant-blackdown-1.4.2
|
||||
$ 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 -qa
|
||||
aterm-2.2
|
||||
bash-3.0
|
||||
binutils-2.15
|
||||
bison-1.875d
|
||||
blackdown-1.4.2
|
||||
bzip2-1.0.2
|
||||
...</screen>
|
||||
…</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:
|
||||
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 nixpkgs-<replaceable>version</replaceable> gcc
|
||||
gcc-3.4.6
|
||||
gcc-4.0.3
|
||||
gcc-4.1.1</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 -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>
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -67,4 +67,4 @@ is a quick and easy way to clean up your system.</para>
|
|||
|
||||
<xi:include href="garbage-collector-roots.xml" />
|
||||
|
||||
</chapter>
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue