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 <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$ git clone https://github.com/NixOS/nixpkgs
13$ 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
19 package. For instance, a library package typically goes into
20 <filename>pkgs/development/libraries/<replaceable>pkgname</replaceable></filename>,
21 while a web browser goes into
22 <filename>pkgs/applications/networking/browsers/<replaceable>pkgname</replaceable></filename>.
23 See <xref linkend="sec-organisation" /> for some hints on the tree
24 organisation. Create a directory for your package, e.g.
25<screen>
26$ mkdir pkgs/development/libraries/libfoo</screen>
27 </para>
28 </listitem>
29 <listitem>
30 <para>
31 In the package directory, create a Nix expression — a piece of code that
32 describes how to build the package. In this case, it should be a
33 <emphasis>function</emphasis> that is called with the package dependencies
34 as arguments, and returns a build of the package in the Nix store. The
35 expression should usually be called <filename>default.nix</filename>.
36<screen>
37$ emacs pkgs/development/libraries/libfoo/default.nix
38$ git add pkgs/development/libraries/libfoo/default.nix</screen>
39 </para>
40 <para>
41 You can have a look at the existing Nix expressions under
42 <filename>pkgs/</filename> to see how it’s done. Here are some good
43 ones:
44 <itemizedlist>
45 <listitem>
46 <para>
47 GNU Hello:
48 <link
49 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/hello/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>.
50 Trivial package, which specifies some <varname>meta</varname>
51 attributes which is good practice.
52 </para>
53 </listitem>
54 <listitem>
55 <para>
56 GNU cpio:
57 <link
58 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/archivers/cpio/default.nix"><filename>pkgs/tools/archivers/cpio/default.nix</filename></link>.
59 Also a simple package. The generic builder in <varname>stdenv</varname>
60 does everything for you. It has no dependencies beyond
61 <varname>stdenv</varname>.
62 </para>
63 </listitem>
64 <listitem>
65 <para>
66 GNU Multiple Precision arithmetic library (GMP):
67 <link
68 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>.
69 Also done by the generic builder, but has a dependency on
70 <varname>m4</varname>.
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 Pan, a GTK-based newsreader:
76 <link
77 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>.
78 Has an optional dependency on <varname>gtkspell</varname>, which is
79 only built if <varname>spellCheck</varname> is <literal>true</literal>.
80 </para>
81 </listitem>
82 <listitem>
83 <para>
84 Apache HTTPD:
85 <link
86 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>.
87 A bunch of optional features, variable substitutions in the configure
88 flags, a post-install hook, and miscellaneous hackery.
89 </para>
90 </listitem>
91 <listitem>
92 <para>
93 Thunderbird:
94 <link
95 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>.
96 Lots of dependencies.
97 </para>
98 </listitem>
99 <listitem>
100 <para>
101 JDiskReport, a Java utility:
102 <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
105 <link
106 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/tools/misc/jdiskreport/builder.sh">builder</link>).
107 Nixpkgs doesn’t have a decent <varname>stdenv</varname> for Java yet
108 so this is pretty ad-hoc.
109 </para>
110 </listitem>
111 <listitem>
112 <para>
113 XML::Simple, a Perl module:
114 <link
115 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>
116 (search for the <varname>XMLSimple</varname> attribute). Most Perl
117 modules are so simple to build that they are defined directly in
118 <filename>perl-packages.nix</filename>; no need to make a separate file
119 for them.
120 </para>
121 </listitem>
122 <listitem>
123 <para>
124 Adobe Reader:
125 <link
126 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>.
127 Shows how binary-only packages can be supported. In particular the
128 <link
129 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/adobe-reader/builder.sh">builder</link>
130 uses <command>patchelf</command> to set the RUNPATH and ELF interpreter
131 of the executables so that the right libraries are found at runtime.
132 </para>
133 </listitem>
134 </itemizedlist>
135 </para>
136 <para>
137 Some notes:
138 <itemizedlist>
139 <listitem>
140 <para>
141 All <varname linkend="chap-meta">meta</varname> attributes are
142 optional, but it’s still a good idea to provide at least the
143 <varname>description</varname>, <varname>homepage</varname> and
144 <varname
145 linkend="sec-meta-license">license</varname>.
146 </para>
147 </listitem>
148 <listitem>
149 <para>
150 You can use <command>nix-prefetch-url</command> (or similar
151 nix-prefetch-git, etc) <replaceable>url</replaceable> to get the
152 SHA-256 hash of source distributions. There are similar commands as
153 <command>nix-prefetch-git</command> and
154 <command>nix-prefetch-hg</command> available in
155 <literal>nix-prefetch-scripts</literal> package.
156 </para>
157 </listitem>
158 <listitem>
159 <para>
160 A list of schemes for <literal>mirror://</literal> URLs can be found in
161 <link
162 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/fetchurl/mirrors.nix"><filename>pkgs/build-support/fetchurl/mirrors.nix</filename></link>.
163 </para>
164 </listitem>
165 </itemizedlist>
166 </para>
167 <para>
168 The exact syntax and semantics of the Nix expression language, including
169 the built-in function, are described in the Nix manual in the
170 <link
171 xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter
172 on writing Nix expressions</link>.
173 </para>
174 </listitem>
175 <listitem>
176 <para>
177 Add a call to the function defined in the previous step to
178 <link
179 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/all-packages.nix"><filename>pkgs/top-level/all-packages.nix</filename></link>
180 with some descriptive name for the variable, e.g.
181 <varname>libfoo</varname>.
182<screen>
183$ emacs pkgs/top-level/all-packages.nix</screen>
184 </para>
185 <para>
186 The attributes in that file are sorted by category (like “Development /
187 Libraries”) that more-or-less correspond to the directory structure of
188 Nixpkgs, and then by attribute name.
189 </para>
190 </listitem>
191 <listitem>
192 <para>
193 To test whether the package builds, run the following command from the
194 root of the nixpkgs source tree:
195<screen>
196$ nix-build -A libfoo</screen>
197 where <varname>libfoo</varname> should be the variable name defined in the
198 previous step. You may want to add the flag <option>-K</option> to keep
199 the temporary build directory in case something fails. If the build
200 succeeds, a symlink <filename>./result</filename> to the package in the
201 Nix store is created.
202 </para>
203 </listitem>
204 <listitem>
205 <para>
206 If you want to install the package into your profile (optional), do
207<screen>
208$ nix-env -f . -iA libfoo</screen>
209 </para>
210 </listitem>
211 <listitem>
212 <para>
213 Optionally commit the new package and open a pull request, or send a patch
214 to <literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.
215 </para>
216 </listitem>
217 </orderedlist>
218 </para>
219</chapter>