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