* Describe the NixOS channel.

svn path=/nixos/trunk/; revision=34084
This commit is contained in:
Eelco Dolstra 2012-05-14 03:59:38 +00:00
parent b57e12dfee
commit ae8d4a2f7c
3 changed files with 109 additions and 67 deletions

View file

@ -7,6 +7,39 @@
NixOS.</para>
<!--===============================================================-->
<section>
<title>Hacking on NixOS</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
Subversion. This is done using the following command:
<screen>
$ nixos-checkout
</screen>
This will check out the latest NixOS sources to
<filename>/etc/nixos/nixos</filename> and the Nixpkgs sources to
<filename>/etc/nixos/nixpkgs</filename>. 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 -I /etc/nixos
</screen>
</para>
</section>
<!--===============================================================-->
<section>
@ -49,12 +82,12 @@ NixOS.</para>
<example xml:id='module-syntax'><title>Usual module content</title>
<programlisting>
{config, pkgs, ...}: <co xml:id='module-syntax-1' />
{ config, pkgs, ... }: <co xml:id='module-syntax-1' />
{
imports = [
<co xml:id='module-syntax-2' />
];
imports =
[ <co xml:id='module-syntax-2' />
];
options = {
<co xml:id='module-syntax-3' />
@ -180,7 +213,7 @@ NixOS.</para>
<example xml:id='locate-example'><title>Locate Module Example</title>
<programlisting>
{config, pkgs, ...}:
{ config, pkgs, ... }:
with pkgs.lib;
@ -200,9 +233,7 @@ let
in
{
imports = [
/etc/nixos/nixos/modules/services/scheduling/cron.nix
];
imports = [ /etc/nixos/nixos/modules/services/scheduling/cron.nix ];
options = {
services.locate = {
@ -402,9 +433,9 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
Nix package manager is installed.</para></footnote> from the NixOS
source tree as follows:
<screen>
$ nix-build tests/ -A nfs.test
</screen>
<screen>
$ nix-build tests/ -A nfs.test
</screen>
This performs an automated test of the NFS client and server
functionality in the Linux kernel, including file locking
@ -422,19 +453,19 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
<filename>log.html</filename>, which can be viewed using a web
browser like this:
<screen>
$ icecat result/log.html
</screen>
<screen>
$ icecat result/log.html
</screen>
</para>
<para>
It is also possible to run the test environment interactively,
allowing you to experiment with the VMs. For example:
<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-run-vms
</screen>
<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-run-vms
</screen>
The script <command>nixos-run-vms</command> starts the three
virtual machines defined in the NFS test using QEMU/KVM. The root
@ -447,26 +478,26 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/
Finally, the test itself can be run interactively. This is
particularly useful when developing or debugging a test:
<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-test-driver
starting VDE switch for network 1
&gt;
</screen>
<screen>
$ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-test-driver
starting VDE switch for network 1
&gt;
</screen>
Perl statements can now be typed in to start or manipulate the
VMs:
<screen>
&gt; startAll;
(the VMs start booting)
&gt; $server-&gt;waitForJob("nfs-kernel-nfsd");
&gt; $client1-&gt;succeed("flock -x /data/lock -c 'sleep 100000' &amp;");
&gt; $client2-&gt;fail("flock -n -s /data/lock true");
&gt; $client1-&gt;shutdown;
(this releases client1's lock)
&gt; $client2-&gt;succeed("flock -n -s /data/lock true");
</screen>
<screen>
&gt; startAll;
(the VMs start booting)
&gt; $server-&gt;waitForJob("nfs-kernel-nfsd");
&gt; $client1-&gt;succeed("flock -x /data/lock -c 'sleep 100000' &amp;");
&gt; $client2-&gt;fail("flock -n -s /data/lock true");
&gt; $client1-&gt;shutdown;
(this releases client1's lock)
&gt; $client2-&gt;succeed("flock -n -s /data/lock true");
</screen>
The function <command>testScript</command> executes the entire
test script and drops you back into the test driver command line

View file

@ -228,19 +228,16 @@ $ reboot</screen>
<example xml:id='ex-config'><title>NixOS configuration</title>
<screen>
{
boot.initrd.kernelModules = [ "ata_piix" ];
boot.loader.grub.enable = true;
boot.loader.grub.device = "/dev/sda";
fileSystems = [
{ mountPoint = "/";
label = "nixos";
}
];
fileSystems =
[ { mountPoint = "/";
device = "/dev/disk/by-label/nixos";
}
];
swapDevices = [
{ label = "swap"; }
];
swapDevices =
[ { device = "/dev/disk/by-label/swap"; } ];
services.sshd.enable = true;
}</screen>
@ -258,15 +255,13 @@ $ reboot</screen>
<para>The file <filename>/etc/nixos/configuration.nix</filename>
contains the current configuration of your machine. Whenever youve
changed something to that file, or to the NixOS/Nixpkgs sources in
<filename>/etc/nixos/nixos</filename> and
<filename>/etc/nixos/nixpkgs</filename>, respectively, you should do
changed something to that file, you should do
<screen>
$ nixos-rebuild switch</screen>
to build the new configuration, make it the default configuration for
booting, and try to effect the configuration in the running system
booting, and try to realise the configuration in the running system
(e.g., by restarting system services).</para>
<para>You can also do
@ -296,6 +291,20 @@ $ nixos-rebuild build</screen>
to build the configuration but nothing more. This is useful to see
whether everything compiles cleanly.</para>
<para>If you have a machine that supports hardware virtualisation, you
can also test the new configuration in a sandbox by building and
running a <emphasis>virtual machine</emphasis> that contains the
desired configuration. Just do
<screen>
$ nixos-rebuild build-vm
$ ./result/bin/run-*-vm
</screen>
The VM does not have use any data from your host system, so your
existing user accounts and home directories will not be
available.</para>
</section>
@ -304,28 +313,32 @@ whether everything compiles cleanly.</para>
<section>
<title>Keeping NixOS up to date</title>
<title>Upgrading NixOS</title>
<para>The currently best way to keep your NixOS installation up to
date is to track the NixOS Subversion repository. The program
<command>nixos-checkout</command> does that for you. It will
check if the NixOS/NixPkgs sources are present and if they are under a
version control system (VCS) before updating them to the latest version. If your
sources are not under a VCS, then you can rename them before
running <command>nixos-checkout</command> which will checkout the sources.</para>
<para>The best way to keep your NixOS installation up to date is to
use the <literal>nixos-unstable</literal> channel. (A channel is a
Nix mechanism for distributing Nix expressions and associated
binaries.) The NixOS channel is updated automatically from NixOSs
Subversion repository after running certain tests and building most
packages.</para>
<para>To build the latest and greatest, do
<para>NixOS automatically subscribes you to the NixOS channel. If for
some reason this is not the case, just do
<screen>
$ nixos-checkout
$ nixos-rebuild switch</screen>
$ nix-channel --add http://nixos.org/releases/nixos/channels/nixos-unstable
</screen>
(Or instead of <literal>switch</literal>, use any of the alternatives
shown in <xref linkend="sec-changing-config"/>.)</para>
You can then upgrade NixOS to the latest version in the channel by
running
<screen>
$ nix-channel --update
</screen>
and running the <command>nixos-rebuild</command> command as described
in <xref linkend="sec-changing-config"/>.</para>
</section>
</chapter>

View file

@ -21,9 +21,7 @@
</author>
<copyright>
<year>2007</year>
<year>2008</year>
<year>2009</year>
<year>2007-2012</year>
<holder>Eelco Dolstra</holder>
</copyright>