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