doc/language-support.xml

   1 <chapter xmlns="http://docbook.org/ns/docbook"
   2          xmlns:xlink="http://www.w3.org/1999/xlink"
   3          xml:id="chap-language-support">
   4
   5 <title>Support for specific programming languages</title>
   6
   7 <para>The <link linkend="chap-stdenv">standard build
   8 environment</link> makes it easy to build typical Autotools-based
   9 packages with very little code.  Any other kind of package can be
  10 accomodated by overriding the appropriate phases of
  11 <literal>stdenv</literal>.  However, there are specialised functions
  12 in Nixpkgs to easily build packages for other programming languages,
  13 such as Perl or Haskell.  These are described in this chapter.</para>
  14
  15
  16 <section xml:id="ssec-language-perl"><title>Perl</title>
  17
  18 <para>Nixpkgs provides a function <varname>buildPerlPackage</varname>,
  19 a generic package builder function for any Perl package that has a
  20 standard <varname>Makefile.PL</varname>.  It’s implemented in <link
  21 xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.</para>
  22
  23 <para>Perl packages from CPAN are defined in <link
  24 xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/perl-packages.nix"><filename>pkgs/perl-packages.nix</filename></link>,
  25 rather than <filename>pkgs/all-packages.nix</filename>.  Most Perl
  26 packages are so straight-forward to build that they are defined here
  27 directly, rather than having a separate function for each package
  28 called from <filename>perl-packages.nix</filename>.  However, more
  29 complicated packages should be put in a separate file, typically in
  30 <filename>pkgs/development/perl-modules</filename>.  Here is an
  31 example of the former:
  32
  33 <programlisting>
  34 ClassC3 = buildPerlPackage rec {
  35   name = "Class-C3-0.21";
  36   src = fetchurl {
  37     url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
  38     sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
  39   };
  40 };
  41 </programlisting>
  42
  43 Note the use of <literal>mirror://cpan/</literal>, and the
  44 <literal>${name}</literal> in the URL definition to ensure that the
  45 name attribute is consistent with the source that we’re actually
  46 downloading.  Perl packages are made available in
  47 <filename>all-packages.nix</filename> through the variable
  48 <varname>perlPackages</varname>.  For instance, if you have a package
  49 that needs <varname>ClassC3</varname>, you would typically write
  50
  51 <programlisting>
  52 foo = import ../path/to/foo.nix {
  53   inherit stdenv fetchurl ...;
  54   inherit (perlPackages) ClassC3;
  55 };
  56 </programlisting>
  57
  58 in <filename>all-packages.nix</filename>.  You can test building a
  59 Perl package as follows:
  60
  61 <screen>
  62 $ nix-build -A perlPackages.ClassC3
  63 </screen>
  64
  65 <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to
  66 the start of the name attribute, so the package above is actually
  67 called <literal>perl-Class-C3-0.21</literal>.  So to install it, you
  68 can say:
  69
  70 <screen>
  71 $ nix-env -i perl-Class-C3
  72 </screen>
  73
  74 (Of course you can also install using the attribute name:
  75 <literal>nix-env -i -A perlPackages.ClassC3</literal>.)</para>
  76
  77 <para>So what does <varname>buildPerlPackage</varname> do?  It does
  78 the following:
  79
  80 <orderedlist>
  81
  82   <listitem><para>In the configure phase, it calls <literal>perl
  83   Makefile.PL</literal> to generate a Makefile.  You can set the
  84   variable <varname>makeMakerFlags</varname> to pass flags to
  85   <filename>Makefile.PL</filename></para></listitem>
  86
  87   <listitem><para>It adds the contents of the <envar>PERL5LIB</envar>
  88   environment variable to <literal>#! .../bin/perl</literal> line of
  89   Perl scripts as <literal>-I<replaceable>dir</replaceable></literal>
  90   flags.  This ensures that a script can find its
  91   dependencies.</para></listitem>
  92
  93   <listitem><para>In the fixup phase, it writes the propagated build
  94   inputs (<varname>propagatedBuildInputs</varname>) to the file
  95   <filename>$out/nix-support/propagated-user-env-packages</filename>.
  96   <command>nix-env</command> recursively installs all packages listed
  97   in this file when you install a package that has it.  This ensures
  98   that a Perl package can find its dependencies.</para></listitem>
  99
 100 </orderedlist>
 101
 102 </para>
 103
 104 <para><varname>buildPerlPackage</varname> is built on top of
 105 <varname>stdenv</varname>, so everything can be customised in the
 106 usual way.  For instance, the <literal>BerkeleyDB</literal> module has
 107 a <varname>preConfigure</varname> hook to generate a configuration
 108 file used by <filename>Makefile.PL</filename>:
 109
 110 <programlisting>
 111 {buildPerlPackage, fetchurl, db4}:
 112
 113 buildPerlPackage rec {
 114   name = "BerkeleyDB-0.36";
 115
 116   src = fetchurl {
 117     url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
 118     sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
 119   };
 120
 121   preConfigure = ''
 122     echo "LIB = ${db4}/lib" > config.in
 123     echo "INCLUDE = ${db4}/include" >> config.in
 124   '';
 125 }
 126 </programlisting>
 127
 128 </para>
 129
 130 <para>Dependencies on other Perl packages can be specified in the
 131 <varname>buildInputs</varname> and
 132 <varname>propagatedBuildInputs</varname> attributes.  If something is
 133 exclusively a build-time dependency, use
 134 <varname>buildInputs</varname>; if it’s (also) a runtime dependency,
 135 use <varname>propagatedBuildInputs</varname>.  For instance, this
 136 builds a Perl module that has runtime dependencies on a bunch of other
 137 modules:
 138
 139 <programlisting>
 140 ClassC3Componentised = buildPerlPackage rec {
 141   name = "Class-C3-Componentised-1.0004";
 142   src = fetchurl {
 143     url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
 144     sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
 145   };
 146   propagatedBuildInputs = [
 147     ClassC3 ClassInspector TestException MROCompat
 148   ];
 149 };
 150 </programlisting>
 151
 152 </para>
 153
 154 </section>
 155
 156
 157 <section><title>Python</title>
 158
 159 <para>
 160   Python packages that
 161   use <link xlink:href="http://pypi.python.org/pypi/setuptools/"><literal>setuptools</literal></link>,
 162   which many Python packages do nowadays, can be built very simply using
 163   the <varname>buildPythonPackage</varname> function.  This function is
 164   implemented
 165   in <link xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/development/python-modules/generic/default.nix"><filename>pkgs/development/python-modules/generic/default.nix</filename></link>
 166   and works similarly to <varname>buildPerlPackage</varname>. (See
 167   <xref linkend="ssec-language-perl"/> for details.)
 168 </para>
 169
 170 <para>
 171   Python packages that use <varname>buildPythonPackage</varname> are
 172   defined
 173   in <link xlink:href="https://svn.nixos.org/repos/nix/nixpkgs/trunk/pkgs/top-level/python-packages.nix"><filename>pkgs/top-level/python-packages.nix</filename></link>.
 174   Most of them are simple.  For example:
 175
 176   <programlisting>
 177 twisted = buildPythonPackage {
 178   name = "twisted-8.1.0";
 179
 180   src = fetchurl {
 181     url = http://tmrc.mit.edu/mirror/twisted/Twisted/8.1/Twisted-8.1.0.tar.bz2;
 182     sha256 = "0q25zbr4xzknaghha72mq57kh53qw1bf8csgp63pm9sfi72qhirl";
 183   };
 184
 185   propagatedBuildInputs = [ pkgs.ZopeInterface ];
 186
 187   meta = {
 188     homepage = http://twistedmatrix.com/;
 189     description = "Twisted, an event-driven networking engine written in Python";
 190     license = "MIT";
 191   };
 192 };
 193   </programlisting>
 194 </para>
 195
 196 </section>
 197
 198
 199 <section><title>Haskell</title>
 200
 201 <para>TODO</para>
 202
 203 </section>
 204
 205
 206 <section><title>Java</title>
 207
 208 <para>TODO; Java support needs lots of improvement</para>
 209
 210 </section>
 211
 212
 213 <section><title>TeX / LaTeX</title>
 214
 215 <para>* Special support for building TeX documents</para>
 216
 217 </section>
 218
 219
 220 </chapter>