* Describe the NixOS channel.

svn path=/nixos/trunk/; revision=34084

doc/manual/development.xml

@@ -7,6 +7,39 @@
 NixOS.</para>
 
 
+<!--===============================================================-->
+
+<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>
@@ -52,8 +85,8 @@ NixOS.</para>
 { config, pkgs, ... }: <co xml:id='module-syntax-1' />
 
 {
-  imports = [
+  imports =
-    <co xml:id='module-syntax-2' />
+    [ <co xml:id='module-syntax-2' />
     ];
 
   options = {
@@ -200,9 +233,7 @@ let
 in
 
 {
-  imports = [
+  imports = [ /etc/nixos/nixos/modules/services/scheduling/cron.nix ];
-    /etc/nixos/nixos/modules/services/scheduling/cron.nix
-  ];
 
   options = {
     services.locate = {

doc/manual/installation.xml

@@ -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 = [
+  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;
 }</screen>
@@ -258,15 +255,13 @@ $ reboot</screen>
 
 <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
+changed something to that file, you should do
-<filename>/etc/nixos/nixos</filename> and
-<filename>/etc/nixos/nixpkgs</filename>, respectively, 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
+<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 NixOS’s
-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>
-$ 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>
 
-
-
-
 </chapter>

doc/manual/manual.xml

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