5286dec396
We want to use SPDX short identifier for license string as much as possible. So refer to SPDX license list and use SPDX short identifier for license strings in documentation. Also remove License abbreviations that we have. Signed-off-by: Rahul Bedarkar <rahulbedarkar89@gmail.com> [Thomas: take into account suggestions from Arnout.] Acked-by: Arnout Vandecappelle (Essensium/Mind) <arnout@mind.be> Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
126 lines
4.9 KiB
Plaintext
126 lines
4.9 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc:
|
|
|
|
=== Infrastructure for Perl/CPAN packages
|
|
|
|
[[perl-package-tutorial]]
|
|
|
|
==== +perl-package+ tutorial
|
|
|
|
First, let's see how to write a +.mk+ file for a Perl/CPAN package,
|
|
with an example :
|
|
|
|
------------------------
|
|
01: ################################################################################
|
|
02: #
|
|
03: # perl-foo-bar
|
|
04: #
|
|
05: ################################################################################
|
|
06:
|
|
07: PERL_FOO_BAR_VERSION = 0.02
|
|
08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
|
|
09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
|
|
10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
|
|
11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
|
|
12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
|
|
13:
|
|
14: $(eval $(perl-package))
|
|
------------------------
|
|
|
|
On line 7, we declare the version of the package.
|
|
|
|
On line 8 and 9, we declare the name of the tarball and the location
|
|
of the tarball on a CPAN server. Buildroot will automatically download
|
|
the tarball from this location.
|
|
|
|
On line 10, we declare our dependencies, so that they are built
|
|
before the build process of our package starts.
|
|
|
|
On line 11 and 12, we give licensing details about the package (its
|
|
license on line 11, and the file containing the license text on line
|
|
12).
|
|
|
|
Finally, on line 14, we invoke the +perl-package+ macro that
|
|
generates all the Makefile rules that actually allow the package to be
|
|
built.
|
|
|
|
Most of these data can be retrieved from https://metacpan.org/.
|
|
So, this file and the Config.in can be generated by running
|
|
the script +supports/scripts/scancpan Foo-Bar+ in the Buildroot directory
|
|
(or in a br2-external tree).
|
|
This script creates a Config.in file and foo-bar.mk file for the
|
|
requested package, and also recursively for all dependencies specified by
|
|
CPAN. You should still manually edit the result. In particular, the
|
|
following things should be checked.
|
|
|
|
* If the perl module links with a shared library that is provided by
|
|
another (non-perl) package, this dependency is not added automatically.
|
|
It has to be added manually to +PERL_FOO_BAR_DEPENDENCIES+.
|
|
* The +package/Config.in+ file has to be updated manually to include the
|
|
generated Config.in files. As a hint, the +scancpan+ script prints out
|
|
the required +source "..."+ statements, sorted alphabetically.
|
|
|
|
[[perl-package-reference]]
|
|
|
|
==== +perl-package+ reference
|
|
|
|
As a policy, packages that provide Perl/CPAN modules should all be
|
|
named +perl-<something>+ in Buildroot.
|
|
|
|
This infrastructure handles various Perl build systems :
|
|
+ExtUtils-MakeMaker+ (EUMM), +Module-Build+ (MB) and +Module-Build-Tiny+.
|
|
+Build.PL+ is preferred by default when a package provides a +Makefile.PL+
|
|
and a +Build.PL+.
|
|
|
|
The main macro of the Perl/CPAN package infrastructure is
|
|
+perl-package+. It is similar to the +generic-package+ macro. The ability to
|
|
have target and host packages is also available, with the
|
|
+host-perl-package+ macro.
|
|
|
|
Just like the generic infrastructure, the Perl/CPAN infrastructure
|
|
works by defining a number of variables before calling the
|
|
+perl-package+ macro.
|
|
|
|
First, all the package metadata information variables that exist in the
|
|
generic infrastructure also exist in the Perl/CPAN infrastructure:
|
|
+PERL_FOO_VERSION+, +PERL_FOO_SOURCE+,
|
|
+PERL_FOO_PATCH+, +PERL_FOO_SITE+,
|
|
+PERL_FOO_SUBDIR+, +PERL_FOO_DEPENDENCIES+,
|
|
+PERL_FOO_INSTALL_TARGET+.
|
|
|
|
Note that setting +PERL_FOO_INSTALL_STAGING+ to +YES+ has no effect
|
|
unless a +PERL_FOO_INSTALL_STAGING_CMDS+ variable is defined. The perl
|
|
infrastructure doesn't define these commands since Perl modules generally
|
|
don't need to be installed to the +staging+ directory.
|
|
|
|
A few additional variables, specific to the Perl/CPAN infrastructure,
|
|
can also be defined. Many of them are only useful in very specific
|
|
cases, typical packages will therefore only use a few of them.
|
|
|
|
* +PERL_FOO_PREFER_INSTALLER+/+HOST_PERL_FOO_PREFER_INSTALLER+,
|
|
specifies the preferred installation method. Possible values are
|
|
+EUMM+ (for +Makefile.PL+ based installation using
|
|
+ExtUtils-MakeMaker+) and +MB+ (for +Build.PL+ based installation
|
|
using +Module-Build+). This variable is only used when the package
|
|
provides both installation methods.
|
|
|
|
* +PERL_FOO_CONF_ENV+/+HOST_PERL_FOO_CONF_ENV+, to specify additional
|
|
environment variables to pass to the +perl Makefile.PL+ or +perl Build.PL+.
|
|
By default, empty.
|
|
|
|
* +PERL_FOO_CONF_OPTS+/+HOST_PERL_FOO_CONF_OPTS+, to specify additional
|
|
configure options to pass to the +perl Makefile.PL+ or +perl Build.PL+.
|
|
By default, empty.
|
|
|
|
* +PERL_FOO_BUILD_OPTS+/+HOST_PERL_FOO_BUILD_OPTS+, to specify additional
|
|
options to pass to +make pure_all+ or +perl Build build+ in the build step.
|
|
By default, empty.
|
|
|
|
* +PERL_FOO_INSTALL_TARGET_OPTS+, to specify additional options to
|
|
pass to +make pure_install+ or +perl Build install+ in the install step.
|
|
By default, empty.
|
|
|
|
* +HOST_PERL_FOO_INSTALL_OPTS+, to specify additional options to
|
|
pass to +make pure_install+ or +perl Build install+ in the install step.
|
|
By default, empty.
|