adding-packages-perl.txt 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for Perl/CPAN packages
  4. [[perl-package-tutorial]]
  5. ==== +perl-package+ tutorial
  6. First, let's see how to write a +.mk+ file for a Perl/CPAN package,
  7. with an example :
  8. ------------------------
  9. 01: ################################################################################
  10. 02: #
  11. 03: # perl-foo-bar
  12. 04: #
  13. 05: ################################################################################
  14. 06:
  15. 07: PERL_FOO_BAR_VERSION = 0.02
  16. 08: PERL_FOO_BAR_SOURCE = Foo-Bar-$(PERL_FOO_BAR_VERSION).tar.gz
  17. 09: PERL_FOO_BAR_SITE = $(BR2_CPAN_MIRROR)/authors/id/M/MO/MONGER
  18. 10: PERL_FOO_BAR_DEPENDENCIES = perl-strictures
  19. 11: PERL_FOO_BAR_LICENSE = Artistic or GPL-1.0+
  20. 12: PERL_FOO_BAR_LICENSE_FILES = LICENSE
  21. 13: PERL_FOO_BAR_DISTNAME = Foo-Bar
  22. 14:
  23. 15: $(eval $(perl-package))
  24. ------------------------
  25. On line 7, we declare the version of the package.
  26. On line 8 and 9, we declare the name of the tarball and the location
  27. of the tarball on a CPAN server. Buildroot will automatically download
  28. the tarball from this location.
  29. On line 10, we declare our dependencies, so that they are built
  30. before the build process of our package starts.
  31. On line 11 and 12, we give licensing details about the package (its
  32. license on line 11, and the file containing the license text on line
  33. 12).
  34. On line 13, the name of the distribution as needed by the script
  35. +utils/scancpan+ (in order to regenerate/upgrade these package files).
  36. Finally, on line 15, we invoke the +perl-package+ macro that
  37. generates all the Makefile rules that actually allow the package to be
  38. built.
  39. Most of these data can be retrieved from https://metacpan.org/.
  40. So, this file and the Config.in can be generated by running
  41. the script +utils/scancpan Foo-Bar+ in the Buildroot directory
  42. (or in a br2-external tree).
  43. This script creates a Config.in file and foo-bar.mk file for the
  44. requested package, and also recursively for all dependencies specified by
  45. CPAN. You should still manually edit the result. In particular, the
  46. following things should be checked.
  47. * If the perl module links with a shared library that is provided by
  48. another (non-perl) package, this dependency is not added automatically.
  49. It has to be added manually to +PERL_FOO_BAR_DEPENDENCIES+.
  50. * The +package/Config.in+ file has to be updated manually to include the
  51. generated Config.in files. As a hint, the +scancpan+ script prints out
  52. the required +source "..."+ statements, sorted alphabetically.
  53. [[perl-package-reference]]
  54. ==== +perl-package+ reference
  55. As a policy, packages that provide Perl/CPAN modules should all be
  56. named +perl-<something>+ in Buildroot.
  57. This infrastructure handles various Perl build systems :
  58. +ExtUtils-MakeMaker+ (EUMM), +Module-Build+ (MB) and +Module-Build-Tiny+.
  59. +Build.PL+ is preferred by default when a package provides a +Makefile.PL+
  60. and a +Build.PL+.
  61. The main macro of the Perl/CPAN package infrastructure is
  62. +perl-package+. It is similar to the +generic-package+ macro. The ability to
  63. have target and host packages is also available, with the
  64. +host-perl-package+ macro.
  65. Just like the generic infrastructure, the Perl/CPAN infrastructure
  66. works by defining a number of variables before calling the
  67. +perl-package+ macro.
  68. First, all the package metadata information variables that exist in the
  69. generic infrastructure also exist in the Perl/CPAN infrastructure:
  70. +PERL_FOO_VERSION+, +PERL_FOO_SOURCE+,
  71. +PERL_FOO_PATCH+, +PERL_FOO_SITE+,
  72. +PERL_FOO_SUBDIR+, +PERL_FOO_DEPENDENCIES+,
  73. +PERL_FOO_INSTALL_TARGET+.
  74. Note that setting +PERL_FOO_INSTALL_STAGING+ to +YES+ has no effect
  75. unless a +PERL_FOO_INSTALL_STAGING_CMDS+ variable is defined. The perl
  76. infrastructure doesn't define these commands since Perl modules generally
  77. don't need to be installed to the +staging+ directory.
  78. A few additional variables, specific to the Perl/CPAN infrastructure,
  79. can also be defined. Many of them are only useful in very specific
  80. cases, typical packages will therefore only use a few of them.
  81. * +PERL_FOO_PREFER_INSTALLER+/+HOST_PERL_FOO_PREFER_INSTALLER+,
  82. specifies the preferred installation method. Possible values are
  83. +EUMM+ (for +Makefile.PL+ based installation using
  84. +ExtUtils-MakeMaker+) and +MB+ (for +Build.PL+ based installation
  85. using +Module-Build+). This variable is only used when the package
  86. provides both installation methods.
  87. * +PERL_FOO_CONF_ENV+/+HOST_PERL_FOO_CONF_ENV+, to specify additional
  88. environment variables to pass to the +perl Makefile.PL+ or +perl Build.PL+.
  89. By default, empty.
  90. * +PERL_FOO_CONF_OPTS+/+HOST_PERL_FOO_CONF_OPTS+, to specify additional
  91. configure options to pass to the +perl Makefile.PL+ or +perl Build.PL+.
  92. By default, empty.
  93. * +PERL_FOO_BUILD_OPTS+/+HOST_PERL_FOO_BUILD_OPTS+, to specify additional
  94. options to pass to +make pure_all+ or +perl Build build+ in the build step.
  95. By default, empty.
  96. * +PERL_FOO_INSTALL_TARGET_OPTS+, to specify additional options to
  97. pass to +make pure_install+ or +perl Build install+ in the install step.
  98. By default, empty.
  99. * +HOST_PERL_FOO_INSTALL_OPTS+, to specify additional options to
  100. pass to +make pure_install+ or +perl Build install+ in the install step.
  101. By default, empty.