nordic-dev.net/nix
nordic-dev.net/nix
2
0
Fork 0
mirror of https://github.com/NixOS/nix.git synced 2024-10-31 14:20:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Eelco Dolstra 2014-12-13 23:16:08 +01:00
parent e5a51fab24
commit 3b88d03714
7 changed files with 163 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/manual/command-ref/nix-channel.xml
View File

@ -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>

7
doc/manual/command-ref/nix-pull.xml
View File

@ -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>

10
doc/manual/installation/multi-user.xml
View File

@ -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>

136
doc/manual/packages/basic-package-mgmt.xml
View File

@ -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>

44
doc/manual/packages/channels.xml
View File

@ -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>

2
doc/manual/packages/garbage-collection.xml
View File

@ -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>

6
doc/manual/packages/profiles.xml
View File

@ -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>