pyrox.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
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$ git clone git://github.com/NixOS/nixpkgs.git
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$ 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$ git 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 Hello: <link
59 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>.
60 Trivial package, which specifies some <varname>meta</varname>
61 attributes which is good practice.</para>
62 </listitem>
63
64 <listitem>
65 <para>GNU cpio: <link
66 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>.
67 Also a simple package. The generic builder in
68 <varname>stdenv</varname> does everything for you. It has
69 no dependencies beyond <varname>stdenv</varname>.</para>
70 </listitem>
71
72 <listitem>
73 <para>GNU Multiple Precision arithmetic library (GMP): <link
74 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>.
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://github.com/NixOS/nixpkgs/blob/master/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://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>.
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>Thunderbird: <link
97 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>.
98 Lots of dependencies.</para>
99 </listitem>
100
101 <listitem>
102 <para>JDiskReport, a Java utility: <link
103 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/default.nix"><filename>pkgs/tools/misc/jdiskreport/default.nix</filename></link>
104 (and the <link
105 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>).
106 Nixpkgs doesn’t have a decent <varname>stdenv</varname> for
107 Java yet so this is pretty ad-hoc.</para>
108 </listitem>
109
110 <listitem>
111 <para>XML::Simple, a Perl module: <link
112 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>
113 (search for the <varname>XMLSimple</varname> attribute).
114 Most Perl modules are so simple to build that they are
115 defined directly in <filename>perl-packages.nix</filename>;
116 no need to make a separate file for them.</para>
117 </listitem>
118
119 <listitem>
120 <para>Adobe Reader: <link
121 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>.
122 Shows how binary-only packages can be supported. In
123 particular the <link
124 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh">builder</link>
125 uses <command>patchelf</command> to set the RUNPATH and ELF
126 interpreter of the executables so that the right libraries
127 are found at runtime.</para>
128 </listitem>
129
130 </itemizedlist>
131
132 </para>
133
134 <para>Some notes:
135
136 <itemizedlist>
137
138 <listitem>
139 <para>All <varname linkend="chap-meta">meta</varname>
140 attributes are optional, but it’s still a good idea to
141 provide at least the <varname>description</varname>,
142 <varname>homepage</varname> and <varname
143 linkend="sec-meta-license">license</varname>.</para>
144 </listitem>
145
146 <listitem>
147 <para>You can use <command>nix-prefetch-url</command> (or similar nix-prefetch-git, etc)
148 <replaceable>url</replaceable> to get the SHA-256 hash of
149 source distributions. There are similar commands as <command>nix-prefetch-git</command> and
150 <command>nix-prefetch-hg</command> available in <literal>nix-prefetch-scripts</literal> package.</para>
151 </listitem>
152
153 <listitem>
154 <para>A list of schemes for <literal>mirror://</literal>
155 URLs can be found in <link
156 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>
157 </listitem>
158
159 </itemizedlist>
160
161 </para>
162
163 <para>The exact syntax and semantics of the Nix expression
164 language, including the built-in function, are described in the
165 Nix manual in the <link
166 xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter
167 on writing Nix expressions</link>.</para>
168
169 </listitem>
170
171 <listitem>
172 <para>Add a call to the function defined in the previous step to
173 <link
174 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
175 with some descriptive name for the variable,
176 e.g. <varname>libfoo</varname>.
177
178 <screen>
179$ emacs pkgs/top-level/all-packages.nix</screen>
180
181 </para>
182
183 <para>The attributes in that file are sorted by category (like
184 “Development / Libraries”) that more-or-less correspond to the
185 directory structure of Nixpkgs, and then by attribute name.</para>
186 </listitem>
187
188 <listitem>
189 <para>To test whether the package builds, run the following command
190 from the root of the nixpkgs source tree:
191
192 <screen>
193$ nix-build -A libfoo</screen>
194
195 where <varname>libfoo</varname> should be the variable name
196 defined in the previous step. You may want to add the flag
197 <option>-K</option> to keep the temporary build directory in case
198 something fails. If the build succeeds, a symlink
199 <filename>./result</filename> to the package in the Nix store is
200 created.</para>
201 </listitem>
202
203 <listitem>
204 <para>If you want to install the package into your profile
205 (optional), do
206
207 <screen>
208$ nix-env -f . -iA libfoo</screen>
209
210 </para>
211 </listitem>
212
213 <listitem>
214 <para>Optionally commit the new package and open a pull request, or send a patch to
215 <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.</para>
216 </listitem>
217
218
219</orderedlist>
220
221</para>
222
223</chapter>