Author: eelco
Date: Mon May 14 03:59:38 2012
New Revision: 34084
URL: https://nixos.org/websvn/nix/?rev=34084&sc=1
Log:
* Describe the NixOS channel.
Modified:
nixos/trunk/doc/manual/development.xml
nixos/trunk/doc/manual/installation.xml
nixos/trunk/doc/manual/manual.xml
Modified: nixos/trunk/doc/manual/development.xml
==============================================================================
--- nixos/trunk/doc/manual/development.xml Mon May 14 02:02:45 2012
(r34083)
+++ nixos/trunk/doc/manual/development.xml Mon May 14 03:59:38 2012
(r34084)
@@ -11,6 +11,39 @@
<section>
+<title>Hacking on NixOS</title>
+
+<para>By default, NixOS’s <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>
+
<title>Extending NixOS</title>
<para>NixOS is based on a modular system for declarative configuration.
@@ -49,12 +82,12 @@
<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 @@
<example xml:id='locate-example'><title>Locate Module Example</title>
<programlisting>
-{config, pkgs, ...}:
+{ config, pkgs, ... }:
with pkgs.lib;
@@ -200,9 +233,7 @@
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 @@
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 @@
<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 @@
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
- >
- </screen>
+<screen>
+$ nix-build tests/ -A nfs.driver
+$ ./result/bin/nixos-test-driver
+starting VDE switch for network 1
+>
+</screen>
Perl statements can now be typed in to start or manipulate the
VMs:
- <screen>
- > startAll;
- (the VMs start booting)
- > $server->waitForJob("nfs-kernel-nfsd");
- > $client1->succeed("flock -x /data/lock -c 'sleep 100000' &");
- > $client2->fail("flock -n -s /data/lock true");
- > $client1->shutdown;
- (this releases client1's lock)
- > $client2->succeed("flock -n -s /data/lock true");
- </screen>
+<screen>
+> startAll;
+(the VMs start booting)
+> $server->waitForJob("nfs-kernel-nfsd");
+> $client1->succeed("flock -x /data/lock -c 'sleep 100000' &");
+> $client2->fail("flock -n -s /data/lock true");
+> $client1->shutdown;
+(this releases client1's lock)
+> $client2->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
Modified: nixos/trunk/doc/manual/installation.xml
==============================================================================
--- nixos/trunk/doc/manual/installation.xml Mon May 14 02:02:45 2012
(r34083)
+++ nixos/trunk/doc/manual/installation.xml Mon May 14 03:59:38 2012
(r34084)
@@ -228,19 +228,16 @@
<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";
- }
- ];
-
- swapDevices = [
- { label = "swap"; }
- ];
+ fileSystems =
+ [ { mountPoint = "/";
+ device = "/dev/disk/by-label/nixos";
+ }
+ ];
+
+ swapDevices =
+ [ { device = "/dev/disk/by-label/swap"; } ];
services.sshd.enable = true;
}</screen>
@@ -258,15 +255,13 @@
<para>The file <filename>/etc/nixos/configuration.nix</filename>
contains the current configuration of your machine. Whenever you’ve
-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 @@
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 @@
<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 NixOS’s
+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>
-
-</section>
+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>
Modified: nixos/trunk/doc/manual/manual.xml
==============================================================================
--- nixos/trunk/doc/manual/manual.xml Mon May 14 02:02:45 2012 (r34083)
+++ nixos/trunk/doc/manual/manual.xml Mon May 14 03:59:38 2012 (r34084)
@@ -21,9 +21,7 @@
</author>
<copyright>
- <year>2007</year>
- <year>2008</year>
- <year>2009</year>
+ <year>2007-2012</year>
<holder>Eelco Dolstra</holder>
</copyright>
_______________________________________________
nix-commits mailing list
[email protected]
http://lists.science.uu.nl/mailman/listinfo/nix-commits
