2 // vim: set syntax=asciidoc:
4 === Infrastructure for Perl/CPAN packages
6 [[perl-package-tutorial]]
8 ==== +perl-package+ tutorial
10 First, let's see how to write a +.mk+ file for a Perl/CPAN package,
13 ------------------------
14 01: ################################################################################
18 05: ################################################################################
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
27 14: $(eval $(perl-package))
28 ------------------------
30 On line 7, we declare the version of the package.
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.
36 On line 10, we declare our dependencies, so that they are built
37 before the build process of our package starts.
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
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
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 the +BR2_EXTERNAL+ directory).
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.
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.
63 [[perl-package-reference]]
65 ==== +perl-package+ reference
67 As a policy, packages that provide Perl/CPAN modules should all be
68 named +perl-<something>+ in Buildroot.
70 This infrastructure handles various Perl build systems :
71 +ExtUtils-MakeMaker+, +Module-Build+ and +Module-Build-Tiny+.
72 +Build.PL+ is always preferred when a package provides a +Makefile.PL+
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.
80 Just like the generic infrastructure, the Perl/CPAN infrastructure
81 works by defining a number of variables before calling the
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+.
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.
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.
100 * +PERL_FOO_CONF_ENV+/+HOST_PERL_FOO_CONF_ENV+, to specify additional
101 environment variables to pass to the +perl Makefile.PL+ or +perl Build.PL+.
104 * +PERL_FOO_CONF_OPTS+/+HOST_PERL_FOO_CONF_OPTS+, to specify additional
105 configure options to pass to the +perl Makefile.PL+ or +perl Build.PL+.
108 * +PERL_FOO_BUILD_OPTS+/+HOST_PERL_FOO_BUILD_OPTS+, to specify additional
109 options to pass to +make pure_all+ or +perl Build build+ in the build step.
112 * +PERL_FOO_INSTALL_TARGET_OPTS+, to specify additional options to
113 pass to +make pure_install+ or +perl Build install+ in the install step.
116 * +HOST_PERL_FOO_INSTALL_OPTS+, to specify additional options to
117 pass to +make pure_install+ or +perl Build install+ in the install step.