/[gentoo]/xml/htdocs/proj/en/perl/perl-herd.txt
Gentoo

Contents of /xml/htdocs/proj/en/perl/perl-herd.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations) (download)
Tue Apr 11 22:45:28 2006 UTC (12 years, 3 months ago) by ian
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +0 -0 lines
File MIME type: text/plain
FILE REMOVED
Beautification; linking to the new perl-herd.xml; removing old txt draft

1 Perl Herd Documentation
2
3 This document assumes a base understanding of general ebuild structure and
4 techniques. For more information, please see the following links.
5
6 LINK: Ebuild Etiquite/Policy Guide
7
8 Instead, this document is intended to highlight those places where the
9 perl-module ebuild differs from the average ebuild, what special variables are
10 available, and what the preferred structure/style should be.
11
12
13 *Ebuild Structure*
14
15 The average perl module ebuild follows a stock structure, relying heavily on
16 its parent eclass, perl-module.eclass. The first active line of a perl-module
17 ebuild, then is:
18
19 <code>
20 inherit perl-module
21 </code>
22
23 At the writing of this document, the perl-module eclass is all inclusive and
24 should be used both by modules and pure perl applications. This inclusion of
25 the perl-module eclass takes care of many of the actions handled in an ebuild,
26 such as whether to use Makemaker.PL or Build.PL, pre-compile steps,
27 documentation, etc. Some ebuilds in the portage tree do little more than
28 inherit this eclass and define a few necessary items, such as HOMEPAGE,
29 LICENSE, KEYWORDS, and SRC_URI and do nothing else.
30
31 In regards to SRC_URI, there is one note to keep in mind. If the source of the
32 module/code is located on the Comprehensive Perl Archive Network (CPAN),
33 please use the source of mirror://cpan/, which is actually translated as
34 http://some.cpan.mirror/CPAN. The reason for this is that although CPAN's
35 multiplexer is good at locating a mirror closest to you, it isn't perfect. By
36 using the thirdparty mirror ($PORTDIR/profiles/thirdpartymirrors), we allow
37 Gentoo users to substitute their preferred mirror location.
38
39 There is one variable unique to those ebuilds that inherit the perl-module
40 eclass, SRC_TEST. More detail will begin further in this document in regards
41 to perl testing, but it is this variable that will determine whether or not a
42 'make test' will be performed. If SRC_TEST is set to "do", the test block
43 within the perl-module eclass will be considered. A user must still have
44 maketest enabled in their features (/etc/make.conf) for these tests to be
45 performed, however.
46
47
48 *Testing*
49
50 This discussion of the SRC_TEST variable brings us to the topic of testing in
51 perl modules. The activation of this feature is dependant on many factors. The
52 short of it is, not all perl module tests are created equally. Some factors to
53 consider when deciding to activate tests are:
54
55 * Does the test even work? Write efficient perl module tests isn't always an
56 task, even for the author of the module. As anyone with multiple architectures
57 can attest to, what works on what computer doesn't necessarily work on
58 another. Non-working test suites do exist, and when encountered other steps
59 should be taken to test the functionality of the module. Examples from pods,
60 while still subject to typos, are generally good ways to test that a module is
61 functioning.
62
63 * What are the tests attempting to accomplish? Even if the tests work, it may
64 not be wise to enable them. If it's a database module, is it relying on a
65 running, local database to talk to in order to determine test success? If it's
66 a network related module, is it attempting to do anything on the network that
67 might raise a sysadmin's (or firewall's) hackles? Last year (2004), a CPAN
68 author had to retract the tests he included in a module because of security
69 concerns - his test suite would download remote code and attempt to execute.
70 In the context of the module, that made sense, but from a security
71 perspective, it was less than advisable.
72
73 * Do the tests depend on something more than a headless console? Many of
74 the graphical widget and X related modules have detailed test suites to make sure
75 their created items will interact appropriately. Unfortunately, they rely on
76 an active X display and the interaction of the user. In the non-interactive
77 world of Gentoo testing and installation, however, this is a problem. Again,
78 these are good tests to use during initial testing of the ebuild, but are not
79 appropriate for the masses.
80
81 * Do the tests introduce their own set of dependencies? Currently, Gentoo does
82 not support dependencies specifically for testing purposes. Unfortunately,
83 module authors don't have the same perspective. A fair number of modules
84 utilize specialized testing module suites for their own tests, but don't need
85 those modules either for building or for use on the live system. Over time,
86 some of these extraneous modules have made their way into the tree, and there
87 is the potential one day for a perl test suite of modules to be bundled into
88 portage. At this time however, including these testing modules as dependencies
89 can be costly to user disk and cycle times.
90
91 *Dependencies*
92
93 Tracking dependencies, both on new and existing module ebuilds, is perhaps the
94 most time consuming aspect of adding a new module. There are three initial
95 files to check for expressed dependencies. One should not rely on the warning
96 output of a "perl Makefile.PL" to determine dependencies - this output only
97 displays missing dependencies in your own installation and is not
98 comprehensive of what dependencies are needed.
99
100 First, reading through the Makefile.PL in your favorite editor should give a
101 fair amount of information on what, if any, dependencies are declared. Both
102 the PREREQUISITE block, as well as any leading logic that determines what is
103 placed in the PREREQ block, will give an indication of expected dependencies.
104
105 If present, the META.YML file can contain a break down of build and run time
106 dependencies. Additionaly, if present, the Build.PL file will also indicate
107 any dependencies for the module's building.
108
109 Unfortunately, this isn't always enough, though generally speaking it is a
110 fair indication. You may also need to recursively grep for <em>use</em> and
111 <em>require</em> statements to make sure that the author hasn't forgotten to
112 list anything. Generally, this last step isn't necessary, but it is important
113 to keep in mind, especially when dealing with new packages. This last step
114 will also help if there is any question on DEPEND versus RDEPEND information.
115
116 BEWARE THE TANGLED PATH OF A NEW MODULE AND IT'S DEPENDENCIES.
117
118 Adding a single new module to the tree (either to fill a dependency or for its
119 own sake) can lead to adding a dozen supporting modules before you are done.
120 Though adding to the bulk of dev-perl isn't a goal, this is an understood
121 risk. One should also take note of updating an existing ebuild module, though - sometimes
122 dependencies for a module change over time, and they need to be checked rather
123 than merely relying on the existing ebuild.

  ViewVC Help
Powered by ViewVC 1.1.20