nixpkgs/doc/quick-start.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="chap-quick-start">

<title>Quick Start to Adding a Package</title>

<para>To add a package to Nixpkgs:

<orderedlist>

  <listitem>
    <para>Checkout the Nixpkgs source tree:

<screen>
$ git clone git://github.com/NixOS/nixpkgs.git 
$ cd nixpkgs</screen>

    </para>
  </listitem>

  <listitem>
    <para>Find a good place in the Nixpkgs tree to add the Nix
    expression for your package.  For instance, a library package
    typically goes into
    <filename>pkgs/development/libraries/<replaceable>pkgname</replaceable></filename>,
    while a web browser goes into
    <filename>pkgs/applications/networking/browsers/<replaceable>pkgname</replaceable></filename>.
    See <xref linkend="sec-organisation" /> for some hints on the tree
    organisation.  Create a directory for your package, e.g.

<screen>
$ mkdir pkgs/development/libraries/libfoo</screen>
  
    </para>
  </listitem>

  <listitem>
    <para>In the package directory, create a Nix expression — a piece
    of code that describes how to build the package.  In this case, it
    should be a <emphasis>function</emphasis> that is called with the
    package dependencies as arguments, and returns a build of the
    package in the Nix store.  The expression should usually be called
    <filename>default.nix</filename>.

<screen>
$ emacs pkgs/development/libraries/libfoo/default.nix
$ git add pkgs/development/libraries/libfoo/default.nix</screen>

    </para>

    <para>You can have a look at the existing Nix expressions under
    <filename>pkgs/</filename> to see how it’s done.  Here are some
    good ones:

      <itemizedlist>

        <listitem>
          <para>GNU Hello: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/ex-2/default.nix"><filename>pkgs/applications/misc/hello/ex-2/default.nix</filename></link>.
          Trivial package, which specifies some <varname>meta</varname>
          attributes which is good practice.</para>
        </listitem>

        <listitem>
          <para>GNU cpio: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>.
          Also a simple package. The generic builder in
          <varname>stdenv</varname> does everything for you. It has
          no dependencies beyond <varname>stdenv</varname>.</para>
        </listitem>

        <listitem>
          <para>GNU Multiple Precision arithmetic library (GMP): <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/gmp/5.1.x.nix"><filename>pkgs/development/libraries/gmp/5.1.x.nix</filename></link>.
          Also done by the generic builder, but has a dependency on
          <varname>m4</varname>.</para>
        </listitem>

        <listitem>
          <para>Pan, a GTK-based newsreader: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/newsreaders/pan/default.nix"><filename>pkgs/applications/networking/newsreaders/pan/default.nix</filename></link>.
          Has an optional dependency on <varname>gtkspell</varname>,
          which is only built if <varname>spellCheck</varname> is
          <literal>true</literal>.</para>
        </listitem>

        <listitem>
          <para>Apache HTTPD: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/http/apache-httpd/2.4.nix"><filename>pkgs/servers/http/apache-httpd/2.4.nix</filename></link>.
          A bunch of optional features, variable substitutions in the
          configure flags, a post-install hook, and miscellaneous
          hackery.</para>
        </listitem>

        <listitem>
          <para>Thunderbird: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/networking/mailreaders/thunderbird/default.nix"><filename>pkgs/applications/networking/mailreaders/thunderbird/default.nix</filename></link>.
          Lots of dependencies.</para>
        </listitem>

        <listitem>
          <para>JDiskReport, a Java utility: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link>
          (and the <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>).
          Nixpkgs doesn’t have a decent <varname>stdenv</varname> for
          Java yet so this is pretty ad-hoc.</para>
        </listitem>

        <listitem>
          <para>XML::Simple, a Perl module: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>
          (search for the <varname>XMLSimple</varname> attribute).
          Most Perl modules are so simple to build that they are
          defined directly in <filename>perl-packages.nix</filename>;
          no need to make a separate file for them.</para>
        </listitem>

        <listitem>
          <para>Adobe Reader: <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/default.nix"><filename>pkgs/applications/misc/adobe-reader/default.nix</filename></link>.
          Shows how binary-only packages can be supported.  In
          particular the <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh">builder</link>
          uses <command>patchelf</command> to set the RUNPATH and ELF
          interpreter of the executables so that the right libraries
          are found at runtime.</para>
        </listitem>

      </itemizedlist>

    </para>

    <para>Some notes:

      <itemizedlist>

        <listitem>
          <para>All <varname linkend="chap-meta">meta</varname>
          attributes are optional, but it’s still a good idea to
          provide at least the <varname>description</varname>,
          <varname>homepage</varname> and <varname
          linkend="sec-meta-license">license</varname>.</para>
        </listitem>

        <listitem>
          <para>You can use <command>nix-prefetch-url</command> (or similar nix-prefetch-git, etc)
          <replaceable>url</replaceable> to get the SHA-256 hash of
          source distributions. There are similar commands as <command>nix-prefetch-git</command> and
          <command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package.</para>
        </listitem>

        <listitem>
          <para>A list of schemes for <literal>mirror://</literal>
          URLs can be found in <link
          xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.</para>
        </listitem>

      </itemizedlist>

    </para>

    <para>The exact syntax and semantics of the Nix expression
    language, including the built-in function, are described in the
    Nix manual in the <link
    xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter
    on writing Nix expressions</link>.</para>
    
  </listitem>

  <listitem>
    <para>Add a call to the function defined in the previous step to
    <link
    xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
    with some descriptive name for the variable,
    e.g. <varname>libfoo</varname>.

    <screen>
$ emacs pkgs/top-level/all-packages.nix</screen>
      
    </para>

    <para>The attributes in that file are sorted by category (like
    “Development / Libraries”) that more-or-less correspond to the
    directory structure of Nixpkgs, and then by attribute name.</para>
  </listitem>

  <listitem>
    <para>To test whether the package builds, run the following command
    from the root of the nixpkgs source tree:

    <screen>
$ nix-build -A libfoo</screen>

    where <varname>libfoo</varname> should be the variable name
    defined in the previous step.  You may want to add the flag
    <option>-K</option> to keep the temporary build directory in case
    something fails.  If the build succeeds, a symlink
    <filename>./result</filename> to the package in the Nix store is
    created.</para>
  </listitem>

  <listitem>
    <para>If you want to install the package into your profile
    (optional), do

    <screen>
$ nix-env -f . -iA libfoo</screen>

    </para>
  </listitem>

  <listitem>
    <para>Optionally commit the new package and open a pull request, or send a patch to
    <literal>nix-dev@cs.uu.nl</literal>.</para>
  </listitem>


</orderedlist>

</para>

</chapter>