diff --git a/doc/manual.xml b/doc/manual.xml
index c4f1128ea77..b067549e8fd 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -31,5 +31,42 @@
+
+
+
+
+ Language Support
+
+
+ Perl
+ * Generic Perl builder
+
+
+
+ Python
+ * Wrapper generation
+
+
+
+ Haskell
+ TODO
+
+
+
+ Java
+ TODO; Java support needs lots of improvement
+
+
+
+ TeX / LaTeX
+ * Special support for building TeX documents
+
+
+
+
+
+
+
+
diff --git a/doc/outline.txt b/doc/outline.txt
index a7dfc3bdc86..816cdbdc3ed 100644
--- a/doc/outline.txt
+++ b/doc/outline.txt
@@ -1,23 +1,3 @@
-- Intro
-
- - Goal of this manual
-
-
-- Quick start to adding a package
-
- (Some of this can be copied/moved from the Nix manual)
-
- - Hello example
- - Nix expr
- - Update all-packages.nix
- - How to test
- - How to debug failing builds
-
- - Subversion example
-
- - Some X example?
-
-
- The standard environment
(Some of this can be moved from the Nix manual)
diff --git a/doc/package-notes.xml b/doc/package-notes.xml
new file mode 100644
index 00000000000..6291abbe9bd
--- /dev/null
+++ b/doc/package-notes.xml
@@ -0,0 +1,191 @@
+
+
+Package Notes
+
+This chapter contains information about how to use and maintain
+the Nix expressions for a number of specific packages, such as the
+Linux kernel or X.org.
+
+
+
+
+
+
+Linux kernel
+
+The Nix expressions to build the Linux kernel are in pkgs/os-specific/linux/kernel.
+
+The function that builds the kernel has an argument
+kernelPatches which should be a list of
+{name, patch, extraConfig} attribute sets, where
+name is the name of the patch (which is included in
+the kernel’s meta.description attribute),
+patch is the patch itself (possibly compressed),
+and extraConfig (optional) is a string specifying
+extra options to be concatenated to the kernel configuration file
+(.config).
+
+The kernel derivation exports an attribute
+features specifying whether optional functionality
+is or isn’t enabled. This is used in NixOS to implement
+kernel-specific behaviour. For instance, if the kernel has the
+iwlwifi feature (i.e. has built-in support for
+Intel wireless chipsets), then NixOS doesn’t have to build the
+external iwlwifi package:
+
+
+modulesTree = [kernel]
+ ++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
+ ++ ...;
+
+
+
+
+How to add a new (major) version of the Linux kernel to Nixpkgs:
+
+
+
+
+ Copy (svn cp) the old Nix expression
+ (e.g. linux-2.6.21.nix) to the new one
+ (e.g. linux-2.6.22.nix) and update it.
+
+
+
+ Add the new kernel to all-packages.nix
+ (e.g., create an attribute
+ kernel_2_6_22).
+
+
+
+ Now we’re going to update the kernel configuration. First
+ unpack the kernel. Then for each supported platform
+ (i686, x86_64,
+ uml) do the following:
+
+
+
+
+ Make an svn copy from the old
+ config (e.g. config-2.6.21-i686-smp) to
+ the new one
+ (e.g. config-2.6.22-i686-smp).
+
+
+
+ Copy the config file for this platform
+ (e.g. config-2.6.22-i686-smp) to
+ .config in the kernel source tree.
+
+
+
+
+ Run make oldconfig
+ ARCH={i386,x86_64,um}
+ and answer all questions. (For the uml configuration, also
+ add SHELL=bash.) Make sure to keep the
+ configuration consistent between platforms (i.e. don’t
+ enable some feature on i686 and disable
+ it on x86_64).
+
+
+
+
+ If needed you can also run make
+ menuconfig:
+
+
+$ nix-env -i ncurses
+$ export NIX_CFLAGS_LINK=-lncurses
+$ make menuconfig ARCH=arch
+
+
+
+
+
+ Make sure that
+ CONFIG_FB_TILEBLITTING is not
+ set (otherwise fbsplash won't
+ work). This option has a tendency to be enabled as a
+ side-effect of other options. If it is, investigate why
+ (there's probably another option that forces it to be on)
+ and fix it.
+
+
+
+ Copy .config over the new config
+ file (e.g. config-2.6.22-i686-smp).
+
+
+
+
+
+
+
+
+
+ Test building the kernel: nix-build -A
+ kernel_2_6_22. If it compiles, ship it! For extra
+ credit, try booting NixOS with it.
+
+
+
+ It may be that the new kernel requires updating the external
+ kernel modules and kernel-dependent packages listed in the
+ kernelPackagesFor function in
+ all-packages.nix (such as the NVIDIA drivers,
+ AUFS, splashutils, etc.). If the updated packages aren’t
+ backwards compatible with older kernels, you need to keep the
+ older versions and use some conditionals. For example, new
+ kernels require splashutils 1.5 while old kernel require 1.3, so
+ kernelPackagesFor says:
+
+
+splashutils =
+ if kernel.features ? fbSplash then splashutils_13 else
+ if kernel.features ? fbConDecor then splashutils_15 else
+ null;
+
+splashutils_13 = ...;
+splashutils_15 = ...;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ X.org
+ * Expression is auto-generated
+ * How to update
+
+
+
+
+
+
+ Gnome
+ * Expression is auto-generated
+ * How to update
+
+
+
+
+
+
+ GCC
+ …
+
+
+
+
diff --git a/pkgs/os-specific/linux/kernel/README b/pkgs/os-specific/linux/kernel/README
deleted file mode 100644
index cf437e4bc48..00000000000
--- a/pkgs/os-specific/linux/kernel/README
+++ /dev/null
@@ -1,26 +0,0 @@
-*** Updating the kernel configs ***
-
-- Copy the old Nix expression (e.g. linux-2.6.21.nix) to the new one
- (e.g. linux-2.6.22.nix) and update it.
-- Add an new attribute to all-packages.nix.
-- Unpack the new kernel.
-
-For each platform (i686, x86-64, uml):
-
-- Make an svn copy from the old config (e.g. config-2.6.21-i686-smp)
- to the new one (e.g. (e.g. config-2.6.22-i686-smp).
-- Copy the config file for this platform
- (e.g. config-2.6.22-i686-smp) to .config in the kernel source tree.
-- Run `make oldconfig ARCH={i386,x86_64,um}', answer all questions.
- (For the uml configuration, also add "SHELL=bash".)
-- Make sure that CONFIG_FB_TILEBLITTING is NOT SET (otherwise fbsplash
- won't work). If it is, investigate why (there's probably another
- option that forces it to be on) and fix it.
-- Copy .config over the new config file (e.g. config-2.6.21-i686-smp).
-
-
-- To do `make menuconfig':
-
- $ nix-env -i ncurses
- $ export NIX_CFLAGS_LINK=-lncurses
- $ make menuconfig ARCH=