Project:Perl/perl-herd
Preliminaries
The devmanual has an ebuild HOWTO which is a useful primer.
This document assumes a base understanding of general ebuild structure and techniques.
This document is intended to highlight those places where the perl-module ebuild differs from the average ebuild, special variables and the preferred structure and style.
Ebuild Structure
The average perl module ebuild follows a stock structure, relying heavily on its parent eclass perl-module.eclass . The first active line of a perl-module ebuild, then is:
foo-1.0.0.ebuildinherit perl-module
The perl-module.eclass should be used for the building of any perl modules (code that installs to /usr/$(get_libdir)/perl5 ).
This inclusion of the perl-module.eclass takes care of many of the actions handled in an ebuild, such as whether to use Makemaker.PL or Build.PL, pre-compile steps, documentation, etc. Some ebuilds in the portage tree do little more than inherit this eclass and define a few necessary items, such as HOMEPAGE, LICENSE, and KEYWORDS.
For applications that only need access to perl utility functions, should consume perl-functions.eclass instead.
( There was a separate eclass perl-app.eclass for applications without the regular perl-module.eclass fanfare, but this is deprecated and should not be used in new code )
In regards to SRC_URI, there is one note to keep in mind. If the source of the module/code is located on the Comprehensive Perl Archive Network (CPAN), please use the source of mirror://cpan/, which is actually translated as http://some.cpan.mirror/CPAN. The reason for this is that although CPAN's multiplexer is good at locating a mirror closest to you, it isn't perfect. By using the thirdparty mirror ($PORTDIR/profiles/thirdpartymirrors), we allow Gentoo users to substitute their preferred mirror location.
perl-module.eclass inheriting classes can use a collection of control variables, (EAPI6: DIST_NAME, DIST_VERSION, DIST_A_EXT, DIST_A, DIST_AUTHOR, DIST_SECTION, DIST_EXAMPLES, DIST_TEST EAPI5-: MODULE_NAME, MODULE_VERSION, MODULE_A_EXT, MODULE_A, MODULE_AUTHOR, MODULE_SECTION, SRC_TEST) which simplify the construction of useful SRC_URI values, execution of tests, and installation of example code.
EAPI5 and lower ebuild's require an explicitly defined SRC_TEST to trigger an execution of make test during src_test, but as of EAPI6, the replacement control variable (DIST_TEST) assumes to trigger execution by default, and explicit assignment is only useful to disable or otherwise restrict execution of these tests.
A user must still have test enabled in their features (/etc/portage/make.conf) for these tests to be performed, however.
Testing
This discussion of the DIST_TEST (SRC_TEST prior to EAPI6) variable brings us to the topic of testing in perl modules. The activation of this feature is dependent on many factors. The short of it is, not all perl module tests are created equally. Some factors to consider when deciding to activate tests are:
- Does the test even work? Write efficient perl module tests isn't always an task, even for the author of the module. As anyone with multiple architectures can attest to, what works on what computer doesn't necessarily work on another. Non-working test suites do exist, and when encountered other steps should be taken to test the functionality of the module. Examples from pods, while still subject to typos, are generally good ways to test that a module is functioning.
- What are the tests attempting to accomplish? Even if the tests work, it may not be wise to enable them. If it's a database module, is it relying on a running, local database to talk to in order to determine test success? If it's a network related module, is it attempting to do anything on the network that might raise a sysadmin's (or firewall's) hackles? In 2004 (a year before this was originally written), a CPAN author had to retract the tests he included in a module because of security concerns - his test suite would download remote code and attempt to execute. In the context of the module, that made sense, but from a security perspective, it was less than advisable.
- Do the tests depend on something more than a headless console? Many of the graphical widget and X related modules have detailed test suites to make sure their created items will interact appropriately. Unfortunately, they rely on an active X display and the interaction of the user. In the non-interactive world of Gentoo testing and installation, however, this is a problem. Again, these are good tests to use during initial testing of the ebuild, but are not appropriate for the masses.
- Do the tests introduce their own set of dependencies? Currently, Gentoo does not support dependencies specifically for testing purposes. Unfortunately, module authors don't have the same perspective. A fair number of modules utilize specialized testing module suites for their own tests, but don't need those modules either for building or for use on the live system. Over time, some of these extraneous modules have made their way into the tree, and there is the potential one day for a perl test suite of modules to be bundled into portage. At this time however, including these testing modules as dependencies can be costly to user disk and cycle times.
Dependencies
Beware the tangled path of a new module and its dependencies.
Be sure to keep an eye out for module dependencies that are already fulfilled by having perl simply installed - and which perl they might have come with. If a Makefile.PL lists Test::More => 0 as a dependency, then there is no point in putting this into DEPEND since this was satisfied by having a working perl. But if they depend on Test::More => 0.62, you will need to check the virtuals directory.
Tracking dependencies, both on new and existing module ebuilds, is perhaps the most time consuming aspect of adding a new module. There are three initial files to check for expressed dependencies. One should not rely on the warning output of a perl Makefile.PL to determine dependencies - this output only displays missing dependencies in your own installation and is not comprehensive of what dependencies are needed.
First, reading through the Makefile.PL in your favorite editor should give a fair amount of information on what, if any, dependencies are declared. Both the PREREQUISITE block, as well as any leading logic that determines what is placed in the PREREQ block, will give an indication of expected dependencies.
If present, the META.YML file can contain a break down of build and run time dependencies. Additionaly, if present, the Build.PL file will also indicate any dependencies for the module's building.
Unfortunately, this isn't always enough, though generally speaking it is a fair indication. You may also need to recursively grep for use and require statements to make sure that the author hasn't forgotten to list anything. Generally, this last step isn't necessary, but it is important to keep in mind, especially when dealing with new packages. This last step will also help if there is any question on DEPEND versus RDEPEND information.
Adding a single new module to the tree (either to fill a dependency or for its own sake) can lead to adding a dozen supporting modules before you are done. Though adding to the bulk of dev-perl isn't a goal, this is an understood risk. One should also take note of updating an existing ebuild module, though - sometimes dependencies for a module change over time, and they need to be checked rather than merely relying on the existing ebuild.
Version numbers in Gentoo perl ebuilds
More information is detailed in Project:Perl/Version-Scheme.
Versioning on CPAN and versioning in the portage tree do not always align. Because a CPAN module's versioning scheme changes from author to author (and module's change hands over time), there are no consistant rules for how modules receive their version numbers. Portage, however, requires versions to follow a consistent format. Because of this, the perl team has had to employ version number minging on certain packages to compensate for the disparity, so that Gentoo's users always receive the latest version for their KEYWORDs. For example, dev-perl/module-build released version 0.28. Shortly afterwards, 0.2801-6 were released. If we had maintained these version numbers, portage would never recognize 0.29 as the successor, because in Portage math (where each decimal is a number seperator, not an indication of decimal math), 29 is less than 2801. As such, the minor release of Module::Build were renamed as 0.28.05, 0.28.06, etc.
"inherit versionator" and "delete_version_separator" are your best ally in these situations.
The easier way to get proper version scheme is to use special helper package dev-perl/Gentoo-PerlMod-Version. You can see below how it works:
user $/usr/bin/gentoo-perlmod-version.pl 0.700.70 => 0.700.0