nixpkgs docs: format =)
This commit is contained in:
Graham Christensen
+185
-189
@@ -1,223 +1,219 @@
|
||||
<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:
|
||||
|
||||
<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.
|
||||
|
||||
</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>.
|
||||
|
||||
</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
|
||||
<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/default.nix"><filename>pkgs/applications/misc/hello/default.nix</filename></link>.
|
||||
Trivial package, which specifies some <varname>meta</varname>
|
||||
attributes which is good practice.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>GNU cpio: <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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
(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
|
||||
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
|
||||
(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
|
||||
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>
|
||||
|
||||
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>
|
||||
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
|
||||
<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
|
||||
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>
|
||||
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>
|
||||
<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>
|
||||
|
||||
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>Optionally commit the new package and open a pull request, or send a patch to
|
||||
<literal>https://groups.google.com/forum/#!forum/nix-devel</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
</orderedlist>
|
||||
|
||||
</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>https://groups.google.com/forum/#!forum/nix-devel</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</chapter>
|
||||
|
||||
Reference in New Issue
Block a user