diff options
Diffstat (limited to 'doc/languages-frameworks/perl.xml')
| -rw-r--r-- | doc/languages-frameworks/perl.xml | 98 |
1 files changed, 18 insertions, 80 deletions
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml index d5911cf67fd7..d9b6b2721c67 100644 --- a/doc/languages-frameworks/perl.xml +++ b/doc/languages-frameworks/perl.xml @@ -4,24 +4,13 @@ <title>Perl</title> <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 + 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 xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>. </para> <para> - Perl packages from CPAN are defined in - <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>, - 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: + Perl packages from CPAN are defined in <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>, 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: <programlisting> ClassC3 = buildPerlPackage rec { name = "Class-C3-0.21"; @@ -31,32 +20,22 @@ ClassC3 = buildPerlPackage rec { }; }; </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 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 + 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 <programlisting> foo = import ../path/to/foo.nix { inherit stdenv fetchurl ...; inherit (perlPackages) ClassC3; }; </programlisting> - in <filename>all-packages.nix</filename>. You can test building a Perl - package as follows: + in <filename>all-packages.nix</filename>. You can test building a Perl package as follows: <screen> <prompt>$ </prompt>nix-build -A perlPackages.ClassC3 </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: + <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> <prompt>$ </prompt>nix-env -i perl-Class-C3 </screen> - (Of course you can also install using the attribute name: <literal>nix-env -i - -A perlPackages.ClassC3</literal>.) + (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.) </para> <para> @@ -64,40 +43,24 @@ foo = import ../path/to/foo.nix { <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> + 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. (This can cause this shebang line - to become too long for Darwin to handle; see the note below.) + 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. (This can cause this shebang line to become too long for Darwin to handle; see the note below.) </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. + 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>: + <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> { buildPerlPackage, fetchurl, db }: @@ -118,12 +81,7 @@ buildPerlPackage rec { </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: + 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> ClassC3Componentised = buildPerlPackage rec { name = "Class-C3-Componentised-1.0004"; @@ -139,11 +97,7 @@ ClassC3Componentised = buildPerlPackage rec { </para> <para> - 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: + 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: <programlisting> { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }: @@ -162,20 +116,14 @@ ImageExifTool = buildPerlPackage { ''; }; </programlisting> - 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. + 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. </para> <section xml:id="ssec-generation-from-CPAN"> <title>Generation from CPAN</title> <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: + 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> @@ -183,9 +131,7 @@ ImageExifTool = buildPerlPackage { </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: + 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> <prompt>$ </prompt>nix-generate-from-cpan XML::Simple XMLSimple = buildPerlPackage rec { @@ -201,9 +147,7 @@ ImageExifTool = buildPerlPackage { }; }; </screen> - The output can be pasted into - <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you - need it. + The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it. </para> </section> @@ -211,13 +155,7 @@ ImageExifTool = buildPerlPackage { <title>Cross-compiling modules</title> <para> - Nixpkgs has experimental support for cross-compiling Perl modules. In many - cases, it will just work out of the box, even for modules with native - extensions. Sometimes, however, the Makefile.PL for a module may - (indirectly) import a native module. In that case, you will need to make a - stub for that module that will satisfy the Makefile.PL and install it into - <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the - <varname>postInstall</varname> for <varname>DBI</varname> for an example. + Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example. </para> </section> </section> |