pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="sec-language-perl">
4 <title>Perl</title>
5
6 <para>
7 Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic
8 package builder function for any Perl package that has a standard
9 <varname>Makefile.PL</varname>. It’s implemented in
10 <link
11xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
12 </para>
13
14 <para>
15 Perl packages from CPAN are defined in
16 <link
17xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>,
18 rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages
19 are so straight-forward to build that they are defined here directly, rather
20 than having a separate function for each package called from
21 <filename>perl-packages.nix</filename>. However, more complicated packages
22 should be put in a separate file, typically in
23 <filename>pkgs/development/perl-modules</filename>. Here is an example of the
24 former:
25<programlisting>
26ClassC3 = buildPerlPackage rec {
27 name = "Class-C3-0.21";
28 src = fetchurl {
29 url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
30 sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
31 };
32};
33</programlisting>
34 Note the use of <literal>mirror://cpan/</literal>, and the
35 <literal>${name}</literal> in the URL definition to ensure that the name
36 attribute is consistent with the source that we’re actually downloading.
37 Perl packages are made available in <filename>all-packages.nix</filename>
38 through the variable <varname>perlPackages</varname>. For instance, if you
39 have a package that needs <varname>ClassC3</varname>, you would typically
40 write
41<programlisting>
42foo = import ../path/to/foo.nix {
43 inherit stdenv fetchurl ...;
44 inherit (perlPackages) ClassC3;
45};
46</programlisting>
47 in <filename>all-packages.nix</filename>. You can test building a Perl
48 package as follows:
49<screen>
50$ nix-build -A perlPackages.ClassC3
51</screen>
52 <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the
53 start of the name attribute, so the package above is actually called
54 <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
55<screen>
56$ nix-env -i perl-Class-C3
57</screen>
58 (Of course you can also install using the attribute name: <literal>nix-env -i
59 -A perlPackages.ClassC3</literal>.)
60 </para>
61
62 <para>
63 So what does <varname>buildPerlPackage</varname> do? It does the following:
64 <orderedlist>
65 <listitem>
66 <para>
67 In the configure phase, it calls <literal>perl Makefile.PL</literal> to
68 generate a Makefile. You can set the variable
69 <varname>makeMakerFlags</varname> to pass flags to
70 <filename>Makefile.PL</filename>
71 </para>
72 </listitem>
73 <listitem>
74 <para>
75 It adds the contents of the <envar>PERL5LIB</envar> environment variable
76 to <literal>#! .../bin/perl</literal> line of Perl scripts as
77 <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures
78 that a script can find its dependencies.
79 </para>
80 </listitem>
81 <listitem>
82 <para>
83 In the fixup phase, it writes the propagated build inputs
84 (<varname>propagatedBuildInputs</varname>) to the file
85 <filename>$out/nix-support/propagated-user-env-packages</filename>.
86 <command>nix-env</command> recursively installs all packages listed in
87 this file when you install a package that has it. This ensures that a Perl
88 package can find its dependencies.
89 </para>
90 </listitem>
91 </orderedlist>
92 </para>
93
94 <para>
95 <varname>buildPerlPackage</varname> is built on top of
96 <varname>stdenv</varname>, so everything can be customised in the usual way.
97 For instance, the <literal>BerkeleyDB</literal> module has a
98 <varname>preConfigure</varname> hook to generate a configuration file used by
99 <filename>Makefile.PL</filename>:
100<programlisting>
101{ buildPerlPackage, fetchurl, db }:
102
103buildPerlPackage rec {
104 name = "BerkeleyDB-0.36";
105
106 src = fetchurl {
107 url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
108 sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
109 };
110
111 preConfigure = ''
112 echo "LIB = ${db.out}/lib" > config.in
113 echo "INCLUDE = ${db.dev}/include" >> config.in
114 '';
115}
116</programlisting>
117 </para>
118
119 <para>
120 Dependencies on other Perl packages can be specified in the
121 <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname>
122 attributes. If something is exclusively a build-time dependency, use
123 <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use
124 <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl
125 module that has runtime dependencies on a bunch of other modules:
126<programlisting>
127ClassC3Componentised = buildPerlPackage rec {
128 name = "Class-C3-Componentised-1.0004";
129 src = fetchurl {
130 url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
131 sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
132 };
133 propagatedBuildInputs = [
134 ClassC3 ClassInspector TestException MROCompat
135 ];
136};
137</programlisting>
138 </para>
139
140 <section xml:id="ssec-generation-from-CPAN">
141 <title>Generation from CPAN</title>
142
143 <para>
144 Nix expressions for Perl packages can be generated (almost) automatically
145 from CPAN. This is done by the program
146 <command>nix-generate-from-cpan</command>, which can be installed as
147 follows:
148 </para>
149
150<screen>
151$ nix-env -i nix-generate-from-cpan
152</screen>
153
154 <para>
155 This program takes a Perl module name, looks it up on CPAN, fetches and
156 unpacks the corresponding package, and prints a Nix expression on standard
157 output. For example:
158<screen>
159$ nix-generate-from-cpan XML::Simple
160 XMLSimple = buildPerlPackage rec {
161 name = "XML-Simple-2.22";
162 src = fetchurl {
163 url = "mirror://cpan/authors/id/G/GR/GRANTM/${name}.tar.gz";
164 sha256 = "b9450ef22ea9644ae5d6ada086dc4300fa105be050a2030ebd4efd28c198eb49";
165 };
166 propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
167 meta = {
168 description = "An API for simple XML files";
169 license = with stdenv.lib.licenses; [ artistic1 gpl1Plus ];
170 };
171 };
172</screen>
173 The output can be pasted into
174 <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you
175 need it.
176 </para>
177 </section>
178
179 <section xml:id="ssec-perl-cross-compilation">
180 <title>Cross-compiling modules</title>
181
182 <para>
183 Nixpkgs has experimental support for cross-compiling Perl modules. In many
184 cases, it will just work out of the box, even for modules with native
185 extensions. Sometimes, however, the Makefile.PL for a module may
186 (indirectly) import a native module. In that case, you will need to make a
187 stub for that module that will satisfy the Makefile.PL and install it into
188 <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the
189 <varname>postInstall</varname> for <varname>DBI</varname> for an example.
190 </para>
191 </section>
192</section>