doc/quick-start.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook"
   2          xmlns:xlink="http://www.w3.org/1999/xlink"
   3          xml:id="chap-quick-start">
   4
   5 <title>Quick Start to Adding a Package</title>
   6
   7 <para>To add a package to Nixpkgs:
   8
   9 <orderedlist>
  10
  11   <listitem>
  12     <para>Checkout the Nixpkgs source tree:
  13
  14 <screen>
  15 $ svn checkout https://svn.nixos.org/repos/nix/nixpkgs/trunk nixpkgs
  16 $ cd nixpkgs</screen>
  17
  18     </para>
  19   </listitem>
  20
  21   <listitem>
  22     <para>Find a good place in the Nixpkgs tree to add the Nix
  23     expression for your package.  For instance, a library package
  24     typically goes into
  25     <filename>pkgs/development/libraries/<replaceable>pkgname</replaceable></filename>,
  26     while a web browser goes into
  27     <filename>pkgs/applications/networking/browsers/<replaceable>pkgname</replaceable></filename>.
  28     See <xref linkend="sec-organisation" /> for some hints on the tree
  29     organisation.  Create a directory for your package, e.g.
  30
  31 <screen>
  32 $ svn mkdir pkgs/development/libraries/libfoo</screen>
  33
  34     </para>
  35   </listitem>
  36
  37   <listitem>
  38     <para>In the package directory, create a Nix expression — a piece
  39     of code that describes how to build the package.  In this case, it
  40     should be a <emphasis>function</emphasis> that is called with the
  41     package dependencies as arguments, and returns a build of the
  42     package in the Nix store.  The expression should usually be called
  43     <filename>default.nix</filename>.
  44
  45 <screen>
  46 $ emacs pkgs/development/libraries/libfoo/default.nix
  47 $ svn add pkgs/development/libraries/libfoo/default.nix</screen>
  48
  49     </para>
  50
  51     <para>You can have a look at the existing Nix expressions under
  52     <filename>pkgs/</filename> to see how it’s done.  Here are some
  53     good ones:
  54
  55       <itemizedlist>
  56
  57         <listitem>
  58           <para>GNU cpio: <link
  59           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>.
  60           The simplest possible package.  The generic builder in
  61           <varname>stdenv</varname> does everything for you.  It has
  62           no dependencies beyond <varname>stdenv</varname>.</para>
  63         </listitem>
  64
  65         <listitem>
  66           <para>GNU Hello: <link
  67           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/misc/hello/ex-2/default.nix"><filename>pkgs/applications/misc/hello/ex-2/default.nix</filename></link>.
  68           Also trivial, but it specifies some <varname>meta</varname>
  69           attributes which is good practice.</para>
  70         </listitem>
  71
  72         <listitem>
  73           <para>GNU Multiple Precision arithmetic library (GMP): <link
  74           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/libraries/gmp/default.nix"><filename>pkgs/development/libraries/gmp/default.nix</filename></link>.
  75           Also done by the generic builder, but has a dependency on
  76           <varname>m4</varname>.</para>
  77         </listitem>
  78
  79         <listitem>
  80           <para>Pan, a GTK-based newsreader: <link
  81           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/networking/newsreaders/pan/default.nix"><filename>pkgs/applications/networking/newsreaders/pan/default.nix</filename></link>.
  82           Has an optional dependency on <varname>gtkspell</varname>,
  83           which is only built if <varname>spellCheck</varname> is
  84           <literal>true</literal>.</para>
  85         </listitem>
  86
  87         <listitem>
  88           <para>Apache HTTPD: <link
  89           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/servers/http/apache-httpd/default.nix"><filename>pkgs/servers/http/apache-httpd/default.nix</filename></link>.
  90           A bunch of optional features, variable substitutions in the
  91           configure flags, a post-install hook, and miscellaneous
  92           hackery.</para>
  93         </listitem>
  94
  95         <listitem>
  96           <para>BitTorrent (wxPython-based): <link
  97           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/networking/p2p/bittorrent/default.nix"><filename>pkgs/tools/networking/p2p/bittorrent/default.nix</filename></link>.
  98           Uses an external <link
  99           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/networking/p2p/bittorrent/builder.sh">build
 100           script</link>, which can be useful if you have lots of code
 101           that you don’t want cluttering up the Nix expression.  But
 102           external builders are mostly obsolete.
 103           </para>
 104         </listitem>
 105
 106         <listitem>
 107           <para>Thunderbird: <link
 108           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/networking/mailreaders/thunderbird-2.x/default.nix"><filename>pkgs/applications/networking/mailreaders/thunderbird-2.x/default.nix</filename></link>.
 109           Lots of dependencies.</para>
 110         </listitem>
 111
 112         <listitem>
 113           <para>JDiskReport, a Java utility: <link
 114           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link>
 115           (and the <link
 116           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>).
 117           Nixpkgs doesn’t have a decent <varname>stdenv</varname> for
 118           Java yet so this is pretty ad-hoc.</para>
 119         </listitem>
 120
 121         <listitem>
 122           <para>XML::Simple, a Perl module: <link
 123           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>
 124           (search for the <varname>XMLSimple</varname> attribute).
 125           Most Perl modules are so simple to build that they are
 126           defined directly in <filename>perl-packages.nix</filename>;
 127           no need to make a separate file for them.</para>
 128         </listitem>
 129
 130         <listitem>
 131           <para>Adobe Reader: <link
 132           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/misc/adobe-reader/default.nix"><filename>pkgs/applications/misc/adobe-reader/default.nix</filename></link>.
 133           Shows how binary-only packages can be supported.  In
 134           particular the <link
 135           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/applications/misc/adobe-reader/builder.sh">builder</link>
 136           uses <command>patchelf</command> to set the RUNPATH and ELF
 137           interpreter of the executables so that the right libraries
 138           are found at runtime.</para>
 139         </listitem>
 140
 141       </itemizedlist>
 142
 143     </para>
 144
 145     <para>Some notes:
 146
 147       <itemizedlist>
 148
 149         <listitem>
 150           <para>All <varname linkend="chap-meta">meta</varname>
 151           attributes are optional, but it’s still a good idea to
 152           provide at least the <varname>description</varname>,
 153           <varname>homepage</varname> and <varname
 154           linkend="sec-meta-license">license</varname>.</para>
 155         </listitem>
 156
 157         <listitem>
 158           <para>You can use <command>nix-prefetch-url</command>
 159           <replaceable>url</replaceable> to get the SHA-256 hash of
 160           source distributions.</para>
 161         </listitem>
 162
 163         <listitem>
 164           <para>A list of schemes for <literal>mirror://</literal>
 165           URLs can be found in <link
 166           xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.</para>
 167         </listitem>
 168
 169       </itemizedlist>
 170
 171     </para>
 172
 173     <para>The exact syntax and semantics of the Nix expression
 174     language, including the built-in function, are described in the
 175     Nix manual in the <link
 176     xlink:href="http://nixos.org/releases/nix/unstable/manual/#chap-writing-nix-expressions">chapter
 177     on writing Nix expressions</link>.</para>
 178
 179   </listitem>
 180
 181   <listitem>
 182     <para>Add a call to the function defined in the previous step to
 183     <link
 184     xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
 185     with some descriptive name for the variable,
 186     e.g. <varname>libfoo</varname>.
 187
 188     <screen>
 189 $ emacs pkgs/top-level/all-packages.nix</screen>
 190
 191     </para>
 192
 193     <para>The attributes in that file are sorted by category (like
 194     “Development / Libraries”) that more-or-less correspond to the
 195     directory structure of Nixpkgs, and then by attribute name.</para>
 196   </listitem>
 197
 198   <listitem>
 199     <para>Test whether the package builds:
 200
 201     <screen>
 202 $ nix-build -A libfoo</screen>
 203
 204     where <varname>libfoo</varname> should be the variable name
 205     defined in the previous step.  You may want to add the flag
 206     <option>-K</option> to keep the temporary build directory in case
 207     something fails.  If the build succeeds, a symlink
 208     <filename>./result</filename> to the package in the Nix store is
 209     created.</para>
 210   </listitem>
 211
 212   <listitem>
 213     <para>If you want to install the package into your profile
 214     (optional), do
 215
 216     <screen>
 217 $ nix-env -f . -iA libfoo</screen>
 218
 219     </para>
 220   </listitem>
 221
 222   <listitem>
 223     <para>Optionally commit the new package (<command>svn
 224     ci</command>) or send a patch to
 225     <literal>nix-dev@cs.uu.nl</literal>.</para>
 226   </listitem>
 227
 228   <listitem>
 229     <para>If you want the TU Delft build farm to build binaries of the
 230     package and make them available in the <link
 231     xlink:href="http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable/"><literal>nixpkgs</literal>
 232     channel</link>, add it to <link
 233     xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/release.nix"><filename>pkgs/top-level/release.nix</filename></link>.</para>
 234   </listitem>
 235
 236 </orderedlist>
 237
 238 </para>
 239
 240 </chapter>