docs/manual/adding-packages-perl.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for Perl/CPAN packages
   5
   6 [[perl-package-tutorial]]
   7
   8 ==== +perl-package+ tutorial
   9
  10 First, let's see how to write a +.mk+ file for a Perl/CPAN package,
  11 with an example :
  12
  13 ------------------------
  14 01: ################################################################################
  15 02: #
  16 03: # perl-foo-bar
  17 04: #
  18 05: ################################################################################
  19 06:
  20 07: PERL_FOO_BAR_VERSION = 0.02
  21 08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
  22 09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
  23 10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
  24 11: PERL_FOO_BAR_LICENSE = Artistic or GPLv1+
  25 12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
  26 13:
  27 14: $(eval $(perl-package))
  28 ------------------------
  29
  30 On line 7, we declare the version of the package.
  31
  32 On line 8 and 9, we declare the name of the tarball and the location
  33 of the tarball on a CPAN server. Buildroot will automatically download
  34 the tarball from this location.
  35
  36 On line 10, we declare our dependencies, so that they are built
  37 before the build process of our package starts.
  38
  39 On line 11 and 12, we give licensing details about the package (its
  40 license on line 11, and the file containing the license text on line
  41 12).
  42
  43 Finally, on line 14, we invoke the +perl-package+ macro that
  44 generates all the Makefile rules that actually allow the package to be
  45 built.
  46
  47 Most of these data can be retrieved from https://metacpan.org/.
  48 So, this file and the Config.in can be generated by running
  49 the script +supports/scripts/scancpan Foo-Bar+ in the Buildroot directory
  50 (or in a br2-external tree).
  51 This script creates a Config.in file and foo-bar.mk file for the
  52 requested package, and also recursively for all dependencies specified by
  53 CPAN. You should still manually edit the result. In particular, the
  54 following things should be checked.
  55
  56 * If the perl module links with a shared library that is provided by
  57   another (non-perl) package, this dependency is not added automatically.
  58   It has to be added manually to +PERL_FOO_BAR_DEPENDENCIES+.
  59 * The +package/Config.in+ file has to be updated manually to include the
  60   generated Config.in files. As a hint, the +scancpan+ script prints out
  61   the required +source "..."+ statements, sorted alphabetically.
  62
  63 [[perl-package-reference]]
  64
  65 ==== +perl-package+ reference
  66
  67 As a policy, packages that provide Perl/CPAN modules should all be
  68 named +perl-<something>+ in Buildroot.
  69
  70 This infrastructure handles various Perl build systems :
  71 +ExtUtils-MakeMaker+ (EUMM), +Module-Build+ (MB) and +Module-Build-Tiny+.
  72 +Build.PL+ is preferred by default when a package provides a +Makefile.PL+
  73 and a +Build.PL+.
  74
  75 The main macro of the Perl/CPAN package infrastructure is
  76 +perl-package+. It is similar to the +generic-package+ macro. The ability to
  77 have target and host packages is also available, with the
  78 +host-perl-package+ macro.
  79
  80 Just like the generic infrastructure, the Perl/CPAN infrastructure
  81 works by defining a number of variables before calling the
  82 +perl-package+ macro.
  83
  84 First, all the package metadata information variables that exist in the
  85 generic infrastructure also exist in the Perl/CPAN infrastructure:
  86 +PERL_FOO_VERSION+, +PERL_FOO_SOURCE+,
  87 +PERL_FOO_PATCH+, +PERL_FOO_SITE+,
  88 +PERL_FOO_SUBDIR+, +PERL_FOO_DEPENDENCIES+,
  89 +PERL_FOO_INSTALL_TARGET+.
  90
  91 Note that setting +PERL_FOO_INSTALL_STAGING+ to +YES+ has no effect
  92 unless a +PERL_FOO_INSTALL_STAGING_CMDS+ variable is defined. The perl
  93 infrastructure doesn't define these commands since Perl modules generally
  94 don't need to be installed to the +staging+ directory.
  95
  96 A few additional variables, specific to the Perl/CPAN infrastructure,
  97 can also be defined. Many of them are only useful in very specific
  98 cases, typical packages will therefore only use a few of them.
  99
 100 * +PERL_FOO_PREFER_INSTALLER+/+HOST_PERL_FOO_PREFER_INSTALLER+,
 101   specifies the preferred installation method. Possible values are
 102   +EUMM+ (for +Makefile.PL+ based installation using
 103   +ExtUtils-MakeMaker+) and +MB+ (for +Build.PL+ based installation
 104   using +Module-Build+). This variable is only used when the package
 105   provides both installation methods.
 106
 107 * +PERL_FOO_CONF_ENV+/+HOST_PERL_FOO_CONF_ENV+, to specify additional
 108   environment variables to pass to the +perl Makefile.PL+ or +perl Build.PL+.
 109   By default, empty.
 110
 111 * +PERL_FOO_CONF_OPTS+/+HOST_PERL_FOO_CONF_OPTS+, to specify additional
 112   configure options to pass to the +perl Makefile.PL+ or +perl Build.PL+.
 113   By default, empty.
 114
 115 * +PERL_FOO_BUILD_OPTS+/+HOST_PERL_FOO_BUILD_OPTS+, to specify additional
 116   options to pass to +make pure_all+ or +perl Build build+ in the build step.
 117   By default, empty.
 118
 119 * +PERL_FOO_INSTALL_TARGET_OPTS+, to specify additional options to
 120   pass to +make pure_install+ or +perl Build install+ in the install step.
 121   By default, empty.
 122
 123 * +HOST_PERL_FOO_INSTALL_OPTS+, to specify additional options to
 124   pass to +make pure_install+ or +perl Build install+ in the install step.
 125   By default, empty.