* 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> 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> <section>
@ -49,12 +82,12 @@ NixOS.</para>
<example xml:id='module-syntax'><title>Usual module content</title> <example xml:id='module-syntax'><title>Usual module content</title>
<programlisting> <programlisting>
{config, pkgs, ...}: <co xml:id='module-syntax-1' /> { config, pkgs, ... }: <co xml:id='module-syntax-1' />
{ {
imports = [ imports =
<co xml:id='module-syntax-2' /> [ <co xml:id='module-syntax-2' />
]; ];
options = { options = {
<co xml:id='module-syntax-3' /> <co xml:id='module-syntax-3' />
@ -180,7 +213,7 @@ NixOS.</para>
<example xml:id='locate-example'><title>Locate Module Example</title> <example xml:id='locate-example'><title>Locate Module Example</title>
<programlisting> <programlisting>
{config, pkgs, ...}: { config, pkgs, ... }:
with pkgs.lib; with pkgs.lib;
@ -200,9 +233,7 @@ let
in in
{ {
imports = [ imports = [ /etc/nixos/nixos/modules/services/scheduling/cron.nix ];
/etc/nixos/nixos/modules/services/scheduling/cron.nix
];
options = { options = {
services.locate = { 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 Nix package manager is installed.</para></footnote> from the NixOS
source tree as follows: source tree as follows:
<screen> <screen>
$ nix-build tests/ -A nfs.test $ nix-build tests/ -A nfs.test
</screen> </screen>
This performs an automated test of the NFS client and server This performs an automated test of the NFS client and server
functionality in the Linux kernel, including file locking 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 <filename>log.html</filename>, which can be viewed using a web
browser like this: browser like this:
<screen> <screen>
$ icecat result/log.html $ icecat result/log.html
</screen> </screen>
</para> </para>
<para> <para>
It is also possible to run the test environment interactively, It is also possible to run the test environment interactively,
allowing you to experiment with the VMs. For example: allowing you to experiment with the VMs. For example:
<screen> <screen>
$ nix-build tests/ -A nfs.driver $ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-run-vms $ ./result/bin/nixos-run-vms
</screen> </screen>
The script <command>nixos-run-vms</command> starts the three The script <command>nixos-run-vms</command> starts the three
virtual machines defined in the NFS test using QEMU/KVM. The root 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 Finally, the test itself can be run interactively. This is
particularly useful when developing or debugging a test: particularly useful when developing or debugging a test:
<screen> <screen>
$ nix-build tests/ -A nfs.driver $ nix-build tests/ -A nfs.driver
$ ./result/bin/nixos-test-driver $ ./result/bin/nixos-test-driver
starting VDE switch for network 1 starting VDE switch for network 1
&gt; &gt;
</screen> </screen>
Perl statements can now be typed in to start or manipulate the Perl statements can now be typed in to start or manipulate the
VMs: VMs:
<screen> <screen>
&gt; startAll; &gt; startAll;
(the VMs start booting) (the VMs start booting)
&gt; $server-&gt;waitForJob("nfs-kernel-nfsd"); &gt; $server-&gt;waitForJob("nfs-kernel-nfsd");
&gt; $client1-&gt;succeed("flock -x /data/lock -c 'sleep 100000' &amp;"); &gt; $client1-&gt;succeed("flock -x /data/lock -c 'sleep 100000' &amp;");
&gt; $client2-&gt;fail("flock -n -s /data/lock true"); &gt; $client2-&gt;fail("flock -n -s /data/lock true");
&gt; $client1-&gt;shutdown; &gt; $client1-&gt;shutdown;
(this releases client1's lock) (this releases client1's lock)
&gt; $client2-&gt;succeed("flock -n -s /data/lock true"); &gt; $client2-&gt;succeed("flock -n -s /data/lock true");
</screen> </screen>
The function <command>testScript</command> executes the entire The function <command>testScript</command> executes the entire
test script and drops you back into the test driver command line 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> <example xml:id='ex-config'><title>NixOS configuration</title>
<screen> <screen>
{ {
boot.initrd.kernelModules = [ "ata_piix" ];
boot.loader.grub.enable = true;
boot.loader.grub.device = "/dev/sda"; boot.loader.grub.device = "/dev/sda";
fileSystems = [ fileSystems =
{ mountPoint = "/"; [ { mountPoint = "/";
label = "nixos"; device = "/dev/disk/by-label/nixos";
} }
]; ];
swapDevices = [ swapDevices =
{ label = "swap"; } [ { device = "/dev/disk/by-label/swap"; } ];
];
services.sshd.enable = true; services.sshd.enable = true;
}</screen> }</screen>
@ -258,15 +255,13 @@ $ reboot</screen>
<para>The file <filename>/etc/nixos/configuration.nix</filename> <para>The file <filename>/etc/nixos/configuration.nix</filename>
contains the current configuration of your machine. Whenever youve contains the current configuration of your machine. Whenever youve
changed something to that file, or to the NixOS/Nixpkgs sources in changed something to that file, you should do
<filename>/etc/nixos/nixos</filename> and
<filename>/etc/nixos/nixpkgs</filename>, respectively, you should do
<screen> <screen>
$ nixos-rebuild switch</screen> $ nixos-rebuild switch</screen>
to build the new configuration, make it the default configuration for 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> (e.g., by restarting system services).</para>
<para>You can also do <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 to build the configuration but nothing more. This is useful to see
whether everything compiles cleanly.</para> 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> </section>
@ -304,28 +313,32 @@ whether everything compiles cleanly.</para>
<section> <section>
<title>Keeping NixOS up to date</title> <title>Upgrading NixOS</title>
<para>The currently best way to keep your NixOS installation up to <para>The best way to keep your NixOS installation up to date is to
date is to track the NixOS Subversion repository. The program use the <literal>nixos-unstable</literal> channel. (A channel is a
<command>nixos-checkout</command> does that for you. It will Nix mechanism for distributing Nix expressions and associated
check if the NixOS/NixPkgs sources are present and if they are under a binaries.) The NixOS channel is updated automatically from NixOSs
version control system (VCS) before updating them to the latest version. If your Subversion repository after running certain tests and building most
sources are not under a VCS, then you can rename them before packages.</para>
running <command>nixos-checkout</command> which will checkout the sources.</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> <screen>
$ nixos-checkout $ nix-channel --add http://nixos.org/releases/nixos/channels/nixos-unstable
$ nixos-rebuild switch</screen> </screen>
(Or instead of <literal>switch</literal>, use any of the alternatives You can then upgrade NixOS to the latest version in the channel by
shown in <xref linkend="sec-changing-config"/>.)</para> running
<screen>
$ nix-channel --update
</screen>
and running the <command>nixos-rebuild</command> command as described
in <xref linkend="sec-changing-config"/>.</para>
</section> </section>
</chapter> </chapter>

View file

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