15be920354
This patch changes the documentation about simple packages. cpio was listed as simplest possible package, which is not true anymore, gnu hello is much simpler.
224 lines
8.8 KiB
XML
224 lines
8.8 KiB
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>
|