Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "Module::Build::API 3" |
132 | .TH Module::Build::API 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | Module::Build::API \- API Reference for Module Authors |
135 | .SH "DESCRIPTION" |
136 | .IX Header "DESCRIPTION" |
137 | I list here some of the most important methods in \f(CW\*(C`Module::Build\*(C'\fR. |
138 | Normally you won't need to deal with these methods unless you want to |
139 | subclass \f(CW\*(C`Module::Build\*(C'\fR. But since one of the reasons I created |
140 | this module in the first place was so that subclassing is possible |
141 | (and easy), I will certainly write more docs as the interface |
142 | stabilizes. |
143 | .Sh "\s-1CONSTRUCTORS\s0" |
144 | .IX Subsection "CONSTRUCTORS" |
145 | .IP "\fIcurrent()\fR" 4 |
146 | .IX Item "current()" |
147 | [version 0.20] |
148 | .Sp |
149 | This method returns a reasonable facsimile of the currently-executing |
150 | \&\f(CW\*(C`Module::Build\*(C'\fR object representing the current build. You can use |
151 | this object to query its \*(L"\fInotes()\fR\*(R" method, inquire about installed |
152 | modules, and so on. This is a great way to share information between |
153 | different parts of your build process. For instance, you can ask |
154 | the user a question during \f(CW\*(C`perl Build.PL\*(C'\fR, then use their answer |
155 | during a regression test: |
156 | .Sp |
157 | .Vb 3 |
158 | \& # In Build.PL: |
159 | \& my $color = $build\->prompt("What is your favorite color?"); |
160 | \& $build\->notes(color => $color); |
161 | .Ve |
162 | .Sp |
163 | .Vb 5 |
164 | \& # In t/colortest.t: |
165 | \& use Module::Build; |
166 | \& my $build = Module::Build\->current; |
167 | \& my $color = $build\->notes('color'); |
168 | \& ... |
169 | .Ve |
170 | .Sp |
171 | The way the \f(CW\*(C`current()\*(C'\fR method is currently implemented, there may be |
172 | slight differences between the \f(CW$build\fR object in Build.PL and the |
173 | one in \f(CW\*(C`t/colortest.t\*(C'\fR. It is our goal to minimize these differences |
174 | in future releases of Module::Build, so please report any anomalies |
175 | you find. |
176 | .Sp |
177 | One important caveat: in its current implementation, \f(CW\*(C`current()\*(C'\fR will |
178 | \&\fB\s-1NOT\s0\fR work correctly if you have changed out of the directory that |
179 | \&\f(CW\*(C`Module::Build\*(C'\fR was invoked from. |
180 | .IP "\fInew()\fR" 4 |
181 | .IX Item "new()" |
182 | [version 0.03] |
183 | .Sp |
184 | Creates a new Module::Build object. Arguments to the \fInew()\fR method are |
185 | listed below. Most arguments are optional, but you must provide |
186 | either the \*(L"module_name\*(R" argument, or \*(L"dist_name\*(R" and one of |
187 | \&\*(L"dist_version\*(R" or \*(L"dist_version_from\*(R". In other words, you must |
188 | provide enough information to determine both a distribution name and |
189 | version. |
190 | .RS 4 |
191 | .IP "add_to_cleanup" 4 |
192 | .IX Item "add_to_cleanup" |
193 | [version 0.19] |
194 | .Sp |
195 | An array reference of files to be cleaned up when the \f(CW\*(C`clean\*(C'\fR action |
196 | is performed. See also the \fIadd_to_cleanup()\fR |
197 | method. |
198 | .IP "auto_configure_requires" 4 |
199 | .IX Item "auto_configure_requires" |
200 | [version 0.34] |
201 | .Sp |
202 | This parameter determines whether Module::Build will add itself |
203 | automatically to configure_requires (and build_requires) if Module::Build |
204 | is not already there. The required version will be the last 'major' release, |
205 | as defined by the decimal version truncated to two decimal places (e.g. 0.34, |
206 | instead of 0.3402). The default value is true. |
207 | .IP "auto_features" 4 |
208 | .IX Item "auto_features" |
209 | [version 0.26] |
210 | .Sp |
211 | This parameter supports the setting of features (see |
212 | \&\*(L"feature($name)\*(R") automatically based on a set of prerequisites. For |
213 | instance, for a module that could optionally use either MySQL or |
214 | PostgreSQL databases, you might use \f(CW\*(C`auto_features\*(C'\fR like this: |
215 | .Sp |
216 | .Vb 16 |
217 | \& my $build = Module::Build\->new |
218 | \& ( |
219 | \& ...other stuff here... |
220 | \& auto_features => { |
221 | \& pg_support => { |
222 | \& description => "Interface with Postgres databases", |
223 | \& requires => { 'DBD::Pg' => 23.3, |
224 | \& 'DateTime::Format::Pg' => 0 }, |
225 | \& }, |
226 | \& mysql_support => { |
227 | \& description => "Interface with MySQL databases", |
228 | \& requires => { 'DBD::mysql' => 17.9, |
229 | \& 'DateTime::Format::MySQL' => 0 }, |
230 | \& }, |
231 | \& } |
232 | \& ); |
233 | .Ve |
234 | .Sp |
235 | For each feature named, the required prerequisites will be checked, and |
236 | if there are no failures, the feature will be enabled (set to \f(CW1\fR). |
237 | Otherwise the failures will be displayed to the user and the feature |
238 | will be disabled (set to \f(CW0\fR). |
239 | .Sp |
240 | See the documentation for \*(L"requires\*(R" for the details of how |
241 | requirements can be specified. |
242 | .IP "autosplit" 4 |
243 | .IX Item "autosplit" |
244 | [version 0.04] |
245 | .Sp |
246 | An optional \f(CW\*(C`autosplit\*(C'\fR argument specifies a file which should be run |
247 | through the \fIAutoSplit::autosplit()\fR function. |
248 | If multiple files should be split, the argument may be given as an |
249 | array of the files to split. |
250 | .Sp |
251 | In general I don't consider autosplitting a great idea, because it's |
252 | not always clear that autosplitting achieves its intended performance |
253 | benefits. It may even harm performance in environments like mod_perl, |
254 | where as much as possible of a module's code should be loaded during |
255 | startup. |
256 | .IP "build_class" 4 |
257 | .IX Item "build_class" |
258 | [version 0.28] |
259 | .Sp |
260 | The Module::Build class or subclass to use in the build script. |
261 | Defaults to \*(L"Module::Build\*(R" or the class name passed to or created by |
262 | a call to \*(L"\fIsubclass()\fR\*(R". This property is useful if you're |
263 | writing a custom Module::Build subclass and have a bootstrapping |
264 | problem\*(--that is, your subclass requires modules that may not be |
265 | installed when \f(CW\*(C`perl Build.PL\*(C'\fR is executed, but you've listed in |
266 | \&\*(L"build_requires\*(R" so that they should be available when \f(CW\*(C`./Build\*(C'\fR is |
267 | executed. |
268 | .IP "build_requires" 4 |
269 | .IX Item "build_requires" |
270 | [version 0.07] |
271 | .Sp |
272 | Modules listed in this section are necessary to build and install the |
273 | given module, but are not necessary for regular usage of it. This is |
274 | actually an important distinction \- it allows for tighter control over |
275 | the body of installed modules, and facilitates correct dependency |
276 | checking on binary/packaged distributions of the module. |
277 | .Sp |
278 | See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring |
279 | for the details of how requirements can be specified. |
280 | .IP "create_packlist" 4 |
281 | .IX Item "create_packlist" |
282 | [version 0.28] |
283 | .Sp |
284 | If true, this parameter tells Module::Build to create a \fI.packlist\fR |
285 | file during the \f(CW\*(C`install\*(C'\fR action, just like \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR does. |
286 | The file is created in a subdirectory of the \f(CW\*(C`arch\*(C'\fR installation |
287 | location. It is used by some other tools (\s-1CPAN\s0, \s-1CPANPLUS\s0, etc.) for |
288 | determining what files are part of an install. |
289 | .Sp |
290 | The default value is true. This parameter was introduced in |
291 | Module::Build version 0.2609; previously no packlists were ever |
292 | created by Module::Build. |
293 | .IP "c_source" 4 |
294 | .IX Item "c_source" |
295 | [version 0.04] |
296 | .Sp |
297 | An optional \f(CW\*(C`c_source\*(C'\fR argument specifies a directory which contains |
298 | C source files that the rest of the build may depend on. Any \f(CW\*(C`.c\*(C'\fR |
299 | files in the directory will be compiled to object files. The |
300 | directory will be added to the search path during the compilation and |
301 | linking phases of any C or \s-1XS\s0 files. |
302 | .IP "conflicts" 4 |
303 | .IX Item "conflicts" |
304 | [version 0.07] |
305 | .Sp |
306 | Modules listed in this section conflict in some serious way with the |
307 | given module. \f(CW\*(C`Module::Build\*(C'\fR (or some higher-level tool) will |
308 | refuse to install the given module if the given module/version is also |
309 | installed. |
310 | .Sp |
311 | See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring |
312 | for the details of how requirements can be specified. |
313 | .IP "create_license" 4 |
314 | .IX Item "create_license" |
315 | [version 0.31] |
316 | .Sp |
317 | This parameter tells Module::Build to automatically create a |
318 | \&\fI\s-1LICENSE\s0\fR file at the top level of your distribution, containing the |
319 | full text of the author's chosen license. This requires |
320 | \&\f(CW\*(C`Software::License\*(C'\fR on the author's machine, and further requires |
321 | that the \f(CW\*(C`license\*(C'\fR parameter specifies a license that it knows about. |
322 | .IP "create_makefile_pl" 4 |
323 | .IX Item "create_makefile_pl" |
324 | [version 0.19] |
325 | .Sp |
326 | This parameter lets you use \f(CW\*(C`Module::Build::Compat\*(C'\fR during the |
327 | \&\f(CW\*(C`distdir\*(C'\fR (or \f(CW\*(C`dist\*(C'\fR) action to automatically create a Makefile.PL |
328 | for compatibility with \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. The parameter's value |
329 | should be one of the styles named in the Module::Build::Compat |
330 | documentation. |
331 | .IP "create_readme" 4 |
332 | .IX Item "create_readme" |
333 | [version 0.22] |
334 | .Sp |
335 | This parameter tells Module::Build to automatically create a \fI\s-1README\s0\fR |
336 | file at the top level of your distribution. Currently it will simply |
337 | use \f(CW\*(C`Pod::Text\*(C'\fR (or \f(CW\*(C`Pod::Readme\*(C'\fR if it's installed) on the file |
338 | indicated by \f(CW\*(C`dist_version_from\*(C'\fR and put the result in the \fI\s-1README\s0\fR |
339 | file. This is by no means the only recommended style for writing a |
340 | \&\fI\s-1README\s0\fR, but it seems to be one common one used on the \s-1CPAN\s0. |
341 | .Sp |
342 | If you generate a \fI\s-1README\s0\fR in this way, it's probably a good idea to |
343 | create a separate \fI\s-1INSTALL\s0\fR file if that information isn't in the |
344 | generated \fI\s-1README\s0\fR. |
345 | .IP "dist_abstract" 4 |
346 | .IX Item "dist_abstract" |
347 | [version 0.20] |
348 | .Sp |
349 | This should be a short description of the distribution. This is used when |
350 | generating metadata for \fI\s-1META\s0.yml\fR and \s-1PPD\s0 files. If it is not given |
351 | then \f(CW\*(C`Module::Build\*(C'\fR looks in the \s-1POD\s0 of the module from which it gets |
352 | the distribution's version. If it finds a \s-1POD\s0 section marked \*(L"=head1 |
353 | \&\s-1NAME\s0\*(R", then it looks for the first line matching \f(CW\*(C`\es+\-\es+(.+)\*(C'\fR, |
354 | and uses the captured text as the abstract. |
355 | .IP "dist_author" 4 |
356 | .IX Item "dist_author" |
357 | [version 0.20] |
358 | .Sp |
359 | This should be something like \*(L"John Doe <jdoe@example.com>\*(R", or if |
360 | there are multiple authors, an anonymous array of strings may be |
361 | specified. This is used when generating metadata for \fI\s-1META\s0.yml\fR and |
362 | \&\s-1PPD\s0 files. If this is not specified, then \f(CW\*(C`Module::Build\*(C'\fR looks at |
363 | the module from which it gets the distribution's version. If it finds |
364 | a \s-1POD\s0 section marked \*(L"=head1 \s-1AUTHOR\s0\*(R", then it uses the contents of |
365 | this section. |
366 | .IP "dist_name" 4 |
367 | .IX Item "dist_name" |
368 | [version 0.11] |
369 | .Sp |
370 | Specifies the name for this distribution. Most authors won't need to |
371 | set this directly, they can use \f(CW\*(C`module_name\*(C'\fR to set \f(CW\*(C`dist_name\*(C'\fR to |
372 | a reasonable default. However, some agglomerative distributions like |
373 | \&\f(CW\*(C`libwww\-perl\*(C'\fR or \f(CW\*(C`bioperl\*(C'\fR have names that don't correspond directly |
374 | to a module name, so \f(CW\*(C`dist_name\*(C'\fR can be set independently. |
375 | .IP "dist_version" 4 |
376 | .IX Item "dist_version" |
377 | [version 0.11] |
378 | .Sp |
379 | Specifies a version number for the distribution. See \*(L"module_name\*(R" |
380 | or \*(L"dist_version_from\*(R" for ways to have this set automatically from a |
381 | \&\f(CW$VERSION\fR variable in a module. One way or another, a version |
382 | number needs to be set. |
383 | .IP "dist_version_from" 4 |
384 | .IX Item "dist_version_from" |
385 | [version 0.11] |
386 | .Sp |
387 | Specifies a file to look for the distribution version in. Most |
388 | authors won't need to set this directly, they can use \*(L"module_name\*(R" |
389 | to set it to a reasonable default. |
390 | .Sp |
391 | The version is extracted from the specified file according to the same |
392 | rules as ExtUtils::MakeMaker and \f(CW\*(C`CPAN.pm\*(C'\fR. It involves finding |
393 | the first line that matches the regular expression |
394 | .Sp |
395 | .Vb 1 |
396 | \& /([\e$*])(([\ew\e:\e']*)\ebVERSION)\eb.*\e=/ |
397 | .Ve |
398 | .Sp |
399 | \&\fIeval()\fR\-ing that line, then checking the value of the \f(CW$VERSION\fR |
400 | variable. Quite ugly, really, but all the modules on \s-1CPAN\s0 depend on |
401 | this process, so there's no real opportunity to change to something |
402 | better. |
403 | .Sp |
404 | If the target file of \*(L"dist_version_from\*(R" contains more than one package |
405 | declaration, the version returned will be the one matching the configured |
406 | \&\*(L"module_name\*(R". |
407 | .IP "dynamic_config" 4 |
408 | .IX Item "dynamic_config" |
409 | [version 0.07] |
410 | .Sp |
411 | A boolean flag indicating whether the \fIBuild.PL\fR file must be |
412 | executed, or whether this module can be built, tested and installed |
413 | solely from consulting its metadata file. The main reason to set this |
414 | to a true value is that your module performs some dynamic |
415 | configuration as part of its build/install process. If the flag is |
416 | omitted, the \fI\s-1META\s0.yml\fR spec says that installation tools should |
417 | treat it as 1 (true), because this is a safer way to behave. |
418 | .Sp |
419 | Currently \f(CW\*(C`Module::Build\*(C'\fR doesn't actually do anything with this flag |
420 | \&\- it's up to higher-level tools like \f(CW\*(C`CPAN.pm\*(C'\fR to do something useful |
421 | with it. It can potentially bring lots of security, packaging, and |
422 | convenience improvements. |
423 | .IP "extra_compiler_flags" 4 |
424 | .IX Item "extra_compiler_flags" |
425 | .PD 0 |
426 | .IP "extra_linker_flags" 4 |
427 | .IX Item "extra_linker_flags" |
428 | .PD |
429 | [version 0.19] |
430 | .Sp |
431 | These parameters can contain array references (or strings, in which |
432 | case they will be split into arrays) to pass through to the compiler |
433 | and linker phases when compiling/linking C code. For example, to tell |
434 | the compiler that your code is \*(C+, you might do: |
435 | .Sp |
436 | .Vb 5 |
437 | \& my $build = Module::Build\->new |
438 | \& ( |
439 | \& module_name => 'Foo::Bar', |
440 | \& extra_compiler_flags => ['\-x', 'c++'], |
441 | \& ); |
442 | .Ve |
443 | .Sp |
444 | To link your \s-1XS\s0 code against glib you might write something like: |
445 | .Sp |
446 | .Vb 7 |
447 | \& my $build = Module::Build\->new |
448 | \& ( |
449 | \& module_name => 'Foo::Bar', |
450 | \& dynamic_config => 1, |
451 | \& extra_compiler_flags => scalar `glib\-config \-\-cflags`, |
452 | \& extra_linker_flags => scalar `glib\-config \-\-libs`, |
453 | \& ); |
454 | .Ve |
455 | .IP "get_options" 4 |
456 | .IX Item "get_options" |
457 | [version 0.26] |
458 | .Sp |
459 | You can pass arbitrary command line options to \fIBuild.PL\fR or |
460 | \&\fIBuild\fR, and they will be stored in the Module::Build object and can |
461 | be accessed via the \*(L"\fIargs()\fR\*(R" method. However, sometimes you want |
462 | more flexibility out of your argument processing than this allows. In |
463 | such cases, use the \f(CW\*(C`get_options\*(C'\fR parameter to pass in a hash |
464 | reference of argument specifications, and the list of arguments to |
465 | \&\fIBuild.PL\fR or \fIBuild\fR will be processed according to those |
466 | specifications before they're passed on to \f(CW\*(C`Module::Build\*(C'\fR's own |
467 | argument processing. |
468 | .Sp |
469 | The supported option specification hash keys are: |
470 | .RS 4 |
471 | .IP "type" 4 |
472 | .IX Item "type" |
473 | The type of option. The types are those supported by Getopt::Long; consult |
474 | its documentation for a complete list. Typical types are \f(CW\*(C`=s\*(C'\fR for strings, |
475 | \&\f(CW\*(C`+\*(C'\fR for additive options, and \f(CW\*(C`!\*(C'\fR for negatable options. If the |
476 | type is not specified, it will be considered a boolean, i.e. no |
477 | argument is taken and a value of 1 will be assigned when the option is |
478 | encountered. |
479 | .IP "store" 4 |
480 | .IX Item "store" |
481 | A reference to a scalar in which to store the value passed to the option. |
482 | If not specified, the value will be stored under the option name in the |
483 | hash returned by the \f(CW\*(C`args()\*(C'\fR method. |
484 | .IP "default" 4 |
485 | .IX Item "default" |
486 | A default value for the option. If no default value is specified and no option |
487 | is passed, then the option key will not exist in the hash returned by |
488 | \&\f(CW\*(C`args()\*(C'\fR. |
489 | .RE |
490 | .RS 4 |
491 | .Sp |
492 | You can combine references to your own variables or subroutines with |
493 | unreferenced specifications, for which the result will also be stored in the |
494 | hash returned by \f(CW\*(C`args()\*(C'\fR. For example: |
495 | .Sp |
496 | .Vb 10 |
497 | \& my $loud = 0; |
498 | \& my $build = Module::Build\->new |
499 | \& ( |
500 | \& module_name => 'Foo::Bar', |
501 | \& get_options => { |
502 | \& Loud => { store => \e$loud }, |
503 | \& Dbd => { type => '=s' }, |
504 | \& Quantity => { type => '+' }, |
505 | \& } |
506 | \& ); |
507 | .Ve |
508 | .Sp |
509 | .Vb 4 |
510 | \& print STDERR "HEY, ARE YOU LISTENING??\en" if $loud; |
511 | \& print "We'll use the ", $build\->args('Dbd'), " DBI driver\en"; |
512 | \& print "Are you sure you want that many?\en" |
513 | \& if $build\->args('Quantity') > 2; |
514 | .Ve |
515 | .Sp |
516 | The arguments for such a specification can be called like so: |
517 | .Sp |
518 | .Vb 1 |
519 | \& perl Build.PL \-\-Loud \-\-Dbd=DBD::pg \-\-Quantity \-\-Quantity \-\-Quantity |
520 | .Ve |
521 | .Sp |
522 | \&\fB\s-1WARNING:\s0\fR Any option specifications that conflict with Module::Build's own |
523 | options (defined by its properties) will throw an exception. Use capitalized |
524 | option names to avoid unintended conflicts with future Module::Build options. |
525 | .Sp |
526 | Consult the Getopt::Long documentation for details on its usage. |
527 | .RE |
528 | .IP "include_dirs" 4 |
529 | .IX Item "include_dirs" |
530 | [version 0.24] |
531 | .Sp |
532 | Specifies any additional directories in which to search for C header |
533 | files. May be given as a string indicating a single directory, or as |
534 | a list reference indicating multiple directories. |
535 | .IP "install_path" 4 |
536 | .IX Item "install_path" |
537 | [version 0.19] |
538 | .Sp |
539 | You can set paths for individual installable elements by using the |
540 | \&\f(CW\*(C`install_path\*(C'\fR parameter: |
541 | .Sp |
542 | .Vb 8 |
543 | \& my $build = Module::Build\->new |
544 | \& ( |
545 | \& ...other stuff here... |
546 | \& install_path => { |
547 | \& lib => '/foo/lib', |
548 | \& arch => '/foo/lib/arch', |
549 | \& } |
550 | \& ); |
551 | .Ve |
552 | .IP "installdirs" 4 |
553 | .IX Item "installdirs" |
554 | [version 0.19] |
555 | .Sp |
556 | Determines where files are installed within the normal perl hierarchy |
557 | as determined by \fIConfig.pm\fR. Valid values are: \f(CW\*(C`core\*(C'\fR, \f(CW\*(C`site\*(C'\fR, |
558 | \&\f(CW\*(C`vendor\*(C'\fR. The default is \f(CW\*(C`site\*(C'\fR. See |
559 | \&\*(L"\s-1INSTALL\s0 \s-1PATHS\s0\*(R" in Module::Build |
560 | .IP "license" 4 |
561 | .IX Item "license" |
562 | [version 0.07] |
563 | .Sp |
564 | Specifies the licensing terms of your distribution. Valid options include: |
565 | .RS 4 |
566 | .IP "apache" 4 |
567 | .IX Item "apache" |
568 | The distribution is licensed under the Apache Software License |
569 | (<http://opensource.org/licenses/apachepl.php>). |
570 | .IP "artistic" 4 |
571 | .IX Item "artistic" |
572 | The distribution is licensed under the Artistic License, as specified |
573 | by the \fIArtistic\fR file in the standard Perl distribution. |
574 | .IP "artistic_2" 4 |
575 | .IX Item "artistic_2" |
576 | The distribution is licensed under the Artistic 2.0 License |
577 | (<http://opensource.org/licenses/artistic\-license\-2.0.php>.) |
578 | .IP "bsd" 4 |
579 | .IX Item "bsd" |
580 | The distribution is licensed under the \s-1BSD\s0 License |
581 | (<http://www.opensource.org/licenses/bsd\-license.php>). |
582 | .IP "gpl" 4 |
583 | .IX Item "gpl" |
584 | The distribution is licensed under the terms of the \s-1GNU\s0 General |
585 | Public License (<http://www.opensource.org/licenses/gpl\-license.php>). |
586 | .IP "lgpl" 4 |
587 | .IX Item "lgpl" |
588 | The distribution is licensed under the terms of the \s-1GNU\s0 Lesser |
589 | General Public License |
590 | (<http://www.opensource.org/licenses/lgpl\-license.php>). |
591 | .IP "mit" 4 |
592 | .IX Item "mit" |
593 | The distribution is licensed under the \s-1MIT\s0 License |
594 | (<http://opensource.org/licenses/mit\-license.php>). |
595 | .IP "mozilla" 4 |
596 | .IX Item "mozilla" |
597 | The distribution is licensed under the Mozilla Public |
598 | License. (<http://opensource.org/licenses/mozilla1.0.php> or |
599 | <http://opensource.org/licenses/mozilla1.1.php>) |
600 | .IP "open_source" 4 |
601 | .IX Item "open_source" |
602 | The distribution is licensed under some other Open Source |
603 | Initiative-approved license listed at |
604 | <http://www.opensource.org/licenses/>. |
605 | .IP "perl" 4 |
606 | .IX Item "perl" |
607 | The distribution may be copied and redistributed under the same terms |
608 | as Perl itself (this is by far the most common licensing option for |
609 | modules on \s-1CPAN\s0). This is a dual license, in which the user may |
610 | choose between either the \s-1GPL\s0 or the Artistic license. |
611 | .IP "restrictive" 4 |
612 | .IX Item "restrictive" |
613 | The distribution may not be redistributed without special permission |
614 | from the author and/or copyright holder. |
615 | .IP "unrestricted" 4 |
616 | .IX Item "unrestricted" |
617 | The distribution is licensed under a license that is \fBnot\fR approved |
618 | by www.opensource.org but that allows distribution without |
619 | restrictions. |
620 | .RE |
621 | .RS 4 |
622 | .Sp |
623 | Note that you must still include the terms of your license in your |
624 | documentation \- this field only lets automated tools figure out your |
625 | licensing restrictions. Humans still need something to read. If you |
626 | choose to provide this field, you should make sure that you keep it in |
627 | sync with your written documentation if you ever change your licensing |
628 | terms. |
629 | .Sp |
630 | You may also use a license type of \f(CW\*(C`unknown\*(C'\fR if you don't wish to |
631 | specify your terms in the metadata. |
632 | .Sp |
633 | It is a fatal error to use a license other than the ones mentioned |
634 | above. This is not because I wish to impose licensing terms on you \- |
635 | please let me know if you would like another license option to be |
636 | added to the list. I just started out with a small set of licenses to |
637 | keep things simple, figuring I'd let people with actual working |
638 | knowledge in this area tell me what to do. So if that's you, drop me |
639 | a line. |
640 | .RE |
641 | .IP "meta_add" 4 |
642 | .IX Item "meta_add" |
643 | [version 0.28] |
644 | .Sp |
645 | A hash of key/value pairs that should be added to the \fI\s-1META\s0.yml\fR file |
646 | during the \f(CW\*(C`distmeta\*(C'\fR action. Any existing entries with the same |
647 | names will be overridden. |
648 | .Sp |
649 | See the \*(L"\s-1MODULE\s0 \s-1METADATA\s0\*(R" section for details. |
650 | .IP "meta_merge" 4 |
651 | .IX Item "meta_merge" |
652 | [version 0.28] |
653 | .Sp |
654 | A hash of key/value pairs that should be merged into the \fI\s-1META\s0.yml\fR |
655 | file during the \f(CW\*(C`distmeta\*(C'\fR action. Any existing entries with the |
656 | same names will be overridden. |
657 | .Sp |
658 | The only difference between \f(CW\*(C`meta_add\*(C'\fR and \f(CW\*(C`meta_merge\*(C'\fR is their |
659 | behavior on hash-valued and array-valued entries: \f(CW\*(C`meta_add\*(C'\fR will |
660 | completely blow away the existing hash or array value, but |
661 | \&\f(CW\*(C`meta_merge\*(C'\fR will merge the supplied data into the existing hash or |
662 | array value. |
663 | .Sp |
664 | See the \*(L"\s-1MODULE\s0 \s-1METADATA\s0\*(R" section for details. |
665 | .IP "module_name" 4 |
666 | .IX Item "module_name" |
667 | [version 0.03] |
668 | .Sp |
669 | The \f(CW\*(C`module_name\*(C'\fR is a shortcut for setting default values of |
670 | \&\f(CW\*(C`dist_name\*(C'\fR and \f(CW\*(C`dist_version_from\*(C'\fR, reflecting the fact that the |
671 | majority of \s-1CPAN\s0 distributions are centered around one \*(L"main\*(R" module. |
672 | For instance, if you set \f(CW\*(C`module_name\*(C'\fR to \f(CW\*(C`Foo::Bar\*(C'\fR, then |
673 | \&\f(CW\*(C`dist_name\*(C'\fR will default to \f(CW\*(C`Foo\-Bar\*(C'\fR and \f(CW\*(C`dist_version_from\*(C'\fR will |
674 | default to \f(CW\*(C`lib/Foo/Bar.pm\*(C'\fR. \f(CW\*(C`dist_version_from\*(C'\fR will in turn be |
675 | used to set \f(CW\*(C`dist_version\*(C'\fR. |
676 | .Sp |
677 | Setting \f(CW\*(C`module_name\*(C'\fR won't override a \f(CW\*(C`dist_*\*(C'\fR parameter you |
678 | specify explicitly. |
679 | .IP "PL_files" 4 |
680 | .IX Item "PL_files" |
681 | [version 0.06] |
682 | .Sp |
683 | An optional parameter specifying a set of \f(CW\*(C`.PL\*(C'\fR files in your |
684 | distribution. These will be run as Perl scripts prior to processing |
685 | the rest of the files in your distribution with the name of the file |
686 | they're generating as an argument. They are usually used as templates |
687 | for creating other files dynamically, so that a file like |
688 | \&\f(CW\*(C`lib/Foo/Bar.pm.PL\*(C'\fR might create the file \f(CW\*(C`lib/Foo/Bar.pm\*(C'\fR. |
689 | .Sp |
690 | The files are specified with the \f(CW\*(C`.PL\*(C'\fR files as hash keys, and the |
691 | file(s) they generate as hash values, like so: |
692 | .Sp |
693 | .Vb 6 |
694 | \& my $build = Module::Build\->new |
695 | \& ( |
696 | \& module_name => 'Foo::Bar', |
697 | \& ... |
698 | \& PL_files => { 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm' }, |
699 | \& ); |
700 | .Ve |
701 | .Sp |
702 | Note that the path specifications are \fIalways\fR given in Unix-like |
703 | format, not in the style of the local system. |
704 | .Sp |
705 | If your \f(CW\*(C`.PL\*(C'\fR scripts don't create any files, or if they create files |
706 | with unexpected names, or even if they create multiple files, you can |
707 | indicate that so that Module::Build can properly handle these created |
708 | files: |
709 | .Sp |
710 | .Vb 5 |
711 | \& PL_files => { |
712 | \& 'lib/Foo/Bar.pm.PL' => 'lib/Foo/Bar.pm', |
713 | \& 'lib/something.PL' => ['/lib/something', '/lib/else'], |
714 | \& 'lib/funny.PL' => [], |
715 | \& } |
716 | .Ve |
717 | .Sp |
718 | Here's an example of a simple \s-1PL\s0 file. |
719 | .Sp |
720 | .Vb 2 |
721 | \& my $output_file = shift; |
722 | \& open my $fh, ">", $output_file or die "Can't open $output_file: $!"; |
723 | .Ve |
724 | .Sp |
725 | .Vb 2 |
726 | \& print $fh <<'END'; |
727 | \& #!/usr/bin/perl |
728 | .Ve |
729 | .Sp |
730 | .Vb 2 |
731 | \& print "Hello, world!\en"; |
732 | \& END |
733 | .Ve |
734 | .Sp |
735 | \&\s-1PL\s0 files are not installed by default, so its safe to put them in |
736 | \&\fIlib/\fR and \fIbin/\fR. |
737 | .IP "pm_files" 4 |
738 | .IX Item "pm_files" |
739 | [version 0.19] |
740 | .Sp |
741 | An optional parameter specifying the set of \f(CW\*(C`.pm\*(C'\fR files in this |
742 | distribution, specified as a hash reference whose keys are the files' |
743 | locations in the distributions, and whose values are their logical |
744 | locations based on their package name, i.e. where they would be found |
745 | in a \*(L"normal\*(R" Module::Build\-style distribution. This parameter is |
746 | mainly intended to support alternative layouts of files. |
747 | .Sp |
748 | For instance, if you have an old-style \f(CW\*(C`MakeMaker\*(C'\fR distribution for a |
749 | module called \f(CW\*(C`Foo::Bar\*(C'\fR and a \fIBar.pm\fR file at the top level of the |
750 | distribution, you could specify your layout in your \f(CW\*(C`Build.PL\*(C'\fR like |
751 | this: |
752 | .Sp |
753 | .Vb 6 |
754 | \& my $build = Module::Build\->new |
755 | \& ( |
756 | \& module_name => 'Foo::Bar', |
757 | \& ... |
758 | \& pm_files => { 'Bar.pm' => 'lib/Foo/Bar.pm' }, |
759 | \& ); |
760 | .Ve |
761 | .Sp |
762 | Note that the values should include \f(CW\*(C`lib/\*(C'\fR, because this is where |
763 | they would be found in a \*(L"normal\*(R" Module::Build\-style distribution. |
764 | .Sp |
765 | Note also that the path specifications are \fIalways\fR given in |
766 | Unix-like format, not in the style of the local system. |
767 | .IP "pod_files" 4 |
768 | .IX Item "pod_files" |
769 | [version 0.19] |
770 | .Sp |
771 | Just like \f(CW\*(C`pm_files\*(C'\fR, but used for specifying the set of \f(CW\*(C`.pod\*(C'\fR |
772 | files in your distribution. |
773 | .IP "recommends" 4 |
774 | .IX Item "recommends" |
775 | [version 0.08] |
776 | .Sp |
777 | This is just like the \*(L"requires\*(R" argument, except that modules listed |
778 | in this section aren't essential, just a good idea. We'll just print |
779 | a friendly warning if one of these modules aren't found, but we'll |
780 | continue running. |
781 | .Sp |
782 | If a module is recommended but not required, all tests should still |
783 | pass if the module isn't installed. This may mean that some tests |
784 | may be skipped if recommended dependencies aren't present. |
785 | .Sp |
786 | Automated tools like \s-1CPAN\s0.pm should inform the user when recommended |
787 | modules aren't installed, and it should offer to install them if it |
788 | wants to be helpful. |
789 | .Sp |
790 | See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring |
791 | for the details of how requirements can be specified. |
792 | .IP "recursive_test_files" 4 |
793 | .IX Item "recursive_test_files" |
794 | [version 0.28] |
795 | .Sp |
796 | Normally, \f(CW\*(C`Module::Build\*(C'\fR does not search subdirectories when looking |
797 | for tests to run. When this options is set it will search recursively |
798 | in all subdirectories of the standard 't' test directory. |
799 | .IP "requires" 4 |
800 | .IX Item "requires" |
801 | [version 0.07] |
802 | .Sp |
803 | An optional \f(CW\*(C`requires\*(C'\fR argument specifies any module prerequisites |
804 | that the current module depends on. |
805 | .Sp |
806 | One note: currently \f(CW\*(C`Module::Build\*(C'\fR doesn't actually \fIrequire\fR the |
807 | user to have dependencies installed, it just strongly urges. In the |
808 | future we may require it. There's also a \*(L"recommends\*(R" section for |
809 | things that aren't absolutely required. |
810 | .Sp |
811 | Automated tools like \s-1CPAN\s0.pm should refuse to install a module if one |
812 | of its dependencies isn't satisfied, unless a \*(L"force\*(R" command is given |
813 | by the user. If the tools are helpful, they should also offer to |
814 | install the dependencies. |
815 | .Sp |
816 | A synonym for \f(CW\*(C`requires\*(C'\fR is \f(CW\*(C`prereq\*(C'\fR, to help succour people |
817 | transitioning from \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. The \f(CW\*(C`requires\*(C'\fR term is |
818 | preferred, but the \f(CW\*(C`prereq\*(C'\fR term will remain valid in future |
819 | distributions. |
820 | .Sp |
821 | See the documentation for \*(L"\s-1PREREQUISITES\s0\*(R" in Module::Build::Authoring |
822 | for the details of how requirements can be specified. |
823 | .IP "script_files" 4 |
824 | .IX Item "script_files" |
825 | [version 0.18] |
826 | .Sp |
827 | An optional parameter specifying a set of files that should be |
828 | installed as executable Perl scripts when the module is installed. |
829 | May be given as an array reference of the files, as a hash reference |
830 | whose keys are the files (and whose values will currently be ignored), |
831 | as a string giving the name of a directory in which to find scripts, |
832 | or as a string giving the name of a single script file. |
833 | .Sp |
834 | The default is to install any scripts found in a \fIbin\fR directory at |
835 | the top level of the distribution, minus any keys of PL_files. |
836 | .Sp |
837 | For backward compatibility, you may use the parameter \f(CW\*(C`scripts\*(C'\fR |
838 | instead of \f(CW\*(C`script_files\*(C'\fR. Please consider this usage deprecated, |
839 | though it will continue to exist for several version releases. |
840 | .IP "sign" 4 |
841 | .IX Item "sign" |
842 | [version 0.16] |
843 | .Sp |
844 | If a true value is specified for this parameter, Module::Signature |
845 | will be used (via the 'distsign' action) to create a \s-1SIGNATURE\s0 file |
846 | for your distribution during the 'distdir' action, and to add the |
847 | \&\s-1SIGNATURE\s0 file to the \s-1MANIFEST\s0 (therefore, don't add it yourself). |
848 | .Sp |
849 | The default value is false. In the future, the default may change to |
850 | true if you have \f(CW\*(C`Module::Signature\*(C'\fR installed on your system. |
851 | .IP "test_files" 4 |
852 | .IX Item "test_files" |
853 | [version 0.23] |
854 | .Sp |
855 | An optional parameter specifying a set of files that should be used as |
856 | \&\f(CW\*(C`Test::Harness\*(C'\fR\-style regression tests to be run during the \f(CW\*(C`test\*(C'\fR |
857 | action. May be given as an array reference of the files, or as a hash |
858 | reference whose keys are the files (and whose values will currently be |
859 | ignored). If the argument is given as a single string (not in an |
860 | array reference), that string will be treated as a \f(CW\*(C`glob()\*(C'\fR pattern |
861 | specifying the files to use. |
862 | .Sp |
863 | The default is to look for a \fItest.pl\fR script in the top-level |
864 | directory of the distribution, and any files matching the glob pattern |
865 | \&\f(CW\*(C`*.t\*(C'\fR in the \fIt/\fR subdirectory. If the \f(CW\*(C`recursive_test_files\*(C'\fR |
866 | property is true, then the \f(CW\*(C`t/\*(C'\fR directory will be scanned recursively |
867 | for \f(CW\*(C`*.t\*(C'\fR files. |
868 | .IP "use_tap_harness" 4 |
869 | .IX Item "use_tap_harness" |
870 | [version 0.2808_03] |
871 | .Sp |
872 | An optional parameter indicating whether or not to use TAP::Harness for |
873 | testing rather than Test::Harness. Defaults to false. If set to true, you must |
874 | therefore be sure to add TAP::Harness as a requirement for your module in |
875 | \&\*(L"build_requires\*(R". Implicitly set to a true value if \f(CW\*(C`tap_harness_args\*(C'\fR is |
876 | specified. |
877 | .IP "tap_harness_args" 4 |
878 | .IX Item "tap_harness_args" |
879 | [version 0.2808_03] |
880 | .Sp |
881 | An optional parameter specifying parameters to be passed to TAP::Harness when |
882 | running tests. Must be given as a hash reference of parameters; see the |
883 | TAP::Harness documentation for details. Note that specifying |
884 | this parameter will implicitly set \f(CW\*(C`use_tap_harness\*(C'\fR to a true value. You |
885 | must therefore be sure to add TAP::Harness as a requirement for your module in |
886 | \&\*(L"build_requires\*(R". |
887 | .IP "xs_files" 4 |
888 | .IX Item "xs_files" |
889 | [version 0.19] |
890 | .Sp |
891 | Just like \f(CW\*(C`pm_files\*(C'\fR, but used for specifying the set of \f(CW\*(C`.xs\*(C'\fR |
892 | files in your distribution. |
893 | .RE |
894 | .RS 4 |
895 | .RE |
896 | .IP "new_from_context(%args)" 4 |
897 | .IX Item "new_from_context(%args)" |
898 | [version 0.28] |
899 | .Sp |
900 | When called from a directory containing a \fIBuild.PL\fR script and a |
901 | \&\fI\s-1META\s0.yml\fR file (in other words, the base directory of a |
902 | distribution), this method will run the \fIBuild.PL\fR and return the |
903 | resulting \f(CW\*(C`Module::Build\*(C'\fR object to the caller. Any key-value |
904 | arguments given to \f(CW\*(C`new_from_context()\*(C'\fR are essentially like |
905 | command line arguments given to the \fIBuild.PL\fR script, so for example |
906 | you could pass \f(CW\*(C`verbose => 1\*(C'\fR to this method to turn on |
907 | verbosity. |
908 | .IP "\fIresume()\fR" 4 |
909 | .IX Item "resume()" |
910 | [version 0.03] |
911 | .Sp |
912 | You'll probably never call this method directly, it's only called from |
913 | the auto-generated \f(CW\*(C`Build\*(C'\fR script. The \f(CW\*(C`new()\*(C'\fR method is only |
914 | called once, when the user runs \f(CW\*(C`perl Build.PL\*(C'\fR. Thereafter, when |
915 | the user runs \f(CW\*(C`Build test\*(C'\fR or another action, the \f(CW\*(C`Module::Build\*(C'\fR |
916 | object is created using the \f(CW\*(C`resume()\*(C'\fR method to re-instantiate with |
917 | the settings given earlier to \f(CW\*(C`new()\*(C'\fR. |
918 | .IP "\fIsubclass()\fR" 4 |
919 | .IX Item "subclass()" |
920 | [version 0.06] |
921 | .Sp |
922 | This creates a new \f(CW\*(C`Module::Build\*(C'\fR subclass on the fly, as described |
923 | in the \*(L"\s-1SUBCLASSING\s0\*(R" in Module::Build::Authoring section. The caller |
924 | must provide either a \f(CW\*(C`class\*(C'\fR or \f(CW\*(C`code\*(C'\fR parameter, or both. The |
925 | \&\f(CW\*(C`class\*(C'\fR parameter indicates the name to use for the new subclass, and |
926 | defaults to \f(CW\*(C`MyModuleBuilder\*(C'\fR. The \f(CW\*(C`code\*(C'\fR parameter specifies Perl |
927 | code to use as the body of the subclass. |
928 | .IP "add_property" 4 |
929 | .IX Item "add_property" |
930 | [version 0.31] |
931 | .Sp |
932 | .Vb 13 |
933 | \& package 'My::Build'; |
934 | \& use base 'Module::Build'; |
935 | \& __PACKAGE__\->add_property( 'pedantic' ); |
936 | \& __PACKAGE__\->add_property( answer => 42 ); |
937 | \& __PACKAGE__\->add_property( |
938 | \& 'epoch', |
939 | \& default => sub { time }, |
940 | \& check => sub { |
941 | \& return 1 if /^\ed+$/; |
942 | \& shift\->property_error( "'$_' is not an epoch time" ); |
943 | \& return 0; |
944 | \& }, |
945 | \& ); |
946 | .Ve |
947 | .Sp |
948 | Adds a property to a Module::Build class. Properties are those attributes of a |
949 | Module::Build object which can be passed to the constructor and which have |
950 | accessors to get and set them. All of the core properties, such as |
951 | \&\f(CW\*(C`module_name\*(C'\fR and \f(CW\*(C`license\*(C'\fR, are defined using this class method. |
952 | .Sp |
953 | The first argument to \f(CW\*(C`add_property()\*(C'\fR is always the name of the property. |
954 | The second argument can be either a default value for the property, or a list |
955 | of key/value pairs. The supported keys are: |
956 | .RS 4 |
957 | .ie n .IP """default""" 4 |
958 | .el .IP "\f(CWdefault\fR" 4 |
959 | .IX Item "default" |
960 | The default value. May optionally be specified as a code reference, in which |
961 | case the return value from the execution of the code reference will be used. |
962 | If you need the default to be a code reference, just use a code reference to |
963 | return it, e.g.: |
964 | .Sp |
965 | .Vb 1 |
966 | \& default => sub { sub { ... } }, |
967 | .Ve |
968 | .ie n .IP """check""" 4 |
969 | .el .IP "\f(CWcheck\fR" 4 |
970 | .IX Item "check" |
971 | A code reference that checks that a value specified for the property is valid. |
972 | During the execution of the code reference, the new value will be included in |
973 | the \f(CW$_\fR variable. If the value is correct, the \f(CW\*(C`check\*(C'\fR code reference |
974 | should return true. If the value is not correct, it sends an error message to |
975 | \&\f(CW\*(C`property_error()\*(C'\fR and returns false. |
976 | .RE |
977 | .RS 4 |
978 | .Sp |
979 | When this method is called, a new property will be installed in the |
980 | Module::Build class, and an accessor will be built to allow the property to be |
981 | get or set on the build object. |
982 | .Sp |
983 | .Vb 2 |
984 | \& print $build\->pedantic, $/; |
985 | \& $build\->pedantic(0); |
986 | .Ve |
987 | .Sp |
988 | If the default value is a hash reference, this generates a special-case |
989 | accessor method, wherein individual key/value pairs may be set or fetched: |
990 | .Sp |
991 | .Vb 3 |
992 | \& print "stuff{foo} is: ", $build\->stuff( 'foo' ), $/; |
993 | \& $build\->stuff( foo => 'bar' ); |
994 | \& print $build\->stuff( 'foo' ), $/; # Outputs "bar" |
995 | .Ve |
996 | .Sp |
997 | Of course, you can still set the entire hash reference at once, as well: |
998 | .Sp |
999 | .Vb 1 |
1000 | \& $build\->stuff( { foo => 'bar', baz => 'yo' } ); |
1001 | .Ve |
1002 | .Sp |
1003 | In either case, if a \f(CW\*(C`check\*(C'\fR has been specified for the property, it will be |
1004 | applied to the entire hash. So the check code reference should look something |
1005 | like: |
1006 | .Sp |
1007 | .Vb 5 |
1008 | \& check => sub { |
1009 | \& return 1 if defined $_ && exists $_\->{foo}; |
1010 | \& shift\->property_error(qq{Property "stuff" needs "foo"}); |
1011 | \& return 0; |
1012 | \& }, |
1013 | .Ve |
1014 | .RE |
1015 | .IP "property_error" 4 |
1016 | .IX Item "property_error" |
1017 | [version 0.31] |
1018 | .Sh "\s-1METHODS\s0" |
1019 | .IX Subsection "METHODS" |
1020 | .IP "add_build_element($type)" 4 |
1021 | .IX Item "add_build_element($type)" |
1022 | [version 0.26] |
1023 | .Sp |
1024 | Adds a new type of entry to the build process. Accepts a single |
1025 | string specifying its type\-name. There must also be a method defined |
1026 | to process things of that type, e.g. if you add a build element called |
1027 | \&\f(CW'foo'\fR, then you must also define a method called |
1028 | \&\f(CW\*(C`process_foo_files()\*(C'\fR. |
1029 | .Sp |
1030 | See also |
1031 | \&\*(L"Adding new file types to the build process\*(R" in Module::Build::Cookbook. |
1032 | .IP "add_to_cleanup(@files)" 4 |
1033 | .IX Item "add_to_cleanup(@files)" |
1034 | [version 0.03] |
1035 | .Sp |
1036 | You may call \f(CW\*(C`$self\->add_to_cleanup(@patterns)\*(C'\fR to tell |
1037 | \&\f(CW\*(C`Module::Build\*(C'\fR that certain files should be removed when the user |
1038 | performs the \f(CW\*(C`Build clean\*(C'\fR action. The arguments to the method are |
1039 | patterns suitable for passing to Perl's \f(CW\*(C`glob()\*(C'\fR function, specified |
1040 | in either Unix format or the current machine's native format. It's |
1041 | usually convenient to use Unix format when you hard-code the filenames |
1042 | (e.g. in \fIBuild.PL\fR) and the native format when the names are |
1043 | programmatically generated (e.g. in a testing script). |
1044 | .Sp |
1045 | I decided to provide a dynamic method of the \f(CW$build\fR object, rather |
1046 | than just use a static list of files named in the \fIBuild.PL\fR, because |
1047 | these static lists can get difficult to manage. I usually prefer to |
1048 | keep the responsibility for registering temporary files close to the |
1049 | code that creates them. |
1050 | .IP "\fIargs()\fR" 4 |
1051 | .IX Item "args()" |
1052 | [version 0.26] |
1053 | .Sp |
1054 | .Vb 4 |
1055 | \& my $args_href = $build\->args; |
1056 | \& my %args = $build\->args; |
1057 | \& my $arg_value = $build\->args($key); |
1058 | \& $build\->args($key, $value); |
1059 | .Ve |
1060 | .Sp |
1061 | This method is the preferred interface for retrieving the arguments passed via |
1062 | command line options to \fIBuild.PL\fR or \fIBuild\fR, minus the Module-Build |
1063 | specific options. |
1064 | .Sp |
1065 | When called in in a scalar context with no arguments, this method returns a |
1066 | reference to the hash storing all of the arguments; in an array context, it |
1067 | returns the hash itself. When passed a single argument, it returns the value |
1068 | stored in the args hash for that option key. When called with two arguments, |
1069 | the second argument is assigned to the args hash under the key passed as the |
1070 | first argument. |
1071 | .ie n .IP "autosplit_file($from, $to)" 4 |
1072 | .el .IP "autosplit_file($from, \f(CW$to\fR)" 4 |
1073 | .IX Item "autosplit_file($from, $to)" |
1074 | [version 0.28] |
1075 | .Sp |
1076 | Invokes the AutoSplit module on the \f(CW$from\fR file, sending the |
1077 | output to the \f(CW\*(C`lib/auto\*(C'\fR directory inside \f(CW$to\fR. \f(CW$to\fR is |
1078 | typically the \f(CW\*(C`blib/\*(C'\fR directory. |
1079 | .IP "\fIbase_dir()\fR" 4 |
1080 | .IX Item "base_dir()" |
1081 | [version 0.14] |
1082 | .Sp |
1083 | Returns a string containing the root-level directory of this build, |
1084 | i.e. where the \f(CW\*(C`Build.PL\*(C'\fR script and the \f(CW\*(C`lib\*(C'\fR directory can be |
1085 | found. This is usually the same as the current working directory, |
1086 | because the \f(CW\*(C`Build\*(C'\fR script will \f(CW\*(C`chdir()\*(C'\fR into this directory as |
1087 | soon as it begins execution. |
1088 | .IP "\fIbuild_requires()\fR" 4 |
1089 | .IX Item "build_requires()" |
1090 | [version 0.21] |
1091 | .Sp |
1092 | Returns a hash reference indicating the \f(CW\*(C`build_requires\*(C'\fR |
1093 | prerequisites that were passed to the \f(CW\*(C`new()\*(C'\fR method. |
1094 | .ie n .IP "can_action( $action )" 4 |
1095 | .el .IP "can_action( \f(CW$action\fR )" 4 |
1096 | .IX Item "can_action( $action )" |
1097 | Returns a reference to the method that defines \f(CW$action\fR, or false |
1098 | otherwise. This is handy for actions defined (or maybe not!) in subclasses. |
1099 | .Sp |
1100 | [version 0.32_xx] |
1101 | .IP "\fIcbuilder()\fR" 4 |
1102 | .IX Item "cbuilder()" |
1103 | [version 0.2809] |
1104 | .Sp |
1105 | Returns the internal ExtUtils::CBuilder object that can be used for |
1106 | compiling & linking C code. If no such object is available (e.g. if |
1107 | the system has no compiler installed) an exception will be thrown. |
1108 | .ie n .IP "check_installed_status($module, $version)" 4 |
1109 | .el .IP "check_installed_status($module, \f(CW$version\fR)" 4 |
1110 | .IX Item "check_installed_status($module, $version)" |
1111 | [version 0.11] |
1112 | .Sp |
1113 | This method returns a hash reference indicating whether a version |
1114 | dependency on a certain module is satisfied. The \f(CW$module\fR argument |
1115 | is given as a string like \f(CW"Data::Dumper"\fR or \f(CW"perl"\fR, and the |
1116 | \&\f(CW$version\fR argument can take any of the forms described in \*(L"requires\*(R" |
1117 | above. This allows very fine-grained version checking. |
1118 | .Sp |
1119 | The returned hash reference has the following structure: |
1120 | .Sp |
1121 | .Vb 6 |
1122 | \& { |
1123 | \& ok => $whether_the_dependency_is_satisfied, |
1124 | \& have => $version_already_installed, |
1125 | \& need => $version_requested, # Same as incoming $version argument |
1126 | \& message => $informative_error_message, |
1127 | \& } |
1128 | .Ve |
1129 | .Sp |
1130 | If no version of \f(CW$module\fR is currently installed, the \f(CW\*(C`have\*(C'\fR value |
1131 | will be the string \f(CW"<none>"\fR. Otherwise the \f(CW\*(C`have\*(C'\fR value will |
1132 | simply be the version of the installed module. Note that this means |
1133 | that if \f(CW$module\fR is installed but doesn't define a version number, |
1134 | the \f(CW\*(C`have\*(C'\fR value will be \f(CW\*(C`undef\*(C'\fR \- this is why we don't use \f(CW\*(C`undef\*(C'\fR |
1135 | for the case when \f(CW$module\fR isn't installed at all. |
1136 | .Sp |
1137 | This method may be called either as an object method |
1138 | (\f(CW\*(C`$build\->check_installed_status($module, $version)\*(C'\fR) |
1139 | or as a class method |
1140 | (\f(CW\*(C`Module::Build\->check_installed_status($module, $version)\*(C'\fR). |
1141 | .ie n .IP "check_installed_version($module, $version)" 4 |
1142 | .el .IP "check_installed_version($module, \f(CW$version\fR)" 4 |
1143 | .IX Item "check_installed_version($module, $version)" |
1144 | [version 0.05] |
1145 | .Sp |
1146 | Like \fIcheck_installed_status()\fR, |
1147 | but simply returns true or false depending on whether module |
1148 | \&\f(CW$module\fR satisfies the dependency \f(CW$version\fR. |
1149 | .Sp |
1150 | If the check succeeds, the return value is the actual version of |
1151 | \&\f(CW$module\fR installed on the system. This allows you to do the |
1152 | following: |
1153 | .Sp |
1154 | .Vb 6 |
1155 | \& my $installed = $build\->check_installed_version('DBI', '1.15'); |
1156 | \& if ($installed) { |
1157 | \& print "Congratulations, version $installed of DBI is installed.\en"; |
1158 | \& } else { |
1159 | \& die "Sorry, you must install DBI.\en"; |
1160 | \& } |
1161 | .Ve |
1162 | .Sp |
1163 | If the check fails, we return false and set \f(CW$@\fR to an informative |
1164 | error message. |
1165 | .Sp |
1166 | If \f(CW$version\fR is any non-true value (notably zero) and any version of |
1167 | \&\f(CW$module\fR is installed, we return true. In this case, if \f(CW$module\fR |
1168 | doesn't define a version, or if its version is zero, we return the |
1169 | special value \*(L"0 but true\*(R", which is numerically zero, but logically |
1170 | true. |
1171 | .Sp |
1172 | In general you might prefer to use \f(CW\*(C`check_installed_status\*(C'\fR if you |
1173 | need detailed information, or this method if you just need a yes/no |
1174 | answer. |
1175 | .ie n .IP "compare_versions($v1, $op\fR, \f(CW$v2)" 4 |
1176 | .el .IP "compare_versions($v1, \f(CW$op\fR, \f(CW$v2\fR)" 4 |
1177 | .IX Item "compare_versions($v1, $op, $v2)" |
1178 | [version 0.28] |
1179 | .Sp |
1180 | Compares two module versions \f(CW$v1\fR and \f(CW$v2\fR using the operator |
1181 | \&\f(CW$op\fR, which should be one of Perl's numeric operators like \f(CW\*(C`!=\*(C'\fR or |
1182 | \&\f(CW\*(C`>=\*(C'\fR or the like. We do at least a halfway-decent job of |
1183 | handling versions that aren't strictly numeric, like \f(CW\*(C`0.27_02\*(C'\fR, but |
1184 | exotic stuff will likely cause problems. |
1185 | .Sp |
1186 | In the future, the guts of this method might be replaced with a call |
1187 | out to \f(CW\*(C`version.pm\*(C'\fR. |
1188 | .IP "config($key)" 4 |
1189 | .IX Item "config($key)" |
1190 | .PD 0 |
1191 | .ie n .IP "config($key, $value)" 4 |
1192 | .el .IP "config($key, \f(CW$value\fR)" 4 |
1193 | .IX Item "config($key, $value)" |
1194 | .IP "\fIconfig()\fR [deprecated]" 4 |
1195 | .IX Item "config() [deprecated]" |
1196 | .PD |
1197 | [version 0.22] |
1198 | .Sp |
1199 | With a single argument \f(CW$key\fR, returns the value associated with that |
1200 | key in the \f(CW\*(C`Config.pm\*(C'\fR hash, including any changes the author or user |
1201 | has specified. |
1202 | .Sp |
1203 | With \f(CW$key\fR and \f(CW$value\fR arguments, sets the value for future |
1204 | callers of \f(CW\*(C`config($key)\*(C'\fR. |
1205 | .Sp |
1206 | With no arguments, returns a hash reference containing all such |
1207 | key-value pairs. This usage is deprecated, though, because it's a |
1208 | resource hog and violates encapsulation. |
1209 | .IP "config_data($name)" 4 |
1210 | .IX Item "config_data($name)" |
1211 | .PD 0 |
1212 | .ie n .IP "config_data($name => $value)" 4 |
1213 | .el .IP "config_data($name => \f(CW$value\fR)" 4 |
1214 | .IX Item "config_data($name => $value)" |
1215 | .PD |
1216 | [version 0.26] |
1217 | .Sp |
1218 | With a single argument, returns the value of the configuration |
1219 | variable \f(CW$name\fR. With two arguments, sets the given configuration |
1220 | variable to the given value. The value may be any Perl scalar that's |
1221 | serializable with \f(CW\*(C`Data::Dumper\*(C'\fR. For instance, if you write a |
1222 | module that can use a MySQL or PostgreSQL back\-end, you might create |
1223 | configuration variables called \f(CW\*(C`mysql_connect\*(C'\fR and |
1224 | \&\f(CW\*(C`postgres_connect\*(C'\fR, and set each to an array of connection parameters |
1225 | for \f(CW\*(C`DBI\->connect()\*(C'\fR. |
1226 | .Sp |
1227 | Configuration values set in this way using the Module::Build object |
1228 | will be available for querying during the build/test process and after |
1229 | installation via the generated \f(CW\*(C`...::ConfigData\*(C'\fR module, as |
1230 | \&\f(CW\*(C`...::ConfigData\->config($name)\*(C'\fR. |
1231 | .Sp |
1232 | The \fIfeature()\fR and \f(CW\*(C`config_data()\*(C'\fR methods represent |
1233 | Module::Build's main support for configuration of installed modules. |
1234 | See also \*(L"\s-1SAVING\s0 \s-1CONFIGURATION\s0 \s-1INFORMATION\s0\*(R" in Module::Build::Authoring. |
1235 | .IP "\fIconflicts()\fR" 4 |
1236 | .IX Item "conflicts()" |
1237 | [version 0.21] |
1238 | .Sp |
1239 | Returns a hash reference indicating the \f(CW\*(C`conflicts\*(C'\fR prerequisites |
1240 | that were passed to the \f(CW\*(C`new()\*(C'\fR method. |
1241 | .IP "contains_pod($file)" 4 |
1242 | .IX Item "contains_pod($file)" |
1243 | [version 0.20] |
1244 | .Sp |
1245 | [Deprecated] Please see Module::Build::ModuleInfo instead. |
1246 | .Sp |
1247 | Returns true if the given file appears to contain \s-1POD\s0 documentation. |
1248 | Currently this checks whether the file has a line beginning with |
1249 | \&'=pod', '=head', or '=item', but the exact semantics may change in the |
1250 | future. |
1251 | .IP "copy_if_modified(%parameters)" 4 |
1252 | .IX Item "copy_if_modified(%parameters)" |
1253 | [version 0.19] |
1254 | .Sp |
1255 | Takes the file in the \f(CW\*(C`from\*(C'\fR parameter and copies it to the file in |
1256 | the \f(CW\*(C`to\*(C'\fR parameter, or the directory in the \f(CW\*(C`to_dir\*(C'\fR parameter, if |
1257 | the file has changed since it was last copied (or if it doesn't exist |
1258 | in the new location). By default the entire directory structure of |
1259 | \&\f(CW\*(C`from\*(C'\fR will be copied into \f(CW\*(C`to_dir\*(C'\fR; an optional \f(CW\*(C`flatten\*(C'\fR |
1260 | parameter will copy into \f(CW\*(C`to_dir\*(C'\fR without doing so. |
1261 | .Sp |
1262 | Returns the path to the destination file, or \f(CW\*(C`undef\*(C'\fR if nothing |
1263 | needed to be copied. |
1264 | .Sp |
1265 | Any directories that need to be created in order to perform the |
1266 | copying will be automatically created. |
1267 | .Sp |
1268 | The destination file is set to read\-only. If the source file has the |
1269 | executable bit set, then the destination file will be made executable. |
1270 | .IP "\fIcreate_build_script()\fR" 4 |
1271 | .IX Item "create_build_script()" |
1272 | [version 0.05] |
1273 | .Sp |
1274 | Creates an executable script called \f(CW\*(C`Build\*(C'\fR in the current directory |
1275 | that will be used to execute further user actions. This script is |
1276 | roughly analogous (in function, not in form) to the Makefile created |
1277 | by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. This method also creates some temporary |
1278 | data in a directory called \f(CW\*(C`_build/\*(C'\fR. Both of these will be removed |
1279 | when the \f(CW\*(C`realclean\*(C'\fR action is performed. |
1280 | .Sp |
1281 | Among the files created in \f(CW\*(C`_build/\*(C'\fR is a \fI_build/prereqs\fR file |
1282 | containing the set of prerequisites for this distribution, as a hash |
1283 | of hashes. This file may be \f(CW\*(C`eval()\*(C'\fR\-ed to obtain the authoritative |
1284 | set of prerequisites, which might be different from the contents of |
1285 | \&\fI\s-1META\s0.yml\fR (because \fIBuild.PL\fR might have set them dynamically). |
1286 | But fancy developers take heed: do not put any fancy custom runtime |
1287 | code in the \fI_build/prereqs\fR file, leave it as a static declaration |
1288 | containing only strings and numbers. Similarly, do not alter the |
1289 | structure of the internal \f(CW\*(C`$self\->{properties}{requires}\*(C'\fR (etc.) |
1290 | data members, because that's where this data comes from. |
1291 | .IP "\fIcurrent_action()\fR" 4 |
1292 | .IX Item "current_action()" |
1293 | [version 0.28] |
1294 | .Sp |
1295 | Returns the name of the currently-running action, such as \*(L"build\*(R" or |
1296 | \&\*(L"test\*(R". This action is not necessarily the action that was originally |
1297 | invoked by the user. For example, if the user invoked the \*(L"test\*(R" |
1298 | action, \fIcurrent_action()\fR would initially return \*(L"test\*(R". However, |
1299 | action \*(L"test\*(R" depends on action \*(L"code\*(R", so \fIcurrent_action()\fR will |
1300 | return \*(L"code\*(R" while that dependency is being executed. Once that |
1301 | action has completed, \fIcurrent_action()\fR will again return \*(L"test\*(R". |
1302 | .Sp |
1303 | If you need to know the name of the original action invoked by the |
1304 | user, see \*(L"\fIinvoked_action()\fR\*(R" below. |
1305 | .IP "depends_on(@actions)" 4 |
1306 | .IX Item "depends_on(@actions)" |
1307 | [version 0.28] |
1308 | .Sp |
1309 | Invokes the named action or list of actions in sequence. Using this |
1310 | method is preferred to calling the action explicitly because it |
1311 | performs some internal record\-keeping, and it ensures that the same |
1312 | action is not invoked multiple times (note: in future versions of |
1313 | Module::Build it's conceivable that this run-only-once mechanism will |
1314 | be changed to something more intelligent). |
1315 | .Sp |
1316 | Note that the name of this method is something of a misnomer; it |
1317 | should really be called something like |
1318 | \&\f(CW\*(C`invoke_actions_unless_already_invoked()\*(C'\fR or something, but for |
1319 | better or worse (perhaps better!) we were still thinking in |
1320 | \&\f(CW\*(C`make\*(C'\fR\-like dependency terms when we created this method. |
1321 | .Sp |
1322 | See also \fIdispatch()\fR. The main |
1323 | distinction between the two is that \f(CW\*(C`depends_on()\*(C'\fR is meant to call |
1324 | an action from inside another action, whereas \f(CW\*(C`dispatch()\*(C'\fR is meant |
1325 | to set the very top action in motion. |
1326 | .ie n .IP "dir_contains($first_dir, $second_dir)" 4 |
1327 | .el .IP "dir_contains($first_dir, \f(CW$second_dir\fR)" 4 |
1328 | .IX Item "dir_contains($first_dir, $second_dir)" |
1329 | [version 0.28] |
1330 | .Sp |
1331 | Returns true if the first directory logically contains the second |
1332 | directory. This is just a convenience function because \f(CW\*(C`File::Spec\*(C'\fR |
1333 | doesn't really provide an easy way to figure this out (but |
1334 | \&\f(CW\*(C`Path::Class\*(C'\fR does...). |
1335 | .ie n .IP "dispatch($action, %args)" 4 |
1336 | .el .IP "dispatch($action, \f(CW%args\fR)" 4 |
1337 | .IX Item "dispatch($action, %args)" |
1338 | [version 0.03] |
1339 | .Sp |
1340 | Invokes the build action \f(CW$action\fR. Optionally, a list of options |
1341 | and their values can be passed in. This is equivalent to invoking an |
1342 | action at the command line, passing in a list of options. |
1343 | .Sp |
1344 | Custom options that have not been registered must be passed in as a |
1345 | hash reference in a key named \*(L"args\*(R": |
1346 | .Sp |
1347 | .Vb 1 |
1348 | \& $build\->dispatch('foo', verbose => 1, args => { my_option => 'value' }); |
1349 | .Ve |
1350 | .Sp |
1351 | This method is intended to be used to programmatically invoke build |
1352 | actions, e.g. by applications controlling Module::Build\-based builds |
1353 | rather than by subclasses. |
1354 | .Sp |
1355 | See also \fIdepends_on()\fR. The main |
1356 | distinction between the two is that \f(CW\*(C`depends_on()\*(C'\fR is meant to call |
1357 | an action from inside another action, whereas \f(CW\*(C`dispatch()\*(C'\fR is meant |
1358 | to set the very top action in motion. |
1359 | .IP "\fIdist_dir()\fR" 4 |
1360 | .IX Item "dist_dir()" |
1361 | [version 0.28] |
1362 | .Sp |
1363 | Returns the name of the directory that will be created during the |
1364 | \&\f(CW\*(C`dist\*(C'\fR action. The name is derived from the \f(CW\*(C`dist_name\*(C'\fR and |
1365 | \&\f(CW\*(C`dist_version\*(C'\fR properties. |
1366 | .IP "\fIdist_name()\fR" 4 |
1367 | .IX Item "dist_name()" |
1368 | [version 0.21] |
1369 | .Sp |
1370 | Returns the name of the current distribution, as passed to the |
1371 | \&\f(CW\*(C`new()\*(C'\fR method in a \f(CW\*(C`dist_name\*(C'\fR or modified \f(CW\*(C`module_name\*(C'\fR |
1372 | parameter. |
1373 | .IP "\fIdist_version()\fR" 4 |
1374 | .IX Item "dist_version()" |
1375 | [version 0.21] |
1376 | .Sp |
1377 | Returns the version of the current distribution, as determined by the |
1378 | \&\f(CW\*(C`new()\*(C'\fR method from a \f(CW\*(C`dist_version\*(C'\fR, \f(CW\*(C`dist_version_from\*(C'\fR, or |
1379 | \&\f(CW\*(C`module_name\*(C'\fR parameter. |
1380 | .ie n .IP "do_system($cmd, @args)" 4 |
1381 | .el .IP "do_system($cmd, \f(CW@args\fR)" 4 |
1382 | .IX Item "do_system($cmd, @args)" |
1383 | [version 0.21] |
1384 | .Sp |
1385 | This is a fairly simple wrapper around Perl's \f(CW\*(C`system()\*(C'\fR built-in |
1386 | command. Given a command and an array of optional arguments, this |
1387 | method will print the command to \f(CW\*(C`STDOUT\*(C'\fR, and then execute it using |
1388 | Perl's \f(CW\*(C`system()\*(C'\fR. It returns true or false to indicate success or |
1389 | failure (the opposite of how \f(CW\*(C`system()\*(C'\fR works, but more intuitive). |
1390 | .Sp |
1391 | Note that if you supply a single argument to \f(CW\*(C`do_system()\*(C'\fR, it |
1392 | will/may be processed by the system's shell, and any special |
1393 | characters will do their special things. If you supply multiple |
1394 | arguments, no shell will get involved and the command will be executed |
1395 | directly. |
1396 | .IP "feature($name)" 4 |
1397 | .IX Item "feature($name)" |
1398 | .PD 0 |
1399 | .ie n .IP "feature($name => $value)" 4 |
1400 | .el .IP "feature($name => \f(CW$value\fR)" 4 |
1401 | .IX Item "feature($name => $value)" |
1402 | .PD |
1403 | [version 0.26] |
1404 | .Sp |
1405 | With a single argument, returns true if the given feature is set. |
1406 | With two arguments, sets the given feature to the given boolean value. |
1407 | In this context, a \*(L"feature\*(R" is any optional functionality of an |
1408 | installed module. For instance, if you write a module that could |
1409 | optionally support a MySQL or PostgreSQL backend, you might create |
1410 | features called \f(CW\*(C`mysql_support\*(C'\fR and \f(CW\*(C`postgres_support\*(C'\fR, and set them |
1411 | to true/false depending on whether the user has the proper databases |
1412 | installed and configured. |
1413 | .Sp |
1414 | Features set in this way using the Module::Build object will be |
1415 | available for querying during the build/test process and after |
1416 | installation via the generated \f(CW\*(C`...::ConfigData\*(C'\fR module, as |
1417 | \&\f(CW\*(C`...::ConfigData\->feature($name)\*(C'\fR. |
1418 | .Sp |
1419 | The \f(CW\*(C`feature()\*(C'\fR and \f(CW\*(C`config_data()\*(C'\fR methods represent |
1420 | Module::Build's main support for configuration of installed modules. |
1421 | See also \*(L"\s-1SAVING\s0 \s-1CONFIGURATION\s0 \s-1INFORMATION\s0\*(R" in Module::Build::Authoring. |
1422 | .IP "fix_shebang_line(@files)" 4 |
1423 | .IX Item "fix_shebang_line(@files)" |
1424 | [version 0.??] |
1425 | .Sp |
1426 | Modify any \*(L"shebang\*(R" line in the specified files to use the path to the |
1427 | perl executable being used for the current build. Files are modified |
1428 | in\-place. The existing shebang line must have a command that contains |
1429 | "\f(CW\*(C`perl\*(C'\fR"; arguments to the command do not count. In particular, this |
1430 | means that the use of \f(CW\*(C`#!/usr/bin/env perl\*(C'\fR will not be changed. |
1431 | .Sp |
1432 | For an explanation of shebang lines, see |
1433 | <http://en.wikipedia.org/wiki/Shebang_%28Unix%29>. |
1434 | .IP "\fIhave_c_compiler()\fR" 4 |
1435 | .IX Item "have_c_compiler()" |
1436 | [version 0.21] |
1437 | .Sp |
1438 | Returns true if the current system seems to have a working C compiler. |
1439 | We currently determine this by attempting to compile a simple C source |
1440 | file and reporting whether the attempt was successful. |
1441 | .IP "\fIinstall_base_relpaths()\fR" 4 |
1442 | .IX Item "install_base_relpaths()" |
1443 | .PD 0 |
1444 | .IP "install_base_relpaths($type)" 4 |
1445 | .IX Item "install_base_relpaths($type)" |
1446 | .ie n .IP "install_base_relpaths($type => $path)" 4 |
1447 | .el .IP "install_base_relpaths($type => \f(CW$path\fR)" 4 |
1448 | .IX Item "install_base_relpaths($type => $path)" |
1449 | .PD |
1450 | [version 0.28] |
1451 | .Sp |
1452 | Set or retrieve the relative paths that are appended to |
1453 | \&\f(CW\*(C`install_base\*(C'\fR for any installable element. This is useful if you |
1454 | want to set the relative install path for custom build elements. |
1455 | .Sp |
1456 | With no argument, it returns a reference to a hash containing all |
1457 | elements and their respective values. This hash should not be modified |
1458 | directly; use the multiple argument below form to change values. |
1459 | .Sp |
1460 | The single argument form returns the value associated with the |
1461 | element \f(CW$type\fR. |
1462 | .Sp |
1463 | The multiple argument form allows you to set the paths for element types. |
1464 | \&\f(CW$value\fR must be a relative path using Unix-like paths. (A series of |
1465 | directories separated by slashes, e.g. \f(CW\*(C`foo/bar\*(C'\fR.) The return value is a |
1466 | localized path based on \f(CW$value\fR. |
1467 | .Sp |
1468 | Assigning the value \f(CW\*(C`undef\*(C'\fR to an element causes it to be removed. |
1469 | .IP "install_destination($type)" 4 |
1470 | .IX Item "install_destination($type)" |
1471 | [version 0.28] |
1472 | .Sp |
1473 | Returns the directory in which items of type \f(CW$type\fR (e.g. \f(CW\*(C`lib\*(C'\fR, |
1474 | \&\f(CW\*(C`arch\*(C'\fR, \f(CW\*(C`bin\*(C'\fR, or anything else returned by the \*(L"\fIinstall_types()\fR\*(R" |
1475 | method) will be installed during the \f(CW\*(C`install\*(C'\fR action. Any settings |
1476 | for \f(CW\*(C`install_path\*(C'\fR, \f(CW\*(C`install_base\*(C'\fR, and \f(CW\*(C`prefix\*(C'\fR are taken into |
1477 | account when determining the return value. |
1478 | .IP "\fIinstall_path()\fR" 4 |
1479 | .IX Item "install_path()" |
1480 | .PD 0 |
1481 | .IP "install_path($type)" 4 |
1482 | .IX Item "install_path($type)" |
1483 | .ie n .IP "install_path($type => $path)" 4 |
1484 | .el .IP "install_path($type => \f(CW$path\fR)" 4 |
1485 | .IX Item "install_path($type => $path)" |
1486 | .PD |
1487 | [version 0.28] |
1488 | .Sp |
1489 | Set or retrieve paths for specific installable elements. This is |
1490 | useful when you want to examine any explicit install paths specified |
1491 | by the user on the command line, or if you want to set the install |
1492 | path for a specific installable element based on another attribute |
1493 | like \f(CW\*(C`install_base()\*(C'\fR. |
1494 | .Sp |
1495 | With no argument, it returns a reference to a hash containing all |
1496 | elements and their respective values. This hash should not be modified |
1497 | directly; use the multiple argument below form to change values. |
1498 | .Sp |
1499 | The single argument form returns the value associated with the |
1500 | element \f(CW$type\fR. |
1501 | .Sp |
1502 | The multiple argument form allows you to set the paths for element types. |
1503 | The supplied \f(CW$path\fR should be an absolute path to install elements |
1504 | of \f(CW$type\fR. The return value is \f(CW$path\fR. |
1505 | .Sp |
1506 | Assigning the value \f(CW\*(C`undef\*(C'\fR to an element causes it to be removed. |
1507 | .IP "\fIinstall_types()\fR" 4 |
1508 | .IX Item "install_types()" |
1509 | [version 0.28] |
1510 | .Sp |
1511 | Returns a list of installable types that this build knows about. |
1512 | These types each correspond to the name of a directory in \fIblib/\fR, |
1513 | and the list usually includes items such as \f(CW\*(C`lib\*(C'\fR, \f(CW\*(C`arch\*(C'\fR, \f(CW\*(C`bin\*(C'\fR, |
1514 | \&\f(CW\*(C`script\*(C'\fR, \f(CW\*(C`libdoc\*(C'\fR, \f(CW\*(C`bindoc\*(C'\fR, and if \s-1HTML\s0 documentation is to be |
1515 | built, \f(CW\*(C`libhtml\*(C'\fR and \f(CW\*(C`binhtml\*(C'\fR. Other user-defined types may also |
1516 | exist. |
1517 | .IP "\fIinvoked_action()\fR" 4 |
1518 | .IX Item "invoked_action()" |
1519 | [version 0.28] |
1520 | .Sp |
1521 | This is the name of the original action invoked by the user. This |
1522 | value is set when the user invokes \fIBuild.PL\fR, the \fIBuild\fR script, |
1523 | or programmatically through the \fIdispatch()\fR |
1524 | method. It does not change as sub-actions are executed as |
1525 | dependencies are evaluated. |
1526 | .Sp |
1527 | To get the name of the currently executing dependency, see |
1528 | \&\*(L"\fIcurrent_action()\fR\*(R" above. |
1529 | .IP "\fInotes()\fR" 4 |
1530 | .IX Item "notes()" |
1531 | .PD 0 |
1532 | .IP "notes($key)" 4 |
1533 | .IX Item "notes($key)" |
1534 | .ie n .IP "notes($key => $value)" 4 |
1535 | .el .IP "notes($key => \f(CW$value\fR)" 4 |
1536 | .IX Item "notes($key => $value)" |
1537 | .PD |
1538 | [version 0.20] |
1539 | .Sp |
1540 | The \f(CW\*(C`notes()\*(C'\fR value allows you to store your own persistent |
1541 | information about the build, and to share that information among |
1542 | different entities involved in the build. See the example in the |
1543 | \&\f(CW\*(C`current()\*(C'\fR method. |
1544 | .Sp |
1545 | The \f(CW\*(C`notes()\*(C'\fR method is essentially a glorified hash access. With no |
1546 | arguments, \f(CW\*(C`notes()\*(C'\fR returns the entire hash of notes. With one argument, |
1547 | \&\f(CW\*(C`notes($key)\*(C'\fR returns the value associated with the given key. With two |
1548 | arguments, \f(CW\*(C`notes($key, $value)\*(C'\fR sets the value associated with the given key |
1549 | to \f(CW$value\fR and returns the new value. |
1550 | .Sp |
1551 | The lifetime of the \f(CW\*(C`notes\*(C'\fR data is for \*(L"a build\*(R" \- that is, the |
1552 | \&\f(CW\*(C`notes\*(C'\fR hash is created when \f(CW\*(C`perl Build.PL\*(C'\fR is run (or when the |
1553 | \&\f(CW\*(C`new()\*(C'\fR method is run, if the Module::Build Perl \s-1API\s0 is being used |
1554 | instead of called from a shell), and lasts until \f(CW\*(C`perl Build.PL\*(C'\fR is |
1555 | run again or the \f(CW\*(C`clean\*(C'\fR action is run. |
1556 | .IP "\fIorig_dir()\fR" 4 |
1557 | .IX Item "orig_dir()" |
1558 | [version 0.28] |
1559 | .Sp |
1560 | Returns a string containing the working directory that was in effect |
1561 | before the \fIBuild\fR script \fIchdir()\fR\-ed into the \f(CW\*(C`base_dir\*(C'\fR. This |
1562 | might be useful for writing wrapper tools that might need to \fIchdir()\fR |
1563 | back out. |
1564 | .IP "\fIos_type()\fR" 4 |
1565 | .IX Item "os_type()" |
1566 | [version 0.04] |
1567 | .Sp |
1568 | If you're subclassing Module::Build and some code needs to alter its |
1569 | behavior based on the current platform, you may only need to know |
1570 | whether you're running on Windows, Unix, MacOS, \s-1VMS\s0, etc., and not the |
1571 | fine-grained value of Perl's \f(CW$^O\fR variable. The \f(CW\*(C`os_type()\*(C'\fR method |
1572 | will return a string like \f(CW\*(C`Windows\*(C'\fR, \f(CW\*(C`Unix\*(C'\fR, \f(CW\*(C`MacOS\*(C'\fR, \f(CW\*(C`VMS\*(C'\fR, or |
1573 | whatever is appropriate. If you're running on an unknown platform, it |
1574 | will return \f(CW\*(C`undef\*(C'\fR \- there shouldn't be many unknown platforms |
1575 | though. |
1576 | .IP "\fIis_vmsish()\fR" 4 |
1577 | .IX Item "is_vmsish()" |
1578 | .PD 0 |
1579 | .IP "\fIis_windowsish()\fR" 4 |
1580 | .IX Item "is_windowsish()" |
1581 | .IP "\fIis_unixish()\fR" 4 |
1582 | .IX Item "is_unixish()" |
1583 | .PD |
1584 | Convenience functions that return a boolean value indicating whether |
1585 | this platform behaves respectively like \s-1VMS\s0, Windows, or Unix. For |
1586 | arbitrary reasons other platforms don't get their own such functions, |
1587 | at least not yet. |
1588 | .IP "\fIprefix_relpaths()\fR" 4 |
1589 | .IX Item "prefix_relpaths()" |
1590 | .PD 0 |
1591 | .IP "prefix_relpaths($installdirs)" 4 |
1592 | .IX Item "prefix_relpaths($installdirs)" |
1593 | .ie n .IP "prefix_relpaths($installdirs, $type)" 4 |
1594 | .el .IP "prefix_relpaths($installdirs, \f(CW$type\fR)" 4 |
1595 | .IX Item "prefix_relpaths($installdirs, $type)" |
1596 | .ie n .IP "prefix_relpaths($installdirs, $type\fR => \f(CW$path)" 4 |
1597 | .el .IP "prefix_relpaths($installdirs, \f(CW$type\fR => \f(CW$path\fR)" 4 |
1598 | .IX Item "prefix_relpaths($installdirs, $type => $path)" |
1599 | .PD |
1600 | [version 0.28] |
1601 | .Sp |
1602 | Set or retrieve the relative paths that are appended to \f(CW\*(C`prefix\*(C'\fR for |
1603 | any installable element. This is useful if you want to set the |
1604 | relative install path for custom build elements. |
1605 | .Sp |
1606 | With no argument, it returns a reference to a hash containing all |
1607 | elements and their respective values as defined by the current |
1608 | \&\f(CW\*(C`installdirs\*(C'\fR setting. |
1609 | .Sp |
1610 | With a single argument, it returns a reference to a hash containing |
1611 | all elements and their respective values as defined by |
1612 | \&\f(CW$installdirs\fR. |
1613 | .Sp |
1614 | The hash returned by the above calls should not be modified directly; |
1615 | use the three-argument below form to change values. |
1616 | .Sp |
1617 | The two argument form returns the value associated with the |
1618 | element \f(CW$type\fR. |
1619 | .Sp |
1620 | The multiple argument form allows you to set the paths for element types. |
1621 | \&\f(CW$value\fR must be a relative path using Unix-like paths. (A series of |
1622 | directories separated by slashes, e.g. \f(CW\*(C`foo/bar\*(C'\fR.) The return value is a |
1623 | localized path based on \f(CW$value\fR. |
1624 | .Sp |
1625 | Assigning the value \f(CW\*(C`undef\*(C'\fR to an element causes it to be removed. |
1626 | .IP "\fIprepare_metadata()\fR" 4 |
1627 | .IX Item "prepare_metadata()" |
1628 | [version 0.28] |
1629 | .Sp |
1630 | This method is provided for authors to override to customize the |
1631 | fields of \fI\s-1META\s0.yml\fR. It is passed a YAML::Node node object which can |
1632 | be modified as desired and then returned. E.g. |
1633 | .Sp |
1634 | .Vb 2 |
1635 | \& package My::Builder; |
1636 | \& use base 'Module::Build'; |
1637 | .Ve |
1638 | .Sp |
1639 | .Vb 6 |
1640 | \& sub prepare_metadata { |
1641 | \& my $self = shift; |
1642 | \& my $node = $self\->SUPER::prepare_metadata( shift ); |
1643 | \& $node\->{custom_field} = 'foo'; |
1644 | \& return $node; |
1645 | \& } |
1646 | .Ve |
1647 | .IP "\fIprereq_failures()\fR" 4 |
1648 | .IX Item "prereq_failures()" |
1649 | [version 0.11] |
1650 | .Sp |
1651 | Returns a data structure containing information about any failed |
1652 | prerequisites (of any of the types described above), or \f(CW\*(C`undef\*(C'\fR if |
1653 | all prerequisites are met. |
1654 | .Sp |
1655 | The data structure returned is a hash reference. The top level keys |
1656 | are the type of prerequisite failed, one of \*(L"requires\*(R", |
1657 | \&\*(L"build_requires\*(R", \*(L"conflicts\*(R", or \*(L"recommends\*(R". The associated values |
1658 | are hash references whose keys are the names of required (or |
1659 | conflicting) modules. The associated values of those are hash |
1660 | references indicating some information about the failure. For example: |
1661 | .Sp |
1662 | .Vb 5 |
1663 | \& { |
1664 | \& have => '0.42', |
1665 | \& need => '0.59', |
1666 | \& message => 'Version 0.42 is installed, but we need version 0.59', |
1667 | \& } |
1668 | .Ve |
1669 | .Sp |
1670 | or |
1671 | .Sp |
1672 | .Vb 5 |
1673 | \& { |
1674 | \& have => '<none>', |
1675 | \& need => '0.59', |
1676 | \& message => 'Prerequisite Foo isn't installed', |
1677 | \& } |
1678 | .Ve |
1679 | .Sp |
1680 | This hash has the same structure as the hash returned by the |
1681 | \&\f(CW\*(C`check_installed_status()\*(C'\fR method, except that in the case of |
1682 | \&\*(L"conflicts\*(R" dependencies we change the \*(L"need\*(R" key to \*(L"conflicts\*(R" and |
1683 | construct a proper message. |
1684 | .Sp |
1685 | Examples: |
1686 | .Sp |
1687 | .Vb 2 |
1688 | \& # Check a required dependency on Foo::Bar |
1689 | \& if ( $build\->prereq_failures\->{requires}{Foo::Bar} ) { ... |
1690 | .Ve |
1691 | .Sp |
1692 | .Vb 2 |
1693 | \& # Check whether there were any failures |
1694 | \& if ( $build\->prereq_failures ) { ... |
1695 | .Ve |
1696 | .Sp |
1697 | .Vb 7 |
1698 | \& # Show messages for all failures |
1699 | \& my $failures = $build\->prereq_failures; |
1700 | \& while (my ($type, $list) = each %$failures) { |
1701 | \& while (my ($name, $hash) = each %$list) { |
1702 | \& print "Failure for $name: $hash\->{message}\en"; |
1703 | \& } |
1704 | \& } |
1705 | .Ve |
1706 | .IP "\fIprereq_data()\fR" 4 |
1707 | .IX Item "prereq_data()" |
1708 | [version 0.32] |
1709 | .Sp |
1710 | Returns a reference to a hash describing all prerequisites. The keys of the |
1711 | hash will the various prerequisite types ('requires', 'build_requires', |
1712 | \&'configure_requires', 'recommends', or 'conflicts') and the values will |
1713 | references to hashes of module names and version numbers. Only prerequisites |
1714 | types that are defined will be included. The \f(CW\*(C`prereq_data\*(C'\fR action is just a |
1715 | thin wrapper around the \f(CW\*(C`prereq_data()\*(C'\fR method and dumps the hash as a string |
1716 | that can be loaded using \f(CW\*(C`eval()\*(C'\fR. |
1717 | .IP "\fIprereq_report()\fR" 4 |
1718 | .IX Item "prereq_report()" |
1719 | [version 0.28] |
1720 | .Sp |
1721 | Returns a human-readable (table\-form) string showing all |
1722 | prerequisites, the versions required, and the versions actually |
1723 | installed. This can be useful for reviewing the configuration of your |
1724 | system prior to a build, or when compiling data to send for a bug |
1725 | report. The \f(CW\*(C`prereq_report\*(C'\fR action is just a thin wrapper around the |
1726 | \&\f(CW\*(C`prereq_report()\*(C'\fR method. |
1727 | .ie n .IP "prompt($message, $default)" 4 |
1728 | .el .IP "prompt($message, \f(CW$default\fR)" 4 |
1729 | .IX Item "prompt($message, $default)" |
1730 | [version 0.12] |
1731 | .Sp |
1732 | Asks the user a question and returns their response as a string. The |
1733 | first argument specifies the message to display to the user (for |
1734 | example, \f(CW"Where do you keep your money?"\fR). The second argument, |
1735 | which is optional, specifies a default answer (for example, |
1736 | \&\f(CW"wallet"\fR). The user will be asked the question once. |
1737 | .Sp |
1738 | If \f(CW\*(C`prompt()\*(C'\fR detects that it is not running interactively and there |
1739 | is nothing on \s-1STDIN\s0 or if the \s-1PERL_MM_USE_DEFAULT\s0 environment variable |
1740 | is set to true, the \f(CW$default\fR will be used without prompting. |
1741 | .Sp |
1742 | To prevent automated processes from blocking, the user must either set |
1743 | \&\s-1PERL_MM_USE_DEFAULT\s0 or attach something to \s-1STDIN\s0 (this can be a |
1744 | pipe/file containing a scripted set of answers or /dev/null.) |
1745 | .Sp |
1746 | If no \f(CW$default\fR is provided an empty string will be used instead. In |
1747 | non-interactive mode, the absence of \f(CW$default\fR is an error (though |
1748 | explicitly passing \f(CW\*(C`undef()\*(C'\fR as the default is valid as of 0.27.) |
1749 | .Sp |
1750 | This method may be called as a class or object method. |
1751 | .IP "\fIrecommends()\fR" 4 |
1752 | .IX Item "recommends()" |
1753 | [version 0.21] |
1754 | .Sp |
1755 | Returns a hash reference indicating the \f(CW\*(C`recommends\*(C'\fR prerequisites |
1756 | that were passed to the \f(CW\*(C`new()\*(C'\fR method. |
1757 | .IP "\fIrequires()\fR" 4 |
1758 | .IX Item "requires()" |
1759 | [version 0.21] |
1760 | .Sp |
1761 | Returns a hash reference indicating the \f(CW\*(C`requires\*(C'\fR prerequisites that |
1762 | were passed to the \f(CW\*(C`new()\*(C'\fR method. |
1763 | .ie n .IP "rscan_dir($dir, $pattern)" 4 |
1764 | .el .IP "rscan_dir($dir, \f(CW$pattern\fR)" 4 |
1765 | .IX Item "rscan_dir($dir, $pattern)" |
1766 | [version 0.28] |
1767 | .Sp |
1768 | Uses \f(CW\*(C`File::Find\*(C'\fR to traverse the directory \f(CW$dir\fR, returning a |
1769 | reference to an array of entries matching \f(CW$pattern\fR. \f(CW$pattern\fR |
1770 | may either be a regular expression (using \f(CW\*(C`qr//\*(C'\fR or just a plain |
1771 | string), or a reference to a subroutine that will return true for |
1772 | wanted entries. If \f(CW$pattern\fR is not given, all entries will be |
1773 | returned. |
1774 | .Sp |
1775 | Examples: |
1776 | .Sp |
1777 | .Vb 2 |
1778 | \& # All the *.pm files in lib/ |
1779 | \& $m\->rscan_dir('lib', qr/\e.pm$/) |
1780 | .Ve |
1781 | .Sp |
1782 | .Vb 2 |
1783 | \& # All the files in blib/ that aren't *.html files |
1784 | \& $m\->rscan_dir('blib', sub {\-f $_ and not /\e.html$/}); |
1785 | .Ve |
1786 | .Sp |
1787 | .Vb 2 |
1788 | \& # All the files in t/ |
1789 | \& $m\->rscan_dir('t'); |
1790 | .Ve |
1791 | .IP "\fIruntime_params()\fR" 4 |
1792 | .IX Item "runtime_params()" |
1793 | .PD 0 |
1794 | .IP "runtime_params($key)" 4 |
1795 | .IX Item "runtime_params($key)" |
1796 | .PD |
1797 | [version 0.28] |
1798 | .Sp |
1799 | The \f(CW\*(C`runtime_params()\*(C'\fR method stores the values passed on the command line |
1800 | for valid properties (that is, any command line options for which |
1801 | \&\f(CW\*(C`valid_property()\*(C'\fR returns a true value). The value on the command line may |
1802 | override the default value for a property, as well as any value specified in a |
1803 | call to \f(CW\*(C`new()\*(C'\fR. This allows you to programmatically tell if \f(CW\*(C`perl Build.PL\*(C'\fR |
1804 | or any execution of \f(CW\*(C`./Build\*(C'\fR had command line options specified that |
1805 | override valid properties. |
1806 | .Sp |
1807 | The \f(CW\*(C`runtime_params()\*(C'\fR method is essentially a glorified read-only hash. With |
1808 | no arguments, \f(CW\*(C`runtime_params()\*(C'\fR returns the entire hash of properties |
1809 | specified on the command line. With one argument, \f(CW\*(C`runtime_params($key)\*(C'\fR |
1810 | returns the value associated with the given key. |
1811 | .Sp |
1812 | The lifetime of the \f(CW\*(C`runtime_params\*(C'\fR data is for \*(L"a build\*(R" \- that is, the |
1813 | \&\f(CW\*(C`runtime_params\*(C'\fR hash is created when \f(CW\*(C`perl Build.PL\*(C'\fR is run (or when the |
1814 | \&\f(CW\*(C`new()\*(C'\fR method is called, if the Module::Build Perl \s-1API\s0 is being used instead |
1815 | of called from a shell), and lasts until \f(CW\*(C`perl Build.PL\*(C'\fR is run again or the |
1816 | \&\f(CW\*(C`clean\*(C'\fR action is run. |
1817 | .IP "\fIscript_files()\fR" 4 |
1818 | .IX Item "script_files()" |
1819 | [version 0.18] |
1820 | .Sp |
1821 | Returns a hash reference whose keys are the perl script files to be |
1822 | installed, if any. This corresponds to the \f(CW\*(C`script_files\*(C'\fR parameter to the |
1823 | \&\f(CW\*(C`new()\*(C'\fR method. With an optional argument, this parameter may be set |
1824 | dynamically. |
1825 | .Sp |
1826 | For backward compatibility, the \f(CW\*(C`scripts()\*(C'\fR method does exactly the |
1827 | same thing as \f(CW\*(C`script_files()\*(C'\fR. \f(CW\*(C`scripts()\*(C'\fR is deprecated, but it |
1828 | will stay around for several versions to give people time to |
1829 | transition. |
1830 | .ie n .IP "up_to_date($source_file, $derived_file)" 4 |
1831 | .el .IP "up_to_date($source_file, \f(CW$derived_file\fR)" 4 |
1832 | .IX Item "up_to_date($source_file, $derived_file)" |
1833 | .PD 0 |
1834 | .IP "up_to_date(\e@source_files, \e@derived_files)" 4 |
1835 | .IX Item "up_to_date(@source_files, @derived_files)" |
1836 | .PD |
1837 | [version 0.20] |
1838 | .Sp |
1839 | This method can be used to compare a set of source files to a set of |
1840 | derived files. If any of the source files are newer than any of the |
1841 | derived files, it returns false. Additionally, if any of the derived |
1842 | files do not exist, it returns false. Otherwise it returns true. |
1843 | .Sp |
1844 | The arguments may be either a scalar or an array reference of file |
1845 | names. |
1846 | .ie n .IP "y_n($message, $default)" 4 |
1847 | .el .IP "y_n($message, \f(CW$default\fR)" 4 |
1848 | .IX Item "y_n($message, $default)" |
1849 | [version 0.12] |
1850 | .Sp |
1851 | Asks the user a yes/no question using \f(CW\*(C`prompt()\*(C'\fR and returns true or |
1852 | false accordingly. The user will be asked the question repeatedly |
1853 | until they give an answer that looks like \*(L"yes\*(R" or \*(L"no\*(R". |
1854 | .Sp |
1855 | The first argument specifies the message to display to the user (for |
1856 | example, \f(CW"Shall I invest your money for you?"\fR), and the second |
1857 | argument specifies the default answer (for example, \f(CW"y"\fR). |
1858 | .Sp |
1859 | Note that the default is specified as a string like \f(CW"y"\fR or \f(CW"n"\fR, |
1860 | and the return value is a Perl boolean value like 1 or 0. I thought |
1861 | about this for a while and this seemed like the most useful way to do |
1862 | it. |
1863 | .Sp |
1864 | This method may be called as a class or object method. |
1865 | .Sh "Autogenerated Accessors" |
1866 | .IX Subsection "Autogenerated Accessors" |
1867 | In addition to the aforementioned methods, there are also some get/set |
1868 | accessor methods for the following properties: |
1869 | .IP "\fIPL_files()\fR" 4 |
1870 | .IX Item "PL_files()" |
1871 | .PD 0 |
1872 | .IP "\fIallow_mb_mismatch()\fR" 4 |
1873 | .IX Item "allow_mb_mismatch()" |
1874 | .IP "\fIauto_configure_requires()\fR" 4 |
1875 | .IX Item "auto_configure_requires()" |
1876 | .IP "\fIautosplit()\fR" 4 |
1877 | .IX Item "autosplit()" |
1878 | .IP "\fIbase_dir()\fR" 4 |
1879 | .IX Item "base_dir()" |
1880 | .IP "\fIbindoc_dirs()\fR" 4 |
1881 | .IX Item "bindoc_dirs()" |
1882 | .IP "\fIblib()\fR" 4 |
1883 | .IX Item "blib()" |
1884 | .IP "\fIbuild_bat()\fR" 4 |
1885 | .IX Item "build_bat()" |
1886 | .IP "\fIbuild_class()\fR" 4 |
1887 | .IX Item "build_class()" |
1888 | .IP "\fIbuild_elements()\fR" 4 |
1889 | .IX Item "build_elements()" |
1890 | .IP "\fIbuild_requires()\fR" 4 |
1891 | .IX Item "build_requires()" |
1892 | .IP "\fIbuild_script()\fR" 4 |
1893 | .IX Item "build_script()" |
1894 | .IP "\fIc_source()\fR" 4 |
1895 | .IX Item "c_source()" |
1896 | .IP "\fIconfig_dir()\fR" 4 |
1897 | .IX Item "config_dir()" |
1898 | .IP "\fIconfigure_requires()\fR" 4 |
1899 | .IX Item "configure_requires()" |
1900 | .IP "\fIconflicts()\fR" 4 |
1901 | .IX Item "conflicts()" |
1902 | .IP "\fIcreate_license()\fR" 4 |
1903 | .IX Item "create_license()" |
1904 | .IP "\fIcreate_makefile_pl()\fR" 4 |
1905 | .IX Item "create_makefile_pl()" |
1906 | .IP "\fIcreate_packlist()\fR" 4 |
1907 | .IX Item "create_packlist()" |
1908 | .IP "\fIcreate_readme()\fR" 4 |
1909 | .IX Item "create_readme()" |
1910 | .IP "\fIdebug()\fR" 4 |
1911 | .IX Item "debug()" |
1912 | .IP "\fIdebugger()\fR" 4 |
1913 | .IX Item "debugger()" |
1914 | .IP "\fIdestdir()\fR" 4 |
1915 | .IX Item "destdir()" |
1916 | .IP "\fIget_options()\fR" 4 |
1917 | .IX Item "get_options()" |
1918 | .IP "\fIhtml_css()\fR" 4 |
1919 | .IX Item "html_css()" |
1920 | .IP "\fIinclude_dirs()\fR" 4 |
1921 | .IX Item "include_dirs()" |
1922 | .IP "\fIinstall_base()\fR" 4 |
1923 | .IX Item "install_base()" |
1924 | .IP "\fIinstalldirs()\fR" 4 |
1925 | .IX Item "installdirs()" |
1926 | .IP "\fIlibdoc_dirs()\fR" 4 |
1927 | .IX Item "libdoc_dirs()" |
1928 | .IP "\fIlicense()\fR" 4 |
1929 | .IX Item "license()" |
1930 | .IP "\fImagic_number()\fR" 4 |
1931 | .IX Item "magic_number()" |
1932 | .IP "\fImb_version()\fR" 4 |
1933 | .IX Item "mb_version()" |
1934 | .IP "\fImeta_add()\fR" 4 |
1935 | .IX Item "meta_add()" |
1936 | .IP "\fImeta_merge()\fR" 4 |
1937 | .IX Item "meta_merge()" |
1938 | .IP "\fImetafile()\fR" 4 |
1939 | .IX Item "metafile()" |
1940 | .IP "\fImodule_name()\fR" 4 |
1941 | .IX Item "module_name()" |
1942 | .IP "\fIorig_dir()\fR" 4 |
1943 | .IX Item "orig_dir()" |
1944 | .IP "\fIperl()\fR" 4 |
1945 | .IX Item "perl()" |
1946 | .IP "\fIpm_files()\fR" 4 |
1947 | .IX Item "pm_files()" |
1948 | .IP "\fIpod_files()\fR" 4 |
1949 | .IX Item "pod_files()" |
1950 | .IP "\fIpollute()\fR" 4 |
1951 | .IX Item "pollute()" |
1952 | .IP "\fIprefix()\fR" 4 |
1953 | .IX Item "prefix()" |
1954 | .IP "\fIprereq_action_types()\fR" 4 |
1955 | .IX Item "prereq_action_types()" |
1956 | .IP "\fIprogram_name()\fR" 4 |
1957 | .IX Item "program_name()" |
1958 | .IP "\fIquiet()\fR" 4 |
1959 | .IX Item "quiet()" |
1960 | .IP "\fIrecommends()\fR" 4 |
1961 | .IX Item "recommends()" |
1962 | .IP "\fIrecurse_into()\fR" 4 |
1963 | .IX Item "recurse_into()" |
1964 | .IP "\fIrecursive_test_files()\fR" 4 |
1965 | .IX Item "recursive_test_files()" |
1966 | .IP "\fIrequires()\fR" 4 |
1967 | .IX Item "requires()" |
1968 | .IP "\fIscripts()\fR" 4 |
1969 | .IX Item "scripts()" |
1970 | .IP "\fIsign()\fR" 4 |
1971 | .IX Item "sign()" |
1972 | .IP "\fItap_harness_args()\fR" 4 |
1973 | .IX Item "tap_harness_args()" |
1974 | .IP "\fItest_file_exts()\fR" 4 |
1975 | .IX Item "test_file_exts()" |
1976 | .IP "\fIuse_rcfile()\fR" 4 |
1977 | .IX Item "use_rcfile()" |
1978 | .IP "\fIuse_tap_harness()\fR" 4 |
1979 | .IX Item "use_tap_harness()" |
1980 | .IP "\fIverbose()\fR" 4 |
1981 | .IX Item "verbose()" |
1982 | .IP "\fIxs_files()\fR" 4 |
1983 | .IX Item "xs_files()" |
1984 | .PD |
1985 | .SH "MODULE METADATA" |
1986 | .IX Header "MODULE METADATA" |
1987 | If you would like to add other useful metadata, \f(CW\*(C`Module::Build\*(C'\fR |
1988 | supports this with the \f(CW\*(C`meta_add\*(C'\fR and \f(CW\*(C`meta_merge\*(C'\fR arguments to |
1989 | \&\*(L"new\*(R". The authoritative list of supported metadata can be found at |
1990 | <http://module\-build.sourceforge.net/META\-spec\-current.html>, but for |
1991 | convenience \- here are a few of the more useful ones: |
1992 | .IP "keywords" 4 |
1993 | .IX Item "keywords" |
1994 | For describing the distribution using keyword (or \*(L"tags\*(R") in order to |
1995 | make \s-1CPAN\s0.org indexing and search more efficient and useful. |
1996 | .Sp |
1997 | See <http://module\-build.sourceforge.net/META\-spec\-current.html#keywords>. |
1998 | .IP "resources" 4 |
1999 | .IX Item "resources" |
2000 | A list of additional resources available for users of the |
2001 | distribution. This can include links to a homepage on the web, a |
2002 | bug tracker, the repository location, a even subscription page for the |
2003 | distribution mailing list. |
2004 | .Sp |
2005 | See <http://module\-build.sourceforge.net/META\-spec\-current.html#resources>. |
2006 | .SH "AUTHOR" |
2007 | .IX Header "AUTHOR" |
2008 | Ken Williams <kwilliams@cpan.org> |
2009 | .SH "COPYRIGHT" |
2010 | .IX Header "COPYRIGHT" |
2011 | Copyright (c) 2001\-2006 Ken Williams. All rights reserved. |
2012 | .PP |
2013 | This library is free software; you can redistribute it and/or |
2014 | modify it under the same terms as Perl itself. |
2015 | .SH "SEE ALSO" |
2016 | .IX Header "SEE ALSO" |
2017 | \&\fIperl\fR\|(1), Module::Build(3), Module::Build::Authoring(3), |
2018 | Module::Build::Cookbook(3), ExtUtils::MakeMaker(3), \s-1YAML\s0(3) |
2019 | .PP |
2020 | \&\fI\s-1META\s0.yml\fR Specification: |
2021 | <http://module\-build.sourceforge.net/META\-spec\-current.html> |