From 649ccdd2db16b209338b1903766fd86800bee27a Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Wed, 27 Aug 2008 12:59:55 +0000
Subject: [PATCH] * Moved the Linux kernel maintenance notes to the manual,
expanded them.
svn path=/nixpkgs/trunk/; revision=12739
---
doc/manual.xml | 37 ++++++
doc/outline.txt | 20 ---
doc/package-notes.xml | 191 +++++++++++++++++++++++++++
pkgs/os-specific/linux/kernel/README | 26 ----
4 files changed, 228 insertions(+), 46 deletions(-)
create mode 100644 doc/package-notes.xml
delete mode 100644 pkgs/os-specific/linux/kernel/README
diff --git a/doc/manual.xml b/doc/manual.xml
index c4f1128ea77e..b067549e8fdf 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -31,5 +31,42 @@
<xi:include href="introduction.xml" />
<xi:include href="quick-start.xml" />
<xi:include href="stdenv.xml" />
+
+
+ <!-- outline -->
+ <chapter>
+ <title>Language Support</title>
+
+ <section>
+ <title>Perl</title>
+ <para>* Generic Perl builder</para>
+ </section>
+
+ <section>
+ <title>Python</title>
+ <para>* Wrapper generation</para>
+ </section>
+
+ <section>
+ <title>Haskell</title>
+ <para>TODO</para>
+ </section>
+
+ <section>
+ <title>Java</title>
+ <para>TODO; Java support needs lots of improvement</para>
+ </section>
+
+ <section>
+ <title>TeX / LaTeX</title>
+ <para>* Special support for building TeX documents</para>
+ </section>
+
+ </chapter>
+
+
+ <xi:include href="package-notes.xml" />
+
+
</book>
diff --git a/doc/outline.txt b/doc/outline.txt
index a7dfc3bdc86c..816cdbdc3ed7 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 000000000000..6291abbe9bd8
--- /dev/null
+++ b/doc/package-notes.xml
@@ -0,0 +1,191 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="chap-introduction">
+
+<title>Package Notes</title>
+
+<para>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.</para>
+
+
+<!--============================================================-->
+
+<section>
+
+<title>Linux kernel</title>
+
+<para>The Nix expressions to build the Linux kernel are in <link
+xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/os-specific/linux/kernel"><filename>pkgs/os-specific/linux/kernel</filename></link>.</para>
+
+<para>The function that builds the kernel has an argument
+<varname>kernelPatches</varname> which should be a list of
+<literal>{name, patch, extraConfig}</literal> attribute sets, where
+<varname>name</varname> is the name of the patch (which is included in
+the kernel’s <varname>meta.description</varname> attribute),
+<varname>patch</varname> is the patch itself (possibly compressed),
+and <varname>extraConfig</varname> (optional) is a string specifying
+extra options to be concatenated to the kernel configuration file
+(<filename>.config</filename>).</para>
+
+<para>The kernel derivation exports an attribute
+<varname>features</varname> 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
+<varname>iwlwifi</varname> feature (i.e. has built-in support for
+Intel wireless chipsets), then NixOS doesn’t have to build the
+external <varname>iwlwifi</varname> package:
+
+<programlisting>
+modulesTree = [kernel]
+ ++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
+ ++ ...;
+</programlisting>
+
+</para>
+
+<para>How to add a new (major) version of the Linux kernel to Nixpkgs:
+
+<orderedlist>
+
+ <listitem>
+ <para>Copy (<command>svn cp</command>) the old Nix expression
+ (e.g. <filename>linux-2.6.21.nix</filename>) to the new one
+ (e.g. <filename>linux-2.6.22.nix</filename>) and update it.</para>
+ </listitem>
+
+ <listitem>
+ <para>Add the new kernel to <filename>all-packages.nix</filename>
+ (e.g., create an attribute
+ <varname>kernel_2_6_22</varname>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Now we’re going to update the kernel configuration. First
+ unpack the kernel. Then for each supported platform
+ (<literal>i686</literal>, <literal>x86_64</literal>,
+ <literal>uml</literal>) do the following:
+
+ <orderedlist>
+
+ <listitem>
+ <para>Make an <command>svn copy</command> from the old
+ config (e.g. <filename>config-2.6.21-i686-smp</filename>) to
+ the new one
+ (e.g. <filename>config-2.6.22-i686-smp</filename>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the config file for this platform
+ (e.g. <filename>config-2.6.22-i686-smp</filename>) to
+ <filename>.config</filename> in the kernel source tree.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Run <literal>make oldconfig
+ ARCH=<replaceable>{i386,x86_64,um}</replaceable></literal>
+ and answer all questions. (For the uml configuration, also
+ add <literal>SHELL=bash</literal>.) Make sure to keep the
+ configuration consistent between platforms (i.e. don’t
+ enable some feature on <literal>i686</literal> and disable
+ it on <literal>x86_64</literal>).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>If needed you can also run <literal>make
+ menuconfig</literal>:
+
+ <screen>
+$ nix-env -i ncurses
+$ export NIX_CFLAGS_LINK=-lncurses
+$ make menuconfig ARCH=<replaceable>arch</replaceable></screen>
+
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Make sure that
+ <literal>CONFIG_FB_TILEBLITTING</literal> is <emphasis>not
+ set</emphasis> (otherwise <command>fbsplash</command> 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.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy <filename>.config</filename> over the new config
+ file (e.g. <filename>config-2.6.22-i686-smp</filename>).</para>
+ </listitem>
+
+ </orderedlist>
+
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>Test building the kernel: <literal>nix-build -A
+ kernel_2_6_22</literal>. If it compiles, ship it! For extra
+ credit, try booting NixOS with it.</para>
+ </listitem>
+
+ <listitem>
+ <para>It may be that the new kernel requires updating the external
+ kernel modules and kernel-dependent packages listed in the
+ <varname>kernelPackagesFor</varname> function in
+ <filename>all-packages.nix</filename> (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
+ <varname>kernelPackagesFor</varname> says:
+
+ <programlisting>
+splashutils =
+ if kernel.features ? fbSplash then splashutils_13 else
+ if kernel.features ? fbConDecor then splashutils_15 else
+ null;
+
+splashutils_13 = ...;
+splashutils_15 = ...;</programlisting>
+
+ </para>
+ </listitem>
+
+</orderedlist>
+
+</para>
+
+</section>
+
+
+<!--============================================================-->
+
+<section>
+ <title>X.org</title>
+ <para>* Expression is auto-generated</para>
+ <para>* How to update</para>
+</section>
+
+
+<!--============================================================-->
+
+<section>
+ <title>Gnome</title>
+ <para>* Expression is auto-generated</para>
+ <para>* How to update</para>
+</section>
+
+
+<!--============================================================-->
+
+<section>
+ <title>GCC</title>
+ <para>…</para>
+</section>
+
+
+</chapter>
diff --git a/pkgs/os-specific/linux/kernel/README b/pkgs/os-specific/linux/kernel/README
deleted file mode 100644
index cf437e4bc482..000000000000
--- 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=<arch>