lix/doc/manual/command-ref/nix-channel.xml

205 lines
7 KiB
XML
Raw Normal View History

<refentry xmlns="http://docbook.org/ns/docbook"
2014-08-27 16:41:09 +00:00
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-nix-channel">
2014-09-16 12:57:45 +00:00
2007-09-19 14:01:41 +00:00
<refmeta>
<refentrytitle>nix-channel</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source">Nix</refmiscinfo>
2014-09-16 12:57:45 +00:00
<refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo>
2007-09-19 14:01:41 +00:00
</refmeta>
2005-04-09 17:16:00 +00:00
<refnamediv>
<refname>nix-channel</refname>
<refpurpose>manage Nix channels</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-channel</command>
<group choice='req'>
<arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg>
2005-04-09 17:16:00 +00:00
<arg choice='plain'><option>--remove</option> <replaceable>url</replaceable></arg>
<arg choice='plain'><option>--list</option></arg>
<arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg>
<arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg>
2005-04-09 17:16:00 +00:00
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsection><title>Description</title>
<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 both a set of Nix
expressions and a pointer to a binary cache. <phrase
condition="manual">See also <xref linkend="sec-channels"
/>.</phrase></para>
2005-04-09 17:16:00 +00:00
<para>This command has the following operations:
<variablelist>
<varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term>
2005-04-09 17:16:00 +00:00
<listitem><para>Adds a channel named
<replaceable>name</replaceable> with URL
<replaceable>url</replaceable> to the list of subscribed channels.
If <replaceable>name</replaceable> is omitted, it defaults to the
last component of <replaceable>url</replaceable>, with the
suffixes <literal>-stable</literal> or
<literal>-unstable</literal> removed.</para></listitem>
2005-04-09 17:16:00 +00:00
</varlistentry>
<varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term>
2005-04-09 17:16:00 +00:00
<listitem><para>Removes the channel named
<replaceable>name</replaceable> from the list of subscribed
channels.</para></listitem>
2005-04-09 17:16:00 +00:00
</varlistentry>
<varlistentry><term><option>--list</option></term>
<listitem><para>Prints the names and URLs of all subscribed
channels on standard output.</para></listitem>
2005-04-09 17:16:00 +00:00
</varlistentry>
<varlistentry><term><option>--update</option> [<replaceable>names</replaceable>…]</term>
2005-04-09 17:16:00 +00:00
<listitem><para>Downloads the Nix expressions of all subscribed
channels (or only those included in
<replaceable>names</replaceable> if specified), makes them the
default for <command>nix-env</command> operations (by symlinking
them from the directory <filename>~/.nix-defexpr</filename>), and
performs a <command>nix-pull</command> on the manifests of all
channels to make pre-built binaries available.</para></listitem>
2005-04-09 17:16:00 +00:00
</varlistentry>
<varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term>
<listitem><para>Reverts the previous call to <command>nix-channel
--update</command>. Optionally, you can specify a specific channel
generation number to restore.</para></listitem>
</varlistentry>
2005-04-09 17:16:00 +00:00
</variablelist>
</para>
<para>Note that <option>--add</option> does not automatically perform
an update.</para>
2005-04-09 17:16:00 +00:00
<para>The list of subscribed channels is stored in
<filename>~/.nix-channels</filename>.</para>
</refsection>
<refsection><title>Examples</title>
<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para>
<screen>
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
$ nix-channel --update
$ nix-env -iA nixpkgs.hello</screen>
<para>You can revert channel updates using <option>--rollback</option>:</para>
<screen>
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
"14.04.527.0e935f1"
$ nix-channel --rollback
switching from generation 483 to 482
$ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
"14.04.526.dbadfad"
</screen>
</refsection>
<refsection><title>Files</title>
<variablelist>
<varlistentry><term><filename>/nix/var/nix/profiles/<replaceable>username</replaceable>/channels</filename></term>
<listitem><para><command>nix-channel</command> uses a
<command>nix-env</command> profile to keep track of previous
versions of the subscribed channels. Every time you run
<command>nix-channel --update</command>, a new channel generation
(that is, a symlink to the channel Nix expressions in the Nix store)
is created. This enables <command>nix-channel --rollback</command>
to revert to previous versions.</para></listitem>
</varlistentry>
<varlistentry><term><filename>~/.nix-defexpr/channels</filename></term>
<listitem><para>This is a symlink to
<filename>/nix/var/nix/profiles/<replaceable>username</replaceable>/channels</filename>. It
ensures that <command>nix-env</command> can find your channels. In
a multi-user installation, you may also have
<filename>~/.nix-defexpr/channels_root</filename>, which links to
the channels of the root user.</para></listitem>
</varlistentry>
</variablelist>
</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 channels “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>
2005-04-09 17:16:00 +00:00
</refentry>