nixpkgs/nixos/doc/manual/development/sources.xml
Eelco Dolstra 10ce7ae769 Document the nixpkgs-channels repo
This replaces update-channel-branches.sh with standard Git
invocations.
2015-05-20 14:20:53 +02:00

110 lines
3.7 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-getting-sources">
<title>Getting the Sources</title>
<para>By default, NixOSs <command>nixos-rebuild</command> command
uses the NixOS and Nixpkgs sources provided by the
<literal>nixos-unstable</literal> channel (kept in
<filename>/nix/var/nix/profiles/per-user/root/channels/nixos</filename>).
To modify NixOS, however, you should check out the latest sources from
Git. This is done using the following command:
<screen>
$ nixos-checkout <replaceable>/my/sources</replaceable>
</screen>
or
<screen>
$ mkdir -p <replaceable>/my/sources</replaceable>
$ cd <replaceable>/my/sources</replaceable>
$ nix-env -i git
$ git clone git://github.com/NixOS/nixpkgs.git
$ cd nixpkgs
$ git remote add channels git://github.com/NixOS/nixpkgs-channels.git
$ git remote update channels
</screen>
This will check out the latest NixOS sources to
<filename><replaceable>/my/sources</replaceable>/nixpkgs/nixos</filename>
and the Nixpkgs sources to
<filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>.
(The NixOS source tree lives in a subdirectory of the Nixpkgs
repository.) The remote <literal>channels</literal> refers to a
read-only repository that tracks the Nixpkgs/NixOS channels (see <xref
linkend="sec-upgrading"/> for more information about channels). Thus,
the Git branch <literal>channels/nixos-14.12</literal> will contain
the latest built and tested version available in the
<literal>nixos-14.12</literal> channel.</para>
<para>Its often inconvenient to develop directly on the master
branch, since if somebody has just committed (say) a change to GCC,
then the binary cache may not have caught up yet and youll have to
rebuild everything from source. So you may want to create a local
branch based on your current NixOS version:
<screen>
$ nixos-version
14.04.273.ea1952b (Baboon)
$ git checkout -b local ea1952b
</screen>
Or, to base your local branch on the latest version available in a
NixOS channel:
<screen>
$ git remote update channels
$ git checkout -b local channels/nixos-14.12
</screen>
(Replace <literal>nixos-14.12</literal> with the name of the channel
you want to use.) You can use <command>git merge</command> or
<command>git rebase</command> to keep your local branch in sync with
the channel, e.g.
<screen>
$ git remote update channels
$ git merge channels/nixos-14.12
</screen>
You can use <command>git cherry-pick</command> to copy commits from
your local branch to the upstream branch.</para>
<para>If you want to rebuild your system using your (modified)
sources, you need to tell <command>nixos-rebuild</command> about them
using the <option>-I</option> flag:
<screen>
$ nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
</screen>
</para>
<para>If you want <command>nix-env</command> to use the expressions in
<replaceable>/my/sources</replaceable>, use <command>nix-env -f
<replaceable>/my/sources</replaceable>/nixpkgs</command>, or change
the default by adding a symlink in
<filename>~/.nix-defexpr</filename>:
<screen>
$ ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs
</screen>
You may want to delete the symlink
<filename>~/.nix-defexpr/channels_root</filename> to prevent roots
NixOS channel from clashing with your own tree.</para>
<!-- FIXME: not sure what this means.
<para>You should not pass the base directory
<filename><replaceable>/my/sources</replaceable></filename>
to <command>nix-env</command>, as it will break after interpreting expressions
in <filename>nixos/</filename> as packages.</para>
-->
</chapter>