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 10First, let's see how to write a +.mk+ file for a Perl/CPAN package, 11with an example : 12 13------------------------ 1401: ################################################################################ 1502: # 1603: # perl-foo-bar 1704: # 1805: ################################################################################ 1906: 2007: PERL_FOO_BAR_VERSION = 0.02 2108: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz 2209: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER 2310: PERL_FOO_BAR_DEPENDENCIES = perl-strictures 2411: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+ 2512: PERL_FOO_BAR_LICENSE_FILES = LICENSE 2613: PERL_FOO_BAR_DISTNAME = Foo-Bar 2714: 2815: $(eval $(perl-package)) 29------------------------ 30 31On line 7, we declare the version of the package. 32 33On line 8 and 9, we declare the name of the tarball and the location 34of the tarball on a CPAN server. Buildroot will automatically download 35the tarball from this location. 36 37On line 10, we declare our dependencies, so that they are built 38before the build process of our package starts. 39 40On line 11 and 12, we give licensing details about the package (its 41license on line 11, and the file containing the license text on line 4212). 43 44On line 13, the name of the distribution as needed by the script 45+utils/scancpan+ (in order to regenerate/upgrade these package files). 46 47Finally, on line 15, we invoke the +perl-package+ macro that 48generates all the Makefile rules that actually allow the package to be 49built. 50 51Most of these data can be retrieved from https://metacpan.org/. 52So, this file and the Config.in can be generated by running 53the script +utils/scancpan Foo-Bar+ in the Buildroot directory 54(or in a br2-external tree). 55This script creates a Config.in file and foo-bar.mk file for the 56requested package, and also recursively for all dependencies specified by 57CPAN. You should still manually edit the result. In particular, the 58following 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 71As a policy, packages that provide Perl/CPAN modules should all be 72named +perl-<something>+ in Buildroot. 73 74This 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+ 77and a +Build.PL+. 78 79The main macro of the Perl/CPAN package infrastructure is 80+perl-package+. It is similar to the +generic-package+ macro. The ability to 81have target and host packages is also available, with the 82+host-perl-package+ macro. 83 84Just like the generic infrastructure, the Perl/CPAN infrastructure 85works by defining a number of variables before calling the 86+perl-package+ macro. 87 88First, all the package metadata information variables that exist in the 89generic 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 95Note that setting +PERL_FOO_INSTALL_STAGING+ to +YES+ has no effect 96unless a +PERL_FOO_INSTALL_STAGING_CMDS+ variable is defined. The perl 97infrastructure doesn't define these commands since Perl modules generally 98don't need to be installed to the +staging+ directory. 99 100A few additional variables, specific to the Perl/CPAN infrastructure, 101can also be defined. Many of them are only useful in very specific 102cases, 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. 130