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

[Yann E. MORIN <yann.morin.1998@free.fr>]

Fran?ois, All,

On 2013-11-23 10:25 +0100, Francois Perrad spake thusly:
> 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 :

I don't really like the way you introduce this by stating "how NOT to [...]".

I would prefer that you straight from the start state that they are
generated files, and still describe all the entries later. Maybe
something like:

    ---8<---
    The +.mk+ files for perl packages are generated files, by running
    the script +support/scripts/scancpan+ fron Buildroot's top
    directory:

    ---
    support/scripts/scancpan foo-bar
    ---

    In most cases, this script will generate a correct +.mk+ file,
    but in some cases (eg. when adding a native C dependency), manual
    editing might be needed.

    Here is how a +.mk+ for a perl package might look like:
    ---8<---

... and then continue with the standard layout below:

> +------------------------
> +01: ################################################################################
> +02: #
> +03: # libfoo-bar-perl
> +04: #
> +05: ################################################################################
> +06:
> +07: LIBFOO_BAR_PERL_VERSION = 0.02
> +08: LIBFOO_BAR_PERL_AUTHOR = MONGERS

There is no reason to include/introduce _AUTHORS, since;
  - your perl-infra does even use it
  - no other pkg-infra does it
  - the legal-info does not use it

> +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))

How does the scancpan script decide to emit target and/or host variants?

> +------------------------
> +
> +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.

This hunk should be included in the general description, above.

> +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+.

After discussing this at the Developpers' Day, we come to the conclusion
that, since it is needed to manually tweak some of the +.mk+ files, we
do prefer that all be committed in the tree, even if they are 100%
automatically generated.

> +[[perl-package-reference]]
> +
> ++perl-package+ reference
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +This infrastructure handles various Perl build systems :
> ++ExtUtils-MakeMaker+, +Module-Build+ and +Module-Build-Tiny+.

From wht I could see in patch 1, you only added two buildsystems:
Build.PL and Makefile.PL, while the sentence above implies there are
three. Did I miss anything?

> +The main macro of the Perl/CPAN package infrastructure is

Since you here mix perl and cpan, I wonder if the best name for this
infra is perl or cpan.

For example, the luarocks infra we recently added is called 'luarocks',
as per the repository of lua paclage, not 'lua' as per the language
name.

So maybe we should call this perl infdra cpan instead. Any comment
against that?

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'