# Quick Start to Adding a Package

To add a package to Nixpkgs:

1. Checkout the Nixpkgs source tree:

       $ svn checkout https://svn.nixos.org/repos/nix/nixpkgs/trunk nixpkgs
       $ cd nixpkgs

2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/`pkgname``, while a web browser goes into `pkgs/applications/networking/browsers/`pkgname``. See sec-organisation for some hints on the tree organisation. Create a directory for your package, e.g.

       $ svn mkdir pkgs/development/libraries/libfoo

3. 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 function 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 `default.nix`.

       $ emacs pkgs/development/libraries/libfoo/default.nix
       $ svn add pkgs/development/libraries/libfoo/default.nix

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

   - GNU cpio: `pkgs/tools/archivers/cpio/default.nix`. The simplest possible package. The generic builder in `stdenv` does everything for you. It has no dependencies beyond `stdenv`.

   - GNU Hello: `pkgs/applications/misc/hello/ex-2/default.nix`. Also trivial, but it specifies some `meta` attributes which is good practice.

   - GNU Multiple Precision arithmetic library (GMP): `pkgs/development/libraries/gmp/default.nix`. Also done by the generic builder, but has a dependency on `m4`.

   - Pan, a GTK-based newsreader: `pkgs/applications/networking/newsreaders/pan/default.nix`. Has an optional dependency on `gtkspell`, which is only built if `spellCheck` is `true`.

   - Apache HTTPD: `pkgs/servers/http/apache-httpd/default.nix`. A bunch of optional features, variable substitutions in the configure flags, a post-install hook, and miscellaneous hackery.

   - BitTorrent (wxPython-based): `pkgs/tools/networking/p2p/bittorrent/default.nix`. Uses an external build script, which can be useful if you have lots of code that you don’t want cluttering up the Nix expression. But external builders are mostly obsolete.

   - Thunderbird: `pkgs/applications/networking/mailreaders/thunderbird/3.x.nix`. Lots of dependencies.

   - JDiskReport, a Java utility: `pkgs/tools/misc/jdiskreport/default.nix` (and the builder). Nixpkgs doesn’t have a decent `stdenv` for Java yet so this is pretty ad-hoc.

   - XML::Simple, a Perl module: `pkgs/top-level/perl-packages.nix` (search for the `XMLSimple` attribute). Most Perl modules are so simple to build that they are defined directly in `perl-packages.nix`; no need to make a separate file for them.

   - Adobe Reader: `pkgs/applications/misc/adobe-reader/default.nix`. Shows how binary-only packages can be supported. In particular the builder uses `patchelf` to set the RUNPATH and ELF interpreter of the executables so that the right libraries are found at runtime.

   Some notes:

   - All `meta` attributes are optional, but it’s still a good idea to provide at least the `description`, `homepage` and `license`.

   - You can use `nix-prefetch-url` `url` to get the SHA-256 hash of source distributions.

   - A list of schemes for `mirror://` URLs can be found in `pkgs/build-support/fetchurl/mirrors.nix`.

   The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the chapter on writing Nix expressions.

4. Add a call to the function defined in the previous step to `pkgs/top-level/all-packages.nix` with some descriptive name for the variable, e.g. `libfoo`.

       $ emacs pkgs/top-level/all-packages.nix

   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.

5. Test whether the package builds:

       $ nix-build -A libfoo

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

6. If you want to install the package into your profile (optional), do

       $ nix-env -f . -iA libfoo

7. Optionally commit the new package (`svn ci`) or send a patch to `nix-dev@cs.uu.nl`.

8. If you want the TU Delft build farm to build binaries of the package and make them available in the `nixpkgs` channel, add it to `pkgs/top-level/release.nix`.