diff options
Diffstat (limited to 'doc/languages-frameworks/perl.xml')
| -rw-r--r-- | doc/languages-frameworks/perl.xml | 233 |
1 files changed, 115 insertions, 118 deletions
diff --git a/doc/languages-frameworks/perl.xml b/doc/languages-frameworks/perl.xml index 149fcb275a09..2fe64999e139 100644 --- a/doc/languages-frameworks/perl.xml +++ b/doc/languages-frameworks/perl.xml @@ -1,24 +1,27 @@ <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-language-perl"> - -<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 -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 + <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 +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: - + 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"; @@ -28,74 +31,72 @@ 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> $ 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> $ 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>.)</para> - -<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>: - + (Of course you can also install using the attribute name: <literal>nix-env -i + -A perlPackages.ClassC3</literal>.) + </para> + + <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> { buildPerlPackage, fetchurl, db }: @@ -113,18 +114,15 @@ buildPerlPackage rec { ''; } </programlisting> - -</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: - + </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> ClassC3Componentised = buildPerlPackage rec { name = "Class-C3-Componentised-1.0004"; @@ -137,24 +135,26 @@ ClassC3Componentised = buildPerlPackage rec { ]; }; </programlisting> + </para> -</para> - -<section xml:id="ssec-generation-from-CPAN"><title>Generation from CPAN</title> + <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:</para> + <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: - + <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 rec { @@ -170,26 +170,23 @@ $ nix-generate-from-cpan XML::Simple }; }; </screen> - -The output can be pasted into -<filename>pkgs/top-level/perl-packages.nix</filename> or wherever else -you need it.</para> - -</section> - -<section xml:id="ssec-perl-cross-compilation"><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.</para> - -</section> - + The output can be pasted into + <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you + need it. + </para> + </section> + + <section xml:id="ssec-perl-cross-compilation"> + <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. + </para> + </section> </section> - |