2009-04-18 11:09:24 +00:00
<chapter xmlns= "http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
2009-11-18 13:54:20 +00:00
xml:id="chap-language-support">
2009-04-18 11:09:24 +00:00
<title > Support for specific programming languages</title>
<para > The <link linkend= "chap-stdenv" > standard build
environment</link> makes it easy to build typical Autotools-based
packages with very little code. Any other kind of package can be
accomodated by overriding the appropriate phases of
<literal > stdenv</literal> . However, there are specialised functions
in Nixpkgs to easily build packages for other programming languages,
such as Perl or Haskell. These are described in this chapter.</para>
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-language-perl" > <title > Perl</title>
2009-04-18 11:09:24 +00:00
<para > Nixpkgs provides a function <varname > buildPerlPackage</varname> ,
a generic package builder function for any Perl package that has a
standard <varname > Makefile.PL</varname> . It’ s implemented in <link
2012-09-04 14:14:01 +00:00
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename > pkgs/development/perl-modules/generic</filename> </link> .</para>
2009-04-18 11:09:24 +00:00
2009-04-20 12:23:01 +00:00
<para > Perl packages from CPAN are defined in <link
2013-06-13 13:39:08 +00:00
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename > pkgs/top-level/perl-packages.nix</filename> </link> ,
2009-04-20 12:23:01 +00:00
rather than <filename > pkgs/all-packages.nix</filename> . Most Perl
packages are so straight-forward to build that they are defined here
directly, rather than having a separate function for each package
called from <filename > perl-packages.nix</filename> . However, more
complicated packages should be put in a separate file, typically in
<filename > pkgs/development/perl-modules</filename> . Here is an
example of the former:
2009-04-18 11:09:24 +00:00
<programlisting >
2009-04-20 12:49:35 +00:00
ClassC3 = buildPerlPackage rec {
2009-04-18 11:09:24 +00:00
name = "Class-C3-0.21";
src = fetchurl {
url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
};
};
</programlisting>
Note the use of <literal > mirror://cpan/</literal> , and the
<literal > ${name}</literal> in the URL definition to ensure that the
name attribute is consistent with the source that we’ re actually
2009-04-20 12:23:01 +00:00
downloading. Perl packages are made available in
<filename > all-packages.nix</filename> through the variable
<varname > perlPackages</varname> . For instance, if you have a package
2009-04-20 12:49:35 +00:00
that needs <varname > ClassC3</varname> , you would typically write
2009-04-20 12:23:01 +00:00
<programlisting >
foo = import ../path/to/foo.nix {
inherit stdenv fetchurl ...;
2009-04-20 12:49:35 +00:00
inherit (perlPackages) ClassC3;
2009-04-20 12:23:01 +00:00
};
</programlisting>
in <filename > all-packages.nix</filename> . You can test building a
Perl package as follows:
2009-04-18 11:09:24 +00:00
<screen >
2009-04-20 12:49:35 +00:00
$ nix-build -A perlPackages.ClassC3
2009-04-18 11:09:24 +00:00
</screen>
<varname > buildPerlPackage</varname> adds <literal > perl-</literal> to
the start of the name attribute, so the package above is actually
called <literal > perl-Class-C3-0.21</literal> . So to install it, you
can say:
<screen >
$ nix-env -i perl-Class-C3
</screen>
(Of course you can also install using the attribute name:
2009-04-20 12:49:35 +00:00
<literal > nix-env -i -A perlPackages.ClassC3</literal> .)</para>
2009-04-18 11:09:24 +00:00
<para > So what does <varname > buildPerlPackage</varname> do? It does
the following:
<orderedlist >
<listitem > <para > In the configure phase, it calls <literal > perl
Makefile.PL</literal> to generate a Makefile. You can set the
variable <varname > makeMakerFlags</varname> to pass flags to
<filename > Makefile.PL</filename> </para> </listitem>
<listitem > <para > It adds the contents of the <envar > PERL5LIB</envar>
environment variable to <literal > #! .../bin/perl</literal> line of
Perl scripts as <literal > -I<replaceable > dir</replaceable> </literal>
flags. This ensures that a script can find its
dependencies.</para> </listitem>
<listitem > <para > In the fixup phase, it writes the propagated build
inputs (<varname > propagatedBuildInputs</varname> ) to the file
<filename > $out/nix-support/propagated-user-env-packages</filename> .
<command > nix-env</command> recursively installs all packages listed
in this file when you install a package that has it. This ensures
that a Perl package can find its dependencies.</para> </listitem>
</orderedlist>
</para>
<para > <varname > buildPerlPackage</varname> is built on top of
<varname > stdenv</varname> , so everything can be customised in the
usual way. For instance, the <literal > BerkeleyDB</literal> module has
a <varname > preConfigure</varname> hook to generate a configuration
file used by <filename > Makefile.PL</filename> :
<programlisting >
2014-11-08 20:59:57 +00:00
{ buildPerlPackage, fetchurl, db }:
2009-04-18 11:09:24 +00:00
buildPerlPackage rec {
name = "BerkeleyDB-0.36";
2014-01-13 12:15:59 +00:00
2009-04-18 11:09:24 +00:00
src = fetchurl {
url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
};
preConfigure = ''
2014-01-31 20:05:37 +00:00
echo "LIB = ${db}/lib" > config.in
echo "INCLUDE = ${db}/include" >> config.in
2009-04-18 11:09:24 +00:00
'';
}
2014-01-13 12:15:59 +00:00
</programlisting>
2009-04-18 11:09:24 +00:00
</para>
<para > Dependencies on other Perl packages can be specified in the
<varname > buildInputs</varname> and
<varname > propagatedBuildInputs</varname> attributes. If something is
exclusively a build-time dependency, use
<varname > buildInputs</varname> ; if it’ s (also) a runtime dependency,
use <varname > propagatedBuildInputs</varname> . For instance, this
builds a Perl module that has runtime dependencies on a bunch of other
modules:
<programlisting >
2009-04-20 12:49:35 +00:00
ClassC3Componentised = buildPerlPackage rec {
2009-04-18 11:09:24 +00:00
name = "Class-C3-Componentised-1.0004";
src = fetchurl {
url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
};
propagatedBuildInputs = [
2009-04-20 12:49:35 +00:00
ClassC3 ClassInspector TestException MROCompat
2009-04-18 11:09:24 +00:00
];
};
</programlisting>
</para>
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-generation-from-CPAN" > <title > Generation from CPAN</title>
2013-06-13 13:39:08 +00:00
<para > Nix expressions for Perl packages can be generated (almost)
automatically from CPAN. This is done by the program
<command > nix-generate-from-cpan</command> , which can be installed
as follows:</para>
<screen >
$ nix-env -i nix-generate-from-cpan
</screen>
<para > This program takes a Perl module name, looks it up on CPAN,
fetches and unpacks the corresponding package, and prints a Nix
expression on standard output. For example:
<screen >
$ nix-generate-from-cpan XML::Simple
XMLSimple = buildPerlPackage {
name = "XML-Simple-2.20";
src = fetchurl {
url = mirror://cpan/authors/id/G/GR/GRANTM/XML-Simple-2.20.tar.gz;
sha256 = "5cff13d0802792da1eb45895ce1be461903d98ec97c9c953bc8406af7294434a";
};
propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
meta = {
description = "Easily read/write XML (esp config files)";
license = "perl";
};
};
</screen>
The output can be pasted into
<filename > pkgs/top-level/perl-packages.nix</filename> or wherever else
you need it.</para>
</section>
2009-04-18 11:09:24 +00:00
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-python" > <title > Python</title>
2014-11-08 20:59:57 +00:00
<para >
Currently supported interpreters are <varname > python26</varname> , <varname > python27</varname> ,
<varname > python32</varname> , <varname > python33</varname> , <varname > python34</varname>
and <varname > pypy</varname> .
</para>
<para >
<varname > python</varname> is an alias of <varname > python27</varname> and <varname > python3</varname> is an alias of <varname > python34</varname> .
</para>
<para >
<varname > python26</varname> and <varname > python27</varname> do not include modules that require
external dependencies (to reduce dependency bloat). Following modules need to be added as
<varname > buildInput</varname> explicitly:
</para>
<itemizedlist >
<listitem > <para > <varname > python.modules.bsddb</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.curses</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.curses_panel</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.crypt</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.gdbm</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.sqlite3</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.tkinter</varname> </para> </listitem>
<listitem > <para > <varname > python.modules.readline</varname> </para> </listitem>
</itemizedlist>
<para > For convenience <varname > python27Full</varname> and <varname > python26Full</varname>
are provided with all modules included.</para>
2009-04-18 11:09:24 +00:00
2009-05-25 00:10:20 +00:00
<para >
Python packages that
2014-11-08 20:59:57 +00:00
use <link xlink:href= "http://pypi.python.org/pypi/setuptools/" > <literal > setuptools</literal> </link> or <literal > distutils</literal> ,
can be built using the <varname > buildPythonPackage</varname> function as documented below.
2009-05-25 00:10:20 +00:00
</para>
<para >
2014-11-08 20:59:57 +00:00
All packages depending on any Python interpreter get appended <varname > $out/${python.libPrefix}/site-packages</varname>
to <literal > $PYTHONPATH</literal> if such directory exists.
</para>
2009-05-25 00:10:20 +00:00
2014-11-08 20:59:57 +00:00
<variablelist >
<title >
Useful attributes on interpreters packages:
</title>
<varlistentry >
<term > <varname > libPrefix</varname> </term>
<listitem > <para >
Name of the folder in <literal > ${python}/lib/</literal> for corresponding interpreter.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > interpreter</varname> </term>
<listitem > <para >
Alias for <literal > ${python}/bin/${executable}.</literal>
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > buildEnv</varname> </term>
<listitem > <para >
Function to build python interpreter environments with extra packages bundled together.
2015-06-02 09:21:22 +00:00
See <xref linkend= "ssec-python-build-env" /> for usage and documentation.
2014-11-08 20:59:57 +00:00
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > sitePackages</varname> </term>
<listitem > <para >
Alias for <literal > lib/${libPrefix}/site-packages</literal> .
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > executable</varname> </term>
<listitem > <para >
Name of the interpreter executable, ie <literal > python3.4</literal> .
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
</variablelist>
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-build-python-package" > <title > <varname > buildPythonPackage</varname> function</title>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<para >
The function is implemented in <link xlink:href= "https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/python-modules/generic/default.nix" >
<filename > pkgs/development/python-modules/generic/default.nix</filename> </link> .
Example usage:
2015-05-25 03:22:20 +00:00
2015-02-15 17:22:14 +00:00
<programlisting language= "nix" >
twisted = buildPythonPackage {
name = "twisted-8.1.0";
src = pkgs.fetchurl {
url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
};
propagatedBuildInputs = [ self.ZopeInterface ];
meta = {
homepage = http://twistedmatrix.com/;
description = "Twisted, an event-driven networking engine written in Python";
license = stdenv.lib.licenses.mit;
};
};
</programlisting>
2014-11-08 20:59:57 +00:00
Most of Python packages that use <varname > buildPythonPackage</varname> are defined
in <link xlink:href= "https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix" > <filename > pkgs/top-level/python-packages.nix</filename> </link>
and generated for each python interpreter separately into attribute sets <varname > python26Packages</varname> ,
<varname > python27Packages</varname> , <varname > python32Packages</varname> , <varname > python33Packages</varname> ,
<varname > python34Packages</varname> and <varname > pypyPackages</varname> .
</para>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<para >
<function > buildPythonPackage</function> mainly does four things:
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<orderedlist >
<listitem > <para >
In the <varname > configurePhase</varname> , it patches
<literal > setup.py</literal> to always include setuptools before
distutils for monkeypatching machinery to take place.
</para> </listitem>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<listitem > <para >
2015-05-25 03:22:20 +00:00
In the <varname > buildPhase</varname> , it calls
2014-11-08 20:59:57 +00:00
<literal > ${python.interpreter} setup.py build ...</literal>
</para> </listitem>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<listitem > <para >
2015-05-25 03:22:20 +00:00
In the <varname > installPhase</varname> , it calls
2014-11-08 20:59:57 +00:00
<literal > ${python.interpreter} setup.py install ...</literal>
</para> </listitem>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<listitem > <para >
In the <varname > postFixup</varname> phase, <literal > wrapPythonPrograms</literal>
bash function is called to wrap all programs in <filename > $out/bin/*</filename>
directory to include <literal > $PYTHONPATH</literal> and <literal > $PATH</literal>
environment variables.
</para> </listitem>
</orderedlist>
</para>
2015-05-25 03:22:20 +00:00
<para > By default <varname > doCheck = true</varname> is set and tests are run with
2014-11-08 20:59:57 +00:00
<literal > ${python.interpreter} setup.py test</literal> command in <varname > checkPhase</varname> .</para>
2015-05-25 03:22:20 +00:00
2015-07-08 12:21:51 +00:00
<para > <varname > propagatedBuildInputs</varname> packages are propagated to the user environment.</para>
<para >
As in Perl, dependencies on other Python packages can be specified in the
<varname > buildInputs</varname> and
<varname > propagatedBuildInputs</varname> attributes. If something is
exclusively a build-time dependency, use
<varname > buildInputs</varname> ; if it’ s (also) a runtime dependency,
use <varname > propagatedBuildInputs</varname> .
</para>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<para >
By default <varname > meta.platforms</varname> is set to the same value
as the interpreter unless overriden otherwise.
</para>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<variablelist >
<title >
<varname > buildPythonPackage</varname> parameters
(all parameters from <varname > mkDerivation</varname> function are still supported)
</title>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > namePrefix</varname> </term>
<listitem > <para >
Prepended text to <varname > ${name}</varname> parameter.
Defaults to <literal > "python3.3-"</literal> for Python 3.3, etc. Set it to
<literal > ""</literal>
if you're packaging an application or a command line tool.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > disabled</varname> </term>
<listitem > <para >
If <varname > true</varname> , package is not build for
particular python interpreter version. Grep around
<filename > pkgs/top-level/python-packages.nix</filename>
for examples.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > setupPyInstallFlags</varname> </term>
<listitem > <para >
List of flags passed to <command > setup.py install</command> command.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > setupPyBuildFlags</varname> </term>
<listitem > <para >
List of flags passed to <command > setup.py build</command> command.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > pythonPath</varname> </term>
<listitem > <para >
List of packages to be added into <literal > $PYTHONPATH</literal> .
Packages in <varname > pythonPath</varname> are not propagated into user environment
(contrary to <varname > propagatedBuildInputs</varname> ).
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > preShellHook</varname> </term>
<listitem > <para >
Hook to execute commands before <varname > shellHook</varname> .
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > postShellHook</varname> </term>
<listitem > <para >
Hook to execute commands after <varname > shellHook</varname> .
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > distutilsExtraCfg</varname> </term>
<listitem > <para >
Extra lines passed to <varname > [easy_install]</varname> section of
<filename > distutils.cfg</filename> (acts as global setup.cfg
configuration).
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
<varlistentry >
<term > <varname > makeWrapperArgs</varname> </term>
<listitem > <para >
A list of strings. Arguments to be passed to
<varname > makeWrapper</varname> , which wraps generated binaries. By
default, the arguments to <varname > makeWrapper</varname> set
<varname > PATH</varname> and <varname > PYTHONPATH</varname> environment
variables before calling the binary. Additional arguments here can
allow a developer to set environment variables which will be
available when the binary is run. For example,
<varname > makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]</varname> .
</para> </listitem>
</varlistentry>
2014-11-08 20:59:57 +00:00
</variablelist>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
</section>
2009-05-25 00:10:20 +00:00
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-python-build-env" > <title > <function > python.buildEnv</function> function</title>
2014-11-08 20:59:57 +00:00
<para >
2014-11-15 19:23:32 +00:00
Create Python environments using low-level <function > pkgs.buildEnv</function> function. Example <filename > default.nix</filename> :
2015-05-25 03:22:20 +00:00
2015-02-15 17:22:14 +00:00
<programlisting language= "nix" >
<![CDATA[with import <nixpkgs> {};
python.buildEnv.override {
extraLibs = [ pkgs.pythonPackages.pyramid ];
ignoreCollisions = true;
}]]>
</programlisting>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
Running <command > nix-build</command> will create
<filename > /nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env</filename>
with wrapped binaries in <filename > bin/</filename> .
</para>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<variablelist >
<title >
<function > python.buildEnv</function> arguments
</title>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > extraLibs</varname> </term>
<listitem > <para >
List of packages installed inside the environment.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > postBuild</varname> </term>
<listitem > <para >
Shell command executed after the build of environment.
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > <varname > ignoreCollisions</varname> </term>
<listitem > <para >
Ignore file collisions inside the environment (default is <varname > false</varname> ).
</para> </listitem>
</varlistentry>
</variablelist>
</section>
2009-05-25 00:10:20 +00:00
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-python-tools" > <title > Tools</title>
2009-05-25 00:10:20 +00:00
2014-11-08 20:59:57 +00:00
<para > Packages inside nixpkgs are written by hand. However many tools
2014-11-15 19:23:32 +00:00
exist in community to help save time. No tool is preferred at the moment.
2014-11-08 20:59:57 +00:00
</para>
<itemizedlist >
<listitem > <para >
<link xlink:href= "https://github.com/proger/python2nix" > python2nix</link>
by Vladimir Kirillov
</para> </listitem>
<listitem > <para >
<link xlink:href= "https://github.com/garbas/pypi2nix" > pypi2nix</link>
by Rok Garbas
</para> </listitem>
<listitem > <para >
<link xlink:href= "https://github.com/offlinehacker/pypi2nix" > pypi2nix</link>
by Jaka Hudoklin
</para> </listitem>
</itemizedlist>
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-python-development" > <title > Development</title>
2014-11-08 20:59:57 +00:00
<para >
2014-12-19 15:30:45 +00:00
To develop Python packages <function > buildPythonPackage</function> has
2014-11-08 20:59:57 +00:00
additional logic inside <varname > shellPhase</varname> to run
<command > ${python.interpreter} setup.py develop</command> for the package.
</para>
2015-05-25 03:22:20 +00:00
2015-02-15 17:22:14 +00:00
<warning > <para > <varname > shellPhase</varname> is executed only if <filename > setup.py</filename>
exists.</para> </warning>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<para >
Given a <filename > default.nix</filename> :
2015-05-25 03:22:20 +00:00
2015-02-15 17:22:14 +00:00
<programlisting language= "nix" >
<![CDATA[with import <nixpkgs> {};
buildPythonPackage {
name = "myproject";
buildInputs = with pkgs.pythonPackages; [ pyramid ];
src = ./.;
}]]>
</programlisting>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
Running <command > nix-shell</command> with no arguments should give you
the environment in which the package would be build with
<command > nix-build</command> .
</para>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<para >
Shortcut to setup environments with C headers/libraries and python packages:
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<programlisting language= "bash" > $ nix-shell -p pythonPackages.pyramid zlib libjpeg git</programlisting>
</para>
2015-05-25 03:22:20 +00:00
2014-11-15 19:23:32 +00:00
<note > <para >
There is a boolean value <varname > lib.inNixShell</varname> set to
2014-11-08 20:59:57 +00:00
<varname > true</varname> if nix-shell is invoked.
2014-11-15 19:23:32 +00:00
</para> </note>
2014-11-08 20:59:57 +00:00
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-python-faq" > <title > FAQ</title>
2014-11-08 20:59:57 +00:00
<variablelist >
<varlistentry >
<term > How to solve circular dependencies?</term>
<listitem > <para >
If you have packages <varname > A</varname> and <varname > B</varname> that
depend on each other, when packaging <varname > B</varname> override package
<varname > A</varname> not to depend on <varname > B</varname> as input
(and also the other way around).
</para> </listitem>
</varlistentry>
<varlistentry >
<term > <varname > install_data / data_files</varname> problems resulting into <literal > error: could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc': Permission denied</literal> </term>
<listitem > <para >
<link xlink:href= "https://bitbucket.org/pypa/setuptools/issue/130/install_data-doesnt-respect-prefix" >
Known bug in setuptools <varname > install_data</varname> does not respect --prefix</link> . Example of
such package using the feature is <filename > pkgs/tools/X11/xpra/default.nix</filename> . As workaround
install it as an extra <varname > preInstall</varname> step:
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<programlisting > ${python.interpreter} setup.py install_data --install-dir=$out --root=$out
sed -i '/ = data_files/d' setup.py</programlisting>
</para> </listitem>
</varlistentry>
2015-05-25 03:22:20 +00:00
2014-11-08 20:59:57 +00:00
<varlistentry >
<term > Rationale of non-existent global site-packages</term>
<listitem > <para >
There is no need to have global site-packages in Nix. Each package has isolated
dependency tree and installing any python package will only populate <varname > $PATH</varname>
2015-06-02 09:21:22 +00:00
inside user environment. See <xref linkend= "ssec-python-build-env" /> to create self-contained
2014-11-08 20:59:57 +00:00
interpreter with a set of packages.
</para> </listitem>
</varlistentry>
</variablelist>
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "ssec-python-contrib" > <title > Contributing guidelines</title>
2014-11-08 20:59:57 +00:00
<para >
Following rules are desired to be respected:
2009-05-25 00:10:20 +00:00
</para>
2009-04-18 11:09:24 +00:00
2014-11-08 20:59:57 +00:00
<itemizedlist >
<listitem > <para >
Make sure package builds for all python interpreters. Use <varname > disabled</varname> argument to
<function > buildPythonPackage</function> to set unsupported interpreters.
</para> </listitem>
<listitem > <para >
If tests need to be disabled for a package, make sure you leave a comment about reasoning.
</para> </listitem>
<listitem > <para >
Packages in <link xlink:href= "https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/python-packages.nix" > <filename > pkgs/top-level/python-packages.nix</filename> </link>
are sorted quasi-alphabetically to avoid merge conflicts.
</para> </listitem>
</itemizedlist>
</section>
2009-04-18 11:09:24 +00:00
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-language-ruby" > <title > Ruby</title>
2015-03-31 17:04:42 +00:00
<para > There currently is support to bundle applications that are packaged as Ruby gems. The utility "bundix" allows you to write a <filename > Gemfile</filename> , let bundler create a <filename > Gemfile.lock</filename> , and then convert
this into a nix expression that contains all Gem dependencies automatically.</para>
<para > For example, to package sensu, we did:</para>
2015-05-25 03:22:20 +00:00
2015-02-15 17:22:14 +00:00
<screen >
2015-03-31 17:04:42 +00:00
< ![CDATA[$ cd pkgs/servers/monitoring
$ mkdir sensu
$ cat > Gemfile
source 'https://rubygems.org'
gem 'sensu'
$ bundler package --path /tmp/vendor/bundle
2015-05-10 22:28:56 +00:00
$ $(nix-build '<nixpkgs > ' -A bundix)/bin/bundix
2015-03-31 17:04:42 +00:00
$ cat > default.nix
{ lib, bundlerEnv, ruby }:
bundlerEnv {
name = "sensu-0.17.1";
inherit ruby;
gemfile = ./Gemfile;
lockfile = ./Gemfile.lock;
gemset = ./gemset.nix;
meta = with lib; {
description = "A monitoring framework that aims to be simple, malleable,
and scalable.";
homepage = http://sensuapp.org/;
license = with licenses; mit;
maintainers = with maintainers; [ theuni ];
platforms = platforms.unix;
};
}]]>
2015-02-15 17:22:14 +00:00
</screen>
2014-09-11 22:26:13 +00:00
2015-03-31 17:04:42 +00:00
<para > Please check in the <filename > Gemfile</filename> , <filename > Gemfile.lock</filename> and the <filename > gemset.nix</filename> so future updates can be run easily.
</para>
</section>
2014-09-11 22:26:13 +00:00
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-language-go" > <title > Go</title>
2015-01-31 15:51:20 +00:00
<para > The function <varname > buildGoPackage</varname> builds
standard Go packages.
</para>
<example xml:id= 'ex-buildGoPackage' > <title > buildGoPackage</title>
<programlisting >
net = buildGoPackage rec {
name = "go.net-${rev}";
2015-05-15 09:02:01 +00:00
goPackagePath = "golang.org/x/net"; <co xml:id= 'ex-buildGoPackage-1' />
2015-01-31 15:51:20 +00:00
subPackages = [ "ipv4" "ipv6" ]; <co xml:id= 'ex-buildGoPackage-2' />
2015-05-15 09:02:01 +00:00
rev = "e0403b4e005";
src = fetchFromGitHub {
2015-01-31 15:51:20 +00:00
inherit rev;
2015-05-15 09:02:01 +00:00
owner = "golang";
repo = "net";
sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
2015-01-31 15:51:20 +00:00
};
2015-05-15 09:02:01 +00:00
goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id= 'ex-buildGoPackage-3' />
2015-04-16 17:02:50 +00:00
propagatedBuildInputs = [ goPackages.text ]; <co xml:id= 'ex-buildGoPackage-4' />
2015-04-17 08:13:18 +00:00
buildFlags = "--tags release"; <co xml:id= 'ex-buildGoPackage-5' />
2015-05-18 10:55:02 +00:00
disabled = isGo13;<co xml:id= 'ex-buildGoPackage-6' />
2015-01-31 15:51:20 +00:00
};
</programlisting>
</example>
<para > <xref linkend= 'ex-buildGoPackage' /> is an example expression using buildGoPackage,
the following arguments are of special significance to the function:
<calloutlist >
<callout arearefs= 'ex-buildGoPackage-1' >
<para >
<varname > goPackagePath</varname> specifies the package's canonical Go import path.
</para>
</callout>
<callout arearefs= 'ex-buildGoPackage-2' >
<para >
<varname > subPackages</varname> limits the builder from building child packages that
have not been listed. If <varname > subPackages</varname> is not specified, all child
packages will be built.
</para>
<para >
In this example only <literal > code.google.com/p/go.net/ipv4</literal> and
<literal > code.google.com/p/go.net/ipv4</literal> will be built.
</para>
</callout>
2015-05-15 09:02:01 +00:00
<callout arearefs= 'ex-buildGoPackage-3' >
2015-04-16 17:02:50 +00:00
<para >
2015-05-15 09:02:01 +00:00
<varname > goPackageAliases</varname> is a list of alternative import paths
that are valid for this library.
Packages that depend on this library will automatically rename
import paths that match any of the aliases to <literal > goPackagePath</literal> .
2015-04-16 17:02:50 +00:00
</para>
<para >
In this example imports will be renamed from
2015-05-15 09:02:01 +00:00
<literal > code.google.com/p/go.net</literal> to
<literal > golang.org/x/net</literal> in every package that depend on the
<literal > go.net</literal> library.
2015-04-16 17:02:50 +00:00
</para>
</callout>
<callout arearefs= 'ex-buildGoPackage-4' >
2015-01-31 15:51:20 +00:00
<para >
<varname > propagatedBuildInputs</varname> is where the dependencies of a Go library are
listed. Only libraries should list <varname > propagatedBuildInputs</varname> . If a standalone
program is being build instead, use <varname > buildInputs</varname> . If a library's tests require
additional dependencies that are not propagated, they should be listed in <varname > buildInputs</varname> .
</para>
</callout>
2015-04-17 08:13:18 +00:00
<callout arearefs= 'ex-buildGoPackage-5' >
<para >
<varname > buildFlags</varname> is a list of flags passed to the go build command.
</para>
</callout>
2015-05-18 10:55:02 +00:00
<callout arearefs= 'ex-buildGoPackage-6' >
<para >
If <varname > disabled</varname> is <literal > true</literal> ,
nix will refuse to build this package.
</para>
<para >
In this example the package will not be built for go 1.3. The <literal > isGo13</literal>
is an utility function that returns <literal > true</literal> if go used to build the
package has version 1.3.x.
</para>
</callout>
2015-01-31 15:51:20 +00:00
</calloutlist>
</para>
<para >
Reusable Go libraries may be found in the <varname > goPackages</varname> set. You can test
build a Go package as follows:
<screen >
$ nix-build -A goPackages.net
</screen>
</para>
<para >
You may use Go packages installed into the active Nix profiles by adding
the following to your ~/.bashrc:
<screen >
for p in $NIX_PROFILES; do
GOPATH="$p/share/go:$GOPATH"
done
</screen>
</para>
2014-09-16 18:40:31 +00:00
<para > To extract dependency information from a Go package in automated way use <link xlink:href= "https://github.com/cstrahan/go2nix" > go2nix</link> .</para>
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-language-java" > <title > Java</title>
2014-01-13 12:15:59 +00:00
<para > Ant-based Java packages are typically built from source as follows:
<programlisting >
stdenv.mkDerivation {
name = "...";
src = fetchurl { ... };
buildInputs = [ jdk ant ];
buildPhase = "ant";
}
</programlisting>
Note that <varname > jdk</varname> is an alias for the OpenJDK.</para>
<para > JAR files that are intended to be used by other packages should
be installed in <filename > $out/share/java</filename> . The OpenJDK has
a stdenv setup hook that adds any JARs in the
<filename > share/java</filename> directories of the build inputs to the
<envar > CLASSPATH</envar> environment variable. For instance, if the
package <literal > libfoo</literal> installs a JAR named
<filename > foo.jar</filename> in its <filename > share/java</filename>
directory, and another package declares the attribute
<programlisting >
buildInputs = [ jdk libfoo ];
</programlisting>
then <envar > CLASSPATH</envar> will be set to
<filename > /nix/store/...-libfoo/share/java/foo.jar</filename> .</para>
<para > Private JARs
should be installed in a location like
<filename > $out/share/<replaceable > package-name</replaceable> </filename> .</para>
<para > If your Java package provides a program, you need to generate a
wrapper script to run it using the OpenJRE. You can use
<literal > makeWrapper</literal> for this:
<programlisting >
buildInputs = [ makeWrapper ];
installPhase =
''
mkdir -p $out/bin
makeWrapper ${jre}/bin/java $out/bin/foo \
--add-flags "-cp $out/share/java/foo.jar org.foo.Main"
'';
</programlisting>
Note the use of <literal > jre</literal> , which is the part of the
OpenJDK package that contains the Java Runtime Environment. By using
<literal > ${jre}/bin/java</literal> instead of
<literal > ${jdk}/bin/java</literal> , you prevent your package from
depending on the JDK at runtime.</para>
<para > It is possible to use a different Java compiler than
<command > javac</command> from the OpenJDK. For instance, to use the
Eclipse Java Compiler:
<programlisting >
buildInputs = [ jre ant ecj ];
</programlisting>
(Note that here you don’ t need the full JDK as an input, but just the
JRE.) The ECJ has a stdenv setup hook that sets some environment
variables to cause Ant to use ECJ, but this doesn’ t work with all Ant
files. Similarly, you can use the GNU Java Compiler:
<programlisting >
buildInputs = [ gcj ant ];
</programlisting>
2009-04-18 11:09:24 +00:00
2014-01-13 12:15:59 +00:00
Here, Ant will automatically use <command > gij</command> (the GNU Java
Runtime) instead of the OpenJRE.</para>
2009-04-18 11:09:24 +00:00
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-language-lua" > <title > Lua</title>
2014-09-23 09:53:53 +00:00
<para >
Lua packages are built by the <varname > buildLuaPackage</varname> function. This function is
implemented
in <link xlink:href= "https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules/generic/default.nix" >
<filename > pkgs/development/lua-modules/generic/default.nix</filename> </link>
and works similarly to <varname > buildPerlPackage</varname> . (See
2015-06-02 09:21:22 +00:00
<xref linkend= "sec-language-perl" /> for details.)
2014-09-23 09:53:53 +00:00
</para>
<para >
Lua packages are defined
in <link xlink:href= "https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/lua-packages.nix" > <filename > pkgs/top-level/lua-packages.nix</filename> </link> .
Most of them are simple. For example:
<programlisting >
fileSystem = buildLuaPackage {
name = "filesystem-1.6.2";
src = fetchurl {
url = "https://github.com/keplerproject/luafilesystem/archive/v1_6_2.tar.gz";
sha256 = "1n8qdwa20ypbrny99vhkmx8q04zd2jjycdb5196xdhgvqzk10abz";
2015-05-25 03:22:20 +00:00
};
2014-09-23 09:53:53 +00:00
meta = {
homepage = "https://github.com/keplerproject/luafilesystem";
hydraPlatforms = stdenv.lib.platforms.linux;
maintainers = with maintainers; [ flosse ];
};
};
</programlisting>
</para>
<para >
2015-05-25 03:22:20 +00:00
Though, more complicated package should be placed in a seperate file in
2014-09-23 09:53:53 +00:00
<link
xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/lua-modules"><filename > pkgs/development/lua-modules</filename> </link> .
</para>
<para >
Lua packages accept additional parameter <varname > disabled</varname> , which defines
the condition of disabling package from luaPackages. For example, if package has
<varname > disabled</varname> assigned to <literal > lua.luaversion != "5.1"</literal> ,
it will not be included in any luaPackages except lua51Packages, making it
only be built for lua 5.1.
</para>
</section>
2015-05-31 16:41:34 +00:00
<section xml:id= "sec-language-coq" > <title > Coq</title>
2014-09-28 21:02:36 +00:00
<para >
Coq libraries should be installed in
<literal > $(out)/lib/coq/${coq.coq-version}/user-contrib/</literal> .
Such directories are automatically added to the
<literal > $COQPATH</literal> environment variable by the hook defined
in the Coq derivation.
</para>
<para >
Some libraries require OCaml and sometimes also Camlp5. The exact
versions that were used to build Coq are saved in the
<literal > coq.ocaml</literal> and <literal > coq.camlp5</literal>
attributes.
</para>
<para >
Here is a simple package example. It is a pure Coq library, thus it
only depends on Coq. Its <literal > makefile</literal> has been
generated using <literal > coq_makefile</literal> so we only have to
set the <literal > $COQLIB</literal> variable at install time.
</para>
<programlisting >
{stdenv, fetchurl, coq}:
stdenv.mkDerivation {
src = fetchurl {
url = http://coq.inria.fr/pylons/contribs/files/Karatsuba/v8.4/Karatsuba.tar.gz;
sha256 = "0ymfpv4v49k4fm63nq6gcl1hbnnxrvjjp7yzc4973n49b853c5b1";
};
name = "coq-karatsuba";
buildInputs = [ coq ];
installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
}
</programlisting>
</section>
2014-09-23 09:53:53 +00:00
2012-11-08 14:18:09 +00:00
<!--
<section > <title > Haskell</title>
2009-04-18 11:09:24 +00:00
2012-11-08 14:18:09 +00:00
<para > TODO</para>
2009-04-18 11:09:24 +00:00
</section>
<section > <title > TeX / LaTeX</title>
<para > * Special support for building TeX documents</para>
</section>
2012-05-11 21:42:00 +00:00
-->
2009-04-18 11:09:24 +00:00
2009-05-25 00:10:20 +00:00
</chapter>