@@ -8,28 +8,28 @@
88
99 <para>
1010 When executing a Perl script, it is possible you get an error such as <literal>./myscript.pl: bad interpreter: /usr/bin/perl: no such file or directory</literal>. This happens when the script expects Perl to be installed at <filename>/usr/bin/perl</filename>, which is not the case when using Perl from nixpkgs. You can fix the script by changing the first line to:
11− <programlisting>
12− #!/usr/bin/env perl
13− </programlisting>
11+<programlisting>
12+#!/usr/bin/env perl
13+</programlisting>
1414 to take the Perl installation from the <literal>PATH</literal> environment variable, or invoke Perl directly with:
15− <screen>
16− <prompt>$ </prompt>perl ./myscript.pl
17− </screen>
15+<screen>
16+<prompt>$ </prompt>perl ./myscript.pl
17+</screen>
1818 </para>
1919
2020 <para>
2121 When the script is using a Perl library that is not installed globally, you might get an error such as <literal>Can't locate DB_File.pm in @INC (you may need to install the DB_File module)</literal>. In that case, you can use <command>nix-shell</command> to start an ad-hoc shell with that library installed, for instance:
22− <screen>
23− <prompt>$ </prompt>nix-shell -p perl perlPackages.DBFile --run ./myscript.pl
24− </screen>
22+<screen>
23+<prompt>$ </prompt>nix-shell -p perl perlPackages.DBFile --run ./myscript.pl
24+</screen>
2525 </para>
2626
2727 <para>
2828 If you are always using the script in places where <command>nix-shell</command> is available, you can embed the <command>nix-shell</command> invocation in the shebang like this:
29− <programlisting>
30− #!/usr/bin/env nix-shell
31− #! nix-shell -i perl -p perl perlPackages.DBFile
32− </programlisting>
29+<programlisting>
30+#!/usr/bin/env nix-shell
31+#! nix-shell -i perl -p perl perlPackages.DBFile
32+</programlisting>
3333 </para>
3434 </section>
3535
@@ -44,30 +44,30 @@
4444 <para>
4545 Perl packages from CPAN are defined in <link
4646 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, 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:
47− <programlisting>
48− ClassC3 = buildPerlPackage rec {
49− name = "Class-C3-0.21";
50− src = fetchurl {
51− url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
52− sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
53− };
54− };
55− </programlisting>
47+<programlisting>
48+ClassC3 = buildPerlPackage rec {
49+ name = "Class-C3-0.21";
50+ src = fetchurl {
51+ url = "mirror://cpan/authors/id/F/FL/FLORA/${name}.tar.gz";
52+ sha256 = "1bl8z095y4js66pwxnm7s853pi9czala4sqc743fdlnk27kq94gz";
53+ };
54+};
55+</programlisting>
5656 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 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 that needs <varname>ClassC3</varname>, you would typically write
57− <programlisting>
58− foo = import ../path/to/foo.nix {
59− inherit stdenv fetchurl ...;
60− inherit (perlPackages) ClassC3;
61− };
62− </programlisting>
57+<programlisting>
58+foo = import ../path/to/foo.nix {
59+ inherit stdenv fetchurl ...;
60+ inherit (perlPackages) ClassC3;
61+};
62+</programlisting>
6363 in <filename>all-packages.nix</filename>. You can test building a Perl package as follows:
64− <screen>
65− <prompt>$ </prompt>nix-build -A perlPackages.ClassC3
66− </screen>
64+<screen>
65+<prompt>$ </prompt>nix-build -A perlPackages.ClassC3
66+</screen>
6767 <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:
68− <screen>
69− <prompt>$ </prompt>nix-env -i perl-Class-C3
70− </screen>
68+<screen>
69+<prompt>$ </prompt>nix-env -i perl-Class-C3
70+</screen>
7171 (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.)
7272 </para>
7373
@@ -94,61 +94,61 @@
9494
9595 <para>
9696 <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>:
97− <programlisting>
98− { buildPerlPackage, fetchurl, db }:
99−
100− buildPerlPackage rec {
101− name = "BerkeleyDB-0.36";
102−
103− src = fetchurl {
104− url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
105− sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
106− };
107−
108− preConfigure = ''
109− echo "LIB = ${db.out}/lib" > config.in
110− echo "INCLUDE = ${db.dev}/include" >> config.in
111− '';
112− }
113− </programlisting>
97+<programlisting>
98+{ buildPerlPackage, fetchurl, db }:
99+
100+buildPerlPackage rec {
101+ name = "BerkeleyDB-0.36";
102+
103+ src = fetchurl {
104+ url = "mirror://cpan/authors/id/P/PM/PMQS/${name}.tar.gz";
105+ sha256 = "07xf50riarb60l1h6m2dqmql8q5dij619712fsgw7ach04d8g3z1";
106+ };
107+
108+ preConfigure = ''
109+ echo "LIB = ${db.out}/lib" > config.in
110+ echo "INCLUDE = ${db.dev}/include" >> config.in
111+ '';
112+}
113+</programlisting>
114114 </para>
115115
116116 <para>
117117 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:
118− <programlisting>
119− ClassC3Componentised = buildPerlPackage rec {
120− name = "Class-C3-Componentised-1.0004";
121− src = fetchurl {
122− url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
123− sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
124− };
125− propagatedBuildInputs = [
126− ClassC3 ClassInspector TestException MROCompat
127− ];
128− };
129− </programlisting>
118+<programlisting>
119+ClassC3Componentised = buildPerlPackage rec {
120+ name = "Class-C3-Componentised-1.0004";
121+ src = fetchurl {
122+ url = "mirror://cpan/authors/id/A/AS/ASH/${name}.tar.gz";
123+ sha256 = "0xql73jkcdbq4q9m0b0rnca6nrlvf5hyzy8is0crdk65bynvs8q1";
124+ };
125+ propagatedBuildInputs = [
126+ ClassC3 ClassInspector TestException MROCompat
127+ ];
128+};
129+</programlisting>
130130 </para>
131131
132132 <para>
133133 On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase:
134− <programlisting>
135− { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
136−
137− ImageExifTool = buildPerlPackage {
138− pname = "Image-ExifTool";
139− version = "11.50";
140−
141− src = fetchurl {
142− url = "https://www.sno.phy.queensu.ca/~phil/exiftool/Image-ExifTool-11.50.tar.gz";
143− sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3";
144− };
145−
146− buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang;
147− postInstall = stdenv.lib.optional stdenv.isDarwin ''
148− shortenPerlShebang $out/bin/exiftool
149− '';
150− };
151− </programlisting>
134+<programlisting>
135+{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
136+
137+ImageExifTool = buildPerlPackage {
138+ pname = "Image-ExifTool";
139+ version = "11.50";
140+
141+ src = fetchurl {
142+ url = "https://www.sno.phy.queensu.ca/~phil/exiftool/Image-ExifTool-11.50.tar.gz";
143+ sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3";
144+ };
145+
146+ buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang;
147+ postInstall = stdenv.lib.optional stdenv.isDarwin ''
148+ shortenPerlShebang $out/bin/exiftool
149+ '';
150+};
151+</programlisting>
152152 This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
153153 </para>
154154
@@ -159,27 +159,27 @@
159159 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:
160160 </para>
161161
162− <screen>
163− <prompt>$ </prompt>nix-env -i nix-generate-from-cpan
164− </screen>
162+<screen>
163+<prompt>$ </prompt>nix-env -i nix-generate-from-cpan
164+</screen>
165165
166166 <para>
167167 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:
168− <screen>
169− <prompt>$ </prompt>nix-generate-from-cpan XML::Simple
170− XMLSimple = buildPerlPackage rec {
171− name = "XML-Simple-2.22";
172− src = fetchurl {
173− url = "mirror://cpan/authors/id/G/GR/GRANTM/${name}.tar.gz";
174− sha256 = "b9450ef22ea9644ae5d6ada086dc4300fa105be050a2030ebd4efd28c198eb49";
175− };
176− propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
177− meta = {
178− description = "An API for simple XML files";
179− license = with stdenv.lib.licenses; [ artistic1 gpl1Plus ];
180− };
181− };
182− </screen>
168+<screen>
169+<prompt>$ </prompt>nix-generate-from-cpan XML::Simple
170+ XMLSimple = buildPerlPackage rec {
171+ name = "XML-Simple-2.22";
172+ src = fetchurl {
173+ url = "mirror://cpan/authors/id/G/GR/GRANTM/${name}.tar.gz";
174+ sha256 = "b9450ef22ea9644ae5d6ada086dc4300fa105be050a2030ebd4efd28c198eb49";
175+ };
176+ propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
177+ meta = {
178+ description = "An API for simple XML files";
179+ license = with stdenv.lib.licenses; [ artistic1 gpl1Plus ];
180+ };
181+ };
182+</screen>
183183 The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it.
184184 </para>
185185 </section>