-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathperl-herd.xml
236 lines (222 loc) · 10.8 KB
/
perl-herd.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/perl/perl-herd.xml,v 1.4 2007/03/12 12:56:09 mcummings Exp $ -->
<!-- Do Not Translate !! -->
<guide link="/proj/en/perl/perl-herd.xml">
<title>Gentoo Perl Herd Guide</title>
<author title="Author">
<mail link="mcummings@gentoo.org">Michael Cummings</mail>
</author>
<author title="Editor">
<mail link="ian@gentoo.org">Christian Hartmann</mail>
</author>
<abstract>
In which Gentoo devs attempt to explain the mechanics of the perl herd...
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
<version>1.0</version>
<date>2006-04-11</date>
<chapter>
<title>Intro</title>
<section id="Preliminaries">
<title>Preliminaries</title>
<body>
<p>
This document assumes a base understanding of general ebuild structure and
techniques. For more information, please see the following link.
</p>
<note>
<uri link="http://www.gentoo.org/proj/en/devrel/handbook/hb-guide-ebuild.xml">Ebuild HOWTO</uri>
</note>
<p>
This document is intended to highlight those places where the perl-module
ebuild differs from the average ebuild, what special variables are available,
and what the preferred structure/style should be.
</p>
<note>
If you are reading this guide because you want to submit ebuilds on bugzilla, please read this first:
<uri link="http://www.gentoo.org/proj/en/devrel/handbook/hb-policy-ebuild.xml">Perl in the POLICY</uri>
</note>
</body>
</section>
<section id="Ebuild Structure">
<title>Ebuild Structure</title>
<body>
<p>
The average perl module ebuild follows a stock structure, relying heavily on
its parent eclass, <path>perl-module.eclass</path>. The first active line of a
perl-module ebuild, then is:
</p>
<pre caption="">
inherit perl-module
</pre>
<p>
The perl-module eclass should be used for the building of any perl modules
(code that installs to <path>/usr/$(get_libdir)/perl5</path> ). There is a
separate eclass for applications that need use of the perl eclass functions,
but that may not need the whole plethora. At the time of this writing the
differences between the two eclasses are minimal.
</p>
<p>
This inclusion of the perl-* eclass takes care of many of the actions
handled in an ebuild, such as whether to use <path>Makemaker.PL</path> or
<path>Build.PL</path>, 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, KEYWORDS, and SRC_URI.
</p>
<note>By default, the perl-module eclass will now default to using Makefile.PL's
and only resorting to using the Build.PL if necessary. This follows an active
discussion the p5p mailing list in which it was highlighted that this is the
preferred course by the authors of Module::Build</note>
<p>
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 <path>mirror://cpan/</path>, which is actually
translated as <path>http://some.cpan.mirror/CPAN</path>. 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
(<path>$PORTDIR/profiles/thirdpartymirrors</path>), we allow Gentoo users to
substitute their preferred mirror location.
</p>
<p>
There is one variable unique to those ebuilds that inherit the perl-module
eclass, SRC_TEST. More detail will begin further in this document in regards
to perl testing, but it is this variable that will determine whether or not a
<path>'make test'</path> will be performed. If SRC_TEST is set to <e>do</e>,
the test block within the perl-module eclass will be considered. A user must
still have test enabled in their features (<path>/etc/make.conf</path>) for
these tests to be performed, however.
</p>
</body>
</section>
<section id="Testing">
<title>Testing</title>
<body>
<p>
This discussion of the SRC_TEST variable brings us to the topic of testing in
perl modules. The activation of this feature is dependant 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:
</p>
<ul>
<li>
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.
</li>
<li>
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? Last year (2004), 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.
</li>
<li>
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.
</li>
<li>
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.
</li>
</ul>
</body>
</section>
<section id="Dependencies">
<title>Dependencies</title>
<body>
<p>
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 <path>perl Makefile.PL</path> to determine dependencies - this
output only displays missing dependencies in your own installation and is not
comprehensive of what dependencies are needed.
</p>
<p>
First, reading through the <path>Makefile.PL</path> 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.
</p>
<p>
If present, the <path>META.YML</path> file can contain a break down of build
and run time dependencies. Additionaly, if present, the <path>Build.PL</path>
file will also indicate any dependencies for the module's building.
</p>
<p>
Unfortunately, this isn't always enough, though generally speaking it is a
fair indication. You may also need to recursively grep for <b>use</b> and
<b>require</b> 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.
</p>
<warn>BEWARE THE TANGLED PATH OF A NEW MODULE AND IT'S DEPENDENCIES.</warn>
<p>
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.
</p>
<note>
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 <path>Makefile.PL</path> lists <path>Test::More => 0</path> 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 <path>Test::More => 0.62</path>,
you will need to check the virtuals directory.
</note>
</body>
</section>
<section id="ExtUtils-MakeMaker">
<title>ExtUtils-MakeMaker</title>
<body>
<p>
perl-core/ExtUtils-MakeMaker should never be added as a dependancy to an ebuild
unless you are working on a package that <b>requires</b> a version greater than
the one provided by the currently stable dev-lang/perl package. It's existance in the
tree at this point is solely to provide a bridge for those users that haven't upgraded
their perl's in quite some time, but continue to use the dev-perl/perl-core portions
of portage.
</p>
</body>
</section>
<section id="Versioning">
<title>Version numbers in Gentoo perl ebuilds</title>
<body>
<p>
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 module's 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 released of Module::Build were renamed as 0.28.05, 0.28.06, etc.
</p>
<note>
"inherit versionator" and "delete_version_serarator" are your best ally in these situations.
</note>
</body>
</section>
</chapter>
</guide>