doc/package-notes.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook"
   2          xmlns:xlink="http://www.w3.org/1999/xlink"
   3          xml:id="chap-introduction">
   4
   5 <title>Package Notes</title>
   6
   7 <para>This chapter contains information about how to use and maintain
   8 the Nix expressions for a number of specific packages, such as the
   9 Linux kernel or X.org.</para>
  10
  11
  12 <!--============================================================-->
  13
  14 <section xml:id="sec-linux-kernel">
  15
  16 <title>Linux kernel</title>
  17
  18 <para>The Nix expressions to build the Linux kernel are in <link
  19 xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/os-specific/linux/kernel"><filename>pkgs/os-specific/linux/kernel</filename></link>.</para>
  20
  21 <para>The function that builds the kernel has an argument
  22 <varname>kernelPatches</varname> which should be a list of
  23 <literal>{name, patch, extraConfig}</literal> attribute sets, where
  24 <varname>name</varname> is the name of the patch (which is included in
  25 the kernel’s <varname>meta.description</varname> attribute),
  26 <varname>patch</varname> is the patch itself (possibly compressed),
  27 and <varname>extraConfig</varname> (optional) is a string specifying
  28 extra options to be concatenated to the kernel configuration file
  29 (<filename>.config</filename>).</para>
  30
  31 <para>The kernel derivation exports an attribute
  32 <varname>features</varname> specifying whether optional functionality
  33 is or isn’t enabled.  This is used in NixOS to implement
  34 kernel-specific behaviour.  For instance, if the kernel has the
  35 <varname>iwlwifi</varname> feature (i.e. has built-in support for
  36 Intel wireless chipsets), then NixOS doesn’t have to build the
  37 external <varname>iwlwifi</varname> package:
  38
  39 <programlisting>
  40 modulesTree = [kernel]
  41   ++ pkgs.lib.optional (!kernel.features ? iwlwifi) kernelPackages.iwlwifi
  42   ++ ...;
  43 </programlisting>
  44
  45 </para>
  46
  47 <para>How to add a new (major) version of the Linux kernel to Nixpkgs:
  48
  49 <orderedlist>
  50
  51   <listitem>
  52     <para>Copy (<command>svn cp</command>) the old Nix expression
  53     (e.g. <filename>linux-2.6.21.nix</filename>) to the new one
  54     (e.g. <filename>linux-2.6.22.nix</filename>) and update it.</para>
  55   </listitem>
  56
  57   <listitem>
  58     <para>Add the new kernel to <filename>all-packages.nix</filename>
  59     (e.g., create an attribute
  60     <varname>kernel_2_6_22</varname>).</para>
  61   </listitem>
  62
  63   <listitem>
  64     <para>Now we’re going to update the kernel configuration.  First
  65     unpack the kernel.  Then for each supported platform
  66     (<literal>i686</literal>, <literal>x86_64</literal>,
  67     <literal>uml</literal>) do the following:
  68
  69       <orderedlist>
  70
  71         <listitem>
  72           <para>Make an <command>svn copy</command> from the old
  73           config (e.g. <filename>config-2.6.21-i686-smp</filename>) to
  74           the new one
  75           (e.g. <filename>config-2.6.22-i686-smp</filename>).</para>
  76         </listitem>
  77
  78         <listitem>
  79           <para>Copy the config file for this platform
  80           (e.g. <filename>config-2.6.22-i686-smp</filename>) to
  81           <filename>.config</filename> in the kernel source tree.
  82           </para>
  83         </listitem>
  84
  85         <listitem>
  86           <para>Run <literal>make oldconfig
  87           ARCH=<replaceable>{i386,x86_64,um}</replaceable></literal>
  88           and answer all questions.  (For the uml configuration, also
  89           add <literal>SHELL=bash</literal>.)  Make sure to keep the
  90           configuration consistent between platforms (i.e. don’t
  91           enable some feature on <literal>i686</literal> and disable
  92           it on <literal>x86_64</literal>).
  93           </para>
  94         </listitem>
  95
  96         <listitem>
  97           <para>If needed you can also run <literal>make
  98           menuconfig</literal>:
  99
 100             <screen>
 101 $ nix-env -i ncurses
 102 $ export NIX_CFLAGS_LINK=-lncurses
 103 $ make menuconfig ARCH=<replaceable>arch</replaceable></screen>
 104
 105           </para>
 106         </listitem>
 107
 108         <listitem>
 109           <para>Make sure that
 110           <literal>CONFIG_FB_TILEBLITTING</literal> is <emphasis>not
 111           set</emphasis> (otherwise <command>fbsplash</command> won't
 112           work).  This option has a tendency to be enabled as a
 113           side-effect of other options.  If it is, investigate why
 114           (there's probably another option that forces it to be on)
 115           and fix it.</para>
 116         </listitem>
 117
 118         <listitem>
 119           <para>Copy <filename>.config</filename> over the new config
 120           file (e.g. <filename>config-2.6.22-i686-smp</filename>).</para>
 121         </listitem>
 122
 123       </orderedlist>
 124
 125     </para>
 126
 127   </listitem>
 128
 129   <listitem>
 130     <para>Test building the kernel: <literal>nix-build -A
 131     kernel_2_6_22</literal>.  If it compiles, ship it!  For extra
 132     credit, try booting NixOS with it.</para>
 133   </listitem>
 134
 135   <listitem>
 136     <para>It may be that the new kernel requires updating the external
 137     kernel modules and kernel-dependent packages listed in the
 138     <varname>kernelPackagesFor</varname> function in
 139     <filename>all-packages.nix</filename> (such as the NVIDIA drivers,
 140     AUFS, splashutils, etc.).  If the updated packages aren’t
 141     backwards compatible with older kernels, you need to keep the
 142     older versions and use some conditionals.  For example, new
 143     kernels require splashutils 1.5 while old kernel require 1.3, so
 144     <varname>kernelPackagesFor</varname> says:
 145
 146       <programlisting>
 147 splashutils =
 148   if kernel.features ? fbSplash then splashutils_13 else
 149   if kernel.features ? fbConDecor then splashutils_15 else
 150   null;
 151
 152 splashutils_13 = ...;
 153 splashutils_15 = ...;</programlisting>
 154
 155     </para>
 156   </listitem>
 157
 158 </orderedlist>
 159
 160 </para>
 161
 162 </section>
 163
 164
 165 <!--============================================================-->
 166
 167 <section>
 168
 169 <title>X.org</title>
 170
 171 <para>The Nix expressions for the X.org packages reside in
 172 <filename>pkgs/servers/x11/xorg/default.nix</filename>.  This file is
 173 automatically generated from lists of tarballs in an X.org release.
 174 As such it should not be modified directly; rather, you should modify
 175 the lists, the generator script or the file
 176 <filename>pkgs/servers/x11/xorg/overrides.nix</filename>, in which you
 177 can override or add to the derivations produced by the
 178 generator.</para>
 179
 180 <para>The generator is invoked as follows:
 181
 182 <screen>
 183 $ cd pkgs/servers/x11/xorg
 184 $ cat tarballs-7.5.list extra.list old.list \
 185   | perl ./generate-expr-from-tarballs.pl
 186 </screen>
 187
 188 For each of the tarballs in the <filename>.list</filename> files, the
 189 script downloads it, unpacks it, and searches its
 190 <filename>configure.ac</filename> and <filename>*.pc.in</filename>
 191 files for dependencies.  This information is used to generate
 192 <filename>default.nix</filename>.  The generator caches downloaded
 193 tarballs between runs.  Pay close attention to the <literal>NOT FOUND:
 194 <replaceable>name</replaceable></literal> messages at the end of the
 195 run, since they may indicate missing dependencies.  (Some might be
 196 optional dependencies, however.)</para>
 197
 198 <para>A file like <filename>tarballs-7.5.list</filename> contains all
 199 tarballs in a X.org release.  It can be generated like this:
 200
 201 <screen>
 202 $ export i="mirror://xorg/X11R7.4/src/everything/"
 203 $ cat $(PRINT_PATH=1 nix-prefetch-url $i | tail -n 1) \
 204   | perl -e 'while (&lt;>) { if (/(href|HREF)="([^"]*.bz2)"/) { print "$ENV{'i'}$2\n"; }; }' \
 205   | sort > tarballs-7.4.list
 206 </screen>
 207
 208 <filename>extra.list</filename> contains libraries that aren’t part of
 209 X.org proper, but are closely related to it, such as
 210 <literal>libxcb</literal>.  <filename>old.list</filename> contains
 211 some packages that were removed from X.org, but are still needed by
 212 some people or by other packages (such as
 213 <varname>imake</varname>).</para>
 214
 215 <para>If the expression for a package requires derivation attributes
 216 that the generator cannot figure out automatically (say,
 217 <varname>patches</varname> or a <varname>postInstall</varname> hook),
 218 you should modify
 219 <filename>pkgs/servers/x11/xorg/overrides.nix</filename>.</para>
 220
 221 </section>
 222
 223
 224
 225 <!--============================================================-->
 226
 227 <section>
 228   <title>Gnome</title>
 229   <para>* Expression is auto-generated</para>
 230   <para>* How to update</para>
 231 </section>
 232
 233
 234 <!--============================================================-->
 235
 236 <section>
 237   <title>GCC</title>
 238   <para>…</para>
 239 </section>
 240
 241
 242 </chapter>