tjh.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-quick-start">
4 <title>Quick Start to Adding a Package</title>
5 <para>
6 To add a package to Nixpkgs:
7 <orderedlist>
8 <listitem>
9 <para>
10 Checkout the Nixpkgs source tree:
11<screen>
12<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs
13<prompt>$ </prompt>cd nixpkgs</screen>
14 </para>
15 </listitem>
16 <listitem>
17 <para>
18 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.
19<screen>
20<prompt>$ </prompt>mkdir pkgs/development/libraries/libfoo</screen>
21 </para>
22 </listitem>
23 <listitem>
24 <para>
25 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>.
26<screen>
27<prompt>$ </prompt>emacs pkgs/development/libraries/libfoo/default.nix
28<prompt>$ </prompt>git add pkgs/development/libraries/libfoo/default.nix</screen>
29 </para>
30 <para>
31 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:
32 <itemizedlist>
33 <listitem>
34 <para>
35 GNU Hello: <link
36 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>. Trivial package, which specifies some <varname>meta</varname> attributes which is good practice.
37 </para>
38 </listitem>
39 <listitem>
40 <para>
41 GNU cpio: <link
42 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>.
43 </para>
44 </listitem>
45 <listitem>
46 <para>
47 GNU Multiple Precision arithmetic library (GMP): <link
48 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>.
49 </para>
50 </listitem>
51 <listitem>
52 <para>
53 Pan, a GTK-based newsreader: <link
54 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>.
55 </para>
56 </listitem>
57 <listitem>
58 <para>
59 Apache HTTPD: <link
60 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.
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Thunderbird: <link
66 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.
67 </para>
68 </listitem>
69 <listitem>
70 <para>
71 JDiskReport, a Java utility: <link
72 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link>. Nixpkgs doesn’t have a decent <varname>stdenv</varname> for Java yet so this is pretty ad-hoc.
73 </para>
74 </listitem>
75 <listitem>
76 <para>
77 XML::Simple, a Perl module: <link
78 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.
79 </para>
80 </listitem>
81 <listitem>
82 <para>
83 Adobe Reader: <link
84 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
85 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.
86 </para>
87 </listitem>
88 </itemizedlist>
89 </para>
90 <para>
91 Some notes:
92 <itemizedlist>
93 <listitem>
94 <para>
95 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
96 linkend="sec-meta-license">license</varname>.
97 </para>
98 </listitem>
99 <listitem>
100 <para>
101 You can use <command>nix-prefetch-url</command> <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.
102 </para>
103 </listitem>
104 <listitem>
105 <para>
106 A list of schemes for <literal>mirror://</literal> URLs can be found in <link
107 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.
108 </para>
109 </listitem>
110 </itemizedlist>
111 </para>
112 <para>
113 The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the <link
114 xlink:href="https://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter on writing Nix expressions</link>.
115 </para>
116 </listitem>
117 <listitem>
118 <para>
119 Add a call to the function defined in the previous step to <link
120 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>.
121<screen>
122<prompt>$ </prompt>emacs pkgs/top-level/all-packages.nix</screen>
123 </para>
124 <para>
125 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.
126 </para>
127 </listitem>
128 <listitem>
129 <para>
130 To test whether the package builds, run the following command from the root of the nixpkgs source tree:
131<screen>
132<prompt>$ </prompt>nix-build -A libfoo</screen>
133 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.
134 </para>
135 </listitem>
136 <listitem>
137 <para>
138 If you want to install the package into your profile (optional), do
139<screen>
140<prompt>$ </prompt>nix-env -f . -iA libfoo</screen>
141 </para>
142 </listitem>
143 <listitem>
144 <para>
145 Optionally commit the new package and open a pull request <link
146 xlink:href="https://github.com/NixOS/nixpkgs/pulls">to nixpkgs</link>, or use <link
147 xlink:href="https://discourse.nixos.org/t/about-the-patches-category/477"> the Patches category</link> on Discourse for sending a patch without a GitHub account.
148 </para>
149 </listitem>
150 </orderedlist>
151 </para>
152</chapter>