path: root/doc/package-notes.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="chap-package-notes">
 <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 xml:id="sec-linux-kernel">
  <title>Linux kernel</title>

  <para>
   The Nix expressions to build the Linux kernel are in
   <link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/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 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 copy 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>
         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>linuxPackagesFor</varname> function in
      <filename>all-packages.nix</filename> (such as the NVIDIA drivers, AUFS,
      etc.). If the updated packages aren’t backwards compatible with older
      kernels, you may need to keep the older versions around.
     </para>
    </listitem>
   </orderedlist>
  </para>
 </section>
<!--============================================================-->
 <section xml:id="sec-xorg">
  <title>X.org</title>

  <para>
   The Nix expressions for the X.org packages reside in
   <filename>pkgs/servers/x11/xorg/default.nix</filename>. This file is
   automatically generated from lists of tarballs in an X.org release. As such
   it should not be modified directly; rather, you should modify the lists, the
   generator script or the file
   <filename>pkgs/servers/x11/xorg/overrides.nix</filename>, in which you can
   override or add to the derivations produced by the generator.
  </para>

  <para>
   The generator is invoked as follows:
<screen>
$ cd pkgs/servers/x11/xorg
$ cat tarballs-7.5.list extra.list old.list \
  | perl ./generate-expr-from-tarballs.pl
</screen>
   For each of the tarballs in the <filename>.list</filename> files, the script
   downloads it, unpacks it, and searches its <filename>configure.ac</filename>
   and <filename>*.pc.in</filename> files for dependencies. This information is
   used to generate <filename>default.nix</filename>. The generator caches
   downloaded tarballs between runs. Pay close attention to the <literal>NOT
   FOUND: <replaceable>name</replaceable></literal> messages at the end of the
   run, since they may indicate missing dependencies. (Some might be optional
   dependencies, however.)
  </para>

  <para>
   A file like <filename>tarballs-7.5.list</filename> contains all tarballs in
   a X.org release. It can be generated like this:
<screen>
$ export i="mirror://xorg/X11R7.4/src/everything/"
$ cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
  | perl -e 'while (&lt;>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'i'}$2\n"; }; }' \
  | sort > tarballs-7.4.list
</screen>
   <filename>extra.list</filename> contains libraries that aren’t part of
   X.org proper, but are closely related to it, such as
   <literal>libxcb</literal>. <filename>old.list</filename> contains some
   packages that were removed from X.org, but are still needed by some people
   or by other packages (such as <varname>imake</varname>).
  </para>

  <para>
   If the expression for a package requires derivation attributes that the
   generator cannot figure out automatically (say, <varname>patches</varname>
   or a <varname>postInstall</varname> hook), you should modify
   <filename>pkgs/servers/x11/xorg/overrides.nix</filename>.
  </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>
-->
<!--============================================================-->