diff --git a/doc/manual/development.xml b/doc/manual/development.xml index 621e9fd4ffe..918bbe08a1a 100644 --- a/doc/manual/development.xml +++ b/doc/manual/development.xml @@ -7,6 +7,39 @@ NixOS. + + +
+ +Hacking on NixOS + +By default, NixOS’s nixos-rebuild command +uses the NixOS and Nixpkgs sources provided by the +nixos-unstable channel (kept in +/nix/var/nix/profiles/per-user/root/channels/nixos). +To modify NixOS, however, you should check out the latest sources from +Subversion. This is done using the following command: + + +$ nixos-checkout + + +This will check out the latest NixOS sources to +/etc/nixos/nixos and the Nixpkgs sources to +/etc/nixos/nixpkgs. If you want to rebuild your +system using your (modified) sources, you need to tell +nixos-rebuild about them using the + flag: + + +$ nixos-rebuild -I /etc/nixos + + + + +
+ +
@@ -49,12 +82,12 @@ NixOS. Usual module content -{config, pkgs, ...}: +{ config, pkgs, ... }: { - imports = [ - - ]; + imports = + [ + ]; options = { @@ -180,7 +213,7 @@ NixOS. Locate Module Example -{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. from the NixOS source tree as follows: - - $ nix-build tests/ -A nfs.test - + +$ nix-build tests/ -A nfs.test + 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/ log.html, which can be viewed using a web browser like this: - - $ icecat result/log.html - + +$ icecat result/log.html + It is also possible to run the test environment interactively, allowing you to experiment with the VMs. For example: - - $ nix-build tests/ -A nfs.driver - $ ./result/bin/nixos-run-vms - + +$ nix-build tests/ -A nfs.driver +$ ./result/bin/nixos-run-vms + The script nixos-run-vms 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: - - $ nix-build tests/ -A nfs.driver - $ ./result/bin/nixos-test-driver - starting VDE switch for network 1 - > - + +$ nix-build tests/ -A nfs.driver +$ ./result/bin/nixos-test-driver +starting VDE switch for network 1 +> + Perl statements can now be typed in to start or manipulate the VMs: - - > 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"); - + +> 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"); + The function testScript executes the entire test script and drops you back into the test driver command line diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index fda5c1491f4..0a69ce0ecba 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -228,19 +228,16 @@ $ reboot NixOS configuration { - 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; } @@ -258,15 +255,13 @@ $ reboot The file /etc/nixos/configuration.nix contains the current configuration of your machine. Whenever you’ve -changed something to that file, or to the NixOS/Nixpkgs sources in -/etc/nixos/nixos and -/etc/nixos/nixpkgs, respectively, you should do +changed something to that file, you should do $ nixos-rebuild switch 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). You can also do @@ -296,6 +291,20 @@ $ nixos-rebuild build to build the configuration but nothing more. This is useful to see whether everything compiles cleanly. +If you have a machine that supports hardware virtualisation, you +can also test the new configuration in a sandbox by building and +running a virtual machine that contains the +desired configuration. Just do + + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + +The VM does not have use any data from your host system, so your +existing user accounts and home directories will not be +available. +
@@ -304,28 +313,32 @@ whether everything compiles cleanly.
-Keeping NixOS up to date +Upgrading NixOS -The currently best way to keep your NixOS installation up to -date is to track the NixOS Subversion repository. The program -nixos-checkout 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 nixos-checkout which will checkout the sources. +The best way to keep your NixOS installation up to date is to +use the nixos-unstable 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. -To build the latest and greatest, do +NixOS automatically subscribes you to the NixOS channel. If for +some reason this is not the case, just do -$ nixos-checkout -$ nixos-rebuild switch +$ nix-channel --add http://nixos.org/releases/nixos/channels/nixos-unstable + -(Or instead of switch, use any of the alternatives -shown in .) +You can then upgrade NixOS to the latest version in the channel by +running + + +$ nix-channel --update + + +and running the nixos-rebuild command as described +in .
- - - diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index ff08a577ca0..b7852e9f1b1 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -21,9 +21,7 @@ - 2007 - 2008 - 2009 + 2007-2012 Eelco Dolstra