[Buildroot] [pkg-perl infra V2 09/12] manual: adding packages perl

[Francois Perrad]

Signed-off-by: Francois Perrad <francois.perrad at gadz.org>
---
 docs/manual/adding-packages-perl.txt |   91 ++++++++++++++++++++++++++++++++++
 docs/manual/adding-packages.txt      |    2 +
 2 files changed, 93 insertions(+)
 create mode 100644 docs/manual/adding-packages-perl.txt

diff --git a/docs/manual/adding-packages-perl.txt b/docs/manual/adding-packages-perl.txt
new file mode 100644
index 0000000..4efc53a
--- /dev/null
+++ b/docs/manual/adding-packages-perl.txt
@@ -0,0 +1,91 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Infrastructure for Perl/CPAN packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[perl-package-tutorial]]
+
++perl-package+ tutorial
+^^^^^^^^^^^^^^^^^^^^^^^
+
+First, let's see how to NOT write a +.mk+ file for a Perl/CPAN package,
+with an example :
+
+------------------------
+01: ################################################################################
+02: #
+03: # libfoo-bar-perl
+04: #
+05: ################################################################################
+06:
+07: LIBFOO_BAR_PERL_VERSION = 0.02
+08: LIBFOO_BAR_PERL_AUTHOR = MONGERS
+09: LIBFOO_BAR_PERL_SOURCE = Foo-$(LIBFOO_BAR_PERL_VERSION).tar.gz
+10: LIBFOO_BAR_PERL_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER/
+11: LIBFOO_BAR_PERL_DEPENDENCIES = perl libstrictures-perl
+12: HOST_LIBFOO_BAR_PERL_DEPENDENCIES = host-libstrictures-perl
+13: LIBFOO_BAR_PERL_LICENSE = perl_5
+14:
+15: $(eval $(perl-package))
+16: $(eval $(host-perl-package))
+------------------------
+
+In fact, this file and the Config.in are written by running
+the script +supports/scripts/scancpan Foo-Bar+ in the +TOPDIR+ directory.
+This script creates packages for all required Perl/CPAN dependencies.
+All theses generated files are stored in the +package/cpan+ directory.
+In very specific case, this Makefile must be modified, for example : for
+adding a C native dependency.
+
+The Perl/CPAN modules are fine-grained, the number of module grows quickly
+over 100. So, only modified files will be stored in the Buildroot repository,
+all others can be regenerated by +scancpan+.
+
+[[perl-package-reference]]
+
++perl-package+ reference
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This infrastructure handles various Perl build systems :
++ExtUtils-MakeMaker+, +Module-Build+ and +Module-Build-Tiny+.
+
+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:
++LIBFOO_VERSION+, +LIBFOO_SOURCE+,
++LIBFOO_PATCH+, +LIBFOO_SITE+,
++LIBFOO_SUBDIR+, +LIBFOO_DEPENDENCIES+,
++LIBFOO_INSTALL_TARGET+.
+
+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.
+
+* +LIBFOO_CONF_OPT+, to specify additional configure
+  options to pass to the +perl Makefile.PL+ or +perl Build.PL+.
+  By default, empty.
+
+* +LIBFOO_BUILD_OPT+, to specify additional options to
+  pass to +make pure_all+ or +perl Build build+ in the build step.
+  By default, empty.
+
+* +LIBFOO_INSTALL_TARGET_OPT+, to specify additional options to
+  pass to +make pure_install+ or +perl Build install+ in the install step.
+  By default, empty.
+
+* +HOST_LIBFOO_INSTALL_OPT+, to specify additional options to
+  pass to +make pure_install+ or +perl Build install+ in the install step.
+  By default, empty.
+
+* +LIBFOO_CLEAN_OPT+, to specify additional options to
+  pass to +make clean+ or +perl Build clean+ in the clean step.
+  By default, empty.
diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt
index ae76e74..d5c2268 100644
--- a/docs/manual/adding-packages.txt
+++ b/docs/manual/adding-packages.txt
@@ -18,6 +18,8 @@ include::adding-packages-autotools.txt[]
 
 include::adding-packages-cmake.txt[]
 
+include::adding-packages-perl.txt[]
+
 include::adding-packages-hooks.txt[]
 
 include::adding-packages-gettext.txt[]
-- 
1.7.9.5