c9b07cbdd0
Currently the text for each package infra that mentions the usage of variables already provided by the generic infra diverge from each other: - some (golang, kconfig, python) add a cross-referece to the generic infra chapter; - kconfig does not list any example; - some mention _LICENSE as an example, others don't; - some (cargo, golang, python) add an 'etc.' at the end of the examples, giving the idea that can be more symbols provided by the generic infra than the ones listed; - most have the text 'works by defining a number of variables before calling the +<macro-name>+ macro', except golang and kconfig; - some actually list 'A few additional variables' but keep using some old reference as 'An additional variable'; - some say 'First, all the package metadata' and other only 'All the package metadata'; - most mention _SUBDIR as an example of variable supported by the generic infra, even the generic infra manual not mentioning it. Improve the correctness for the manual by standardizing the text among the package infras: - use the same text "All the package metadata information variables that exist in the generic package infrastructure also exist in the <name> infrastructure:" for all of them; - add the cross-reference for all of them; - remove the examples of variables inherited from the generic infra - this also solves the _SUBDIR problem, there no longer is any reference to _SUBDIR; - wrap the modified text at 80 columns; - add "macro" to golang and luarocks infra; - use "A few additional variables" for qmake and waf. At same time, add a missing format on golang manual for BR2_PACKAGE_HOST_GO_HOST_ARCH_SUPPORTS. Cc: Eric Le Bihan <eric.le.bihan.dev@free.fr> Cc: Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> Signed-off-by: Ricardo Martincoski <ricardo.martincoski@gmail.com> [Arnout: - remove the examples; - add "the" where "macro" was added; - rewrite the preceding paragraphs for kconfig to make it more consistent. ] Signed-off-by: Arnout Vandecappelle <arnout@mind.be> (cherry picked from commit 4286c89f9d987f5f3bcbb14dfd58ba440944f4c2) Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
127 lines
5.0 KiB
Plaintext
127 lines
5.0 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: PERL_FOO_BAR_DISTNAME = Foo-Bar
|
|
14:
|
|
15: $(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).
|
|
|
|
On line 13, the name of the distribution as needed by the script
|
|
+utils/scancpan+ (in order to regenerate/upgrade these package files).
|
|
|
|
Finally, on line 15, 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 +utils/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.
|
|
|
|
All the package metadata information variables that exist in the
|
|
xref:generic-package-reference[generic package infrastructure] also
|
|
exist in the Perl/CPAN infrastructure.
|
|
|
|
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.
|