Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
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 "ExtUtils::MakeMaker 3" | |
132 | .TH ExtUtils::MakeMaker 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | ExtUtils::MakeMaker \- Create a module Makefile | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use ExtUtils::MakeMaker; | |
139 | .Ve | |
140 | .PP | |
141 | .Vb 1 | |
142 | \& WriteMakefile( ATTRIBUTE => VALUE [, ...] ); | |
143 | .Ve | |
144 | .SH "DESCRIPTION" | |
145 | .IX Header "DESCRIPTION" | |
146 | This utility is designed to write a Makefile for an extension module | |
147 | from a Makefile.PL. It is based on the Makefile.SH model provided by | |
148 | Andy Dougherty and the perl5\-porters. | |
149 | .PP | |
150 | It splits the task of generating the Makefile into several subroutines | |
151 | that can be individually overridden. Each subroutine returns the text | |
152 | it wishes to have written to the Makefile. | |
153 | .PP | |
154 | MakeMaker is object oriented. Each directory below the current | |
155 | directory that contains a Makefile.PL is treated as a separate | |
156 | object. This makes it possible to write an unlimited number of | |
157 | Makefiles with a single invocation of \fIWriteMakefile()\fR. | |
158 | .Sh "How To Write A Makefile.PL" | |
159 | .IX Subsection "How To Write A Makefile.PL" | |
160 | See ExtUtils::MakeMaker::Tutorial. | |
161 | .PP | |
162 | The long answer is the rest of the manpage :\-) | |
163 | .Sh "Default Makefile Behaviour" | |
164 | .IX Subsection "Default Makefile Behaviour" | |
165 | The generated Makefile enables the user of the extension to invoke | |
166 | .PP | |
167 | .Vb 4 | |
168 | \& perl Makefile.PL # optionally "perl Makefile.PL verbose" | |
169 | \& make | |
170 | \& make test # optionally set TEST_VERBOSE=1 | |
171 | \& make install # See below | |
172 | .Ve | |
173 | .PP | |
174 | The Makefile to be produced may be altered by adding arguments of the | |
175 | form \f(CW\*(C`KEY=VALUE\*(C'\fR. E.g. | |
176 | .PP | |
177 | .Vb 1 | |
178 | \& perl Makefile.PL PREFIX=~ | |
179 | .Ve | |
180 | .PP | |
181 | Other interesting targets in the generated Makefile are | |
182 | .PP | |
183 | .Vb 5 | |
184 | \& make config # to check if the Makefile is up-to-date | |
185 | \& make clean # delete local temp files (Makefile gets renamed) | |
186 | \& make realclean # delete derived files (including ./blib) | |
187 | \& make ci # check in all the files in the MANIFEST file | |
188 | \& make dist # see below the Distribution Support section | |
189 | .Ve | |
190 | .Sh "make test" | |
191 | .IX Subsection "make test" | |
192 | MakeMaker checks for the existence of a file named \fItest.pl\fR in the | |
193 | current directory and if it exists it execute the script with the | |
194 | proper set of perl \f(CW\*(C`\-I\*(C'\fR options. | |
195 | .PP | |
196 | MakeMaker also checks for any files matching glob(\*(L"t/*.t\*(R"). It will | |
197 | execute all matching files in alphabetical order via the | |
198 | Test::Harness module with the \f(CW\*(C`\-I\*(C'\fR switches set correctly. | |
199 | .PP | |
200 | If you'd like to see the raw output of your tests, set the | |
201 | \&\f(CW\*(C`TEST_VERBOSE\*(C'\fR variable to true. | |
202 | .PP | |
203 | .Vb 1 | |
204 | \& make test TEST_VERBOSE=1 | |
205 | .Ve | |
206 | .Sh "make testdb" | |
207 | .IX Subsection "make testdb" | |
208 | A useful variation of the above is the target \f(CW\*(C`testdb\*(C'\fR. It runs the | |
209 | test under the Perl debugger (see perldebug). If the file | |
210 | \&\fItest.pl\fR exists in the current directory, it is used for the test. | |
211 | .PP | |
212 | If you want to debug some other testfile, set the \f(CW\*(C`TEST_FILE\*(C'\fR variable | |
213 | thusly: | |
214 | .PP | |
215 | .Vb 1 | |
216 | \& make testdb TEST_FILE=t/mytest.t | |
217 | .Ve | |
218 | .PP | |
219 | By default the debugger is called using \f(CW\*(C`\-d\*(C'\fR option to perl. If you | |
220 | want to specify some other option, set the \f(CW\*(C`TESTDB_SW\*(C'\fR variable: | |
221 | .PP | |
222 | .Vb 1 | |
223 | \& make testdb TESTDB_SW=-Dx | |
224 | .Ve | |
225 | .Sh "make install" | |
226 | .IX Subsection "make install" | |
227 | make alone puts all relevant files into directories that are named by | |
228 | the macros \s-1INST_LIB\s0, \s-1INST_ARCHLIB\s0, \s-1INST_SCRIPT\s0, \s-1INST_MAN1DIR\s0 and | |
229 | \&\s-1INST_MAN3DIR\s0. All these default to something below ./blib if you are | |
230 | \&\fInot\fR building below the perl source directory. If you \fIare\fR | |
231 | building below the perl source, \s-1INST_LIB\s0 and \s-1INST_ARCHLIB\s0 default to | |
232 | \&../../lib, and \s-1INST_SCRIPT\s0 is not defined. | |
233 | .PP | |
234 | The \fIinstall\fR target of the generated Makefile copies the files found | |
235 | below each of the INST_* directories to their INSTALL* | |
236 | counterparts. Which counterparts are chosen depends on the setting of | |
237 | \&\s-1INSTALLDIRS\s0 according to the following table: | |
238 | .PP | |
239 | .Vb 2 | |
240 | \& INSTALLDIRS set to | |
241 | \& perl site vendor | |
242 | .Ve | |
243 | .PP | |
244 | .Vb 7 | |
245 | \& PERLPREFIX SITEPREFIX VENDORPREFIX | |
246 | \& INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH | |
247 | \& INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB | |
248 | \& INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN | |
249 | \& INST_SCRIPT INSTALLSCRIPT INSTALLSCRIPT INSTALLSCRIPT | |
250 | \& INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR | |
251 | \& INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR | |
252 | .Ve | |
253 | .PP | |
254 | The \s-1INSTALL\s0... macros in turn default to their \f(CW%Config\fR | |
255 | ($Config{installprivlib}, \f(CW$Config\fR{installarchlib}, etc.) counterparts. | |
256 | .PP | |
257 | You can check the values of these variables on your system with | |
258 | .PP | |
259 | .Vb 1 | |
260 | \& perl '-V:install.*' | |
261 | .Ve | |
262 | .PP | |
263 | And to check the sequence in which the library directories are | |
264 | searched by perl, run | |
265 | .PP | |
266 | .Vb 1 | |
267 | \& perl -le 'print join $/, @INC' | |
268 | .Ve | |
269 | .PP | |
270 | Sometimes older versions of the module you're installing live in other | |
271 | directories in \f(CW@INC\fR. Because Perl loads the first version of a module it | |
272 | finds, not the newest, you might accidentally get one of these older | |
273 | versions even after installing a brand new version. To delete \fIall other | |
274 | versions of the module you're installing\fR (not simply older ones) set the | |
275 | \&\f(CW\*(C`UNINST\*(C'\fR variable. | |
276 | .PP | |
277 | .Vb 1 | |
278 | \& make install UNINST=1 | |
279 | .Ve | |
280 | .Sh "\s-1PREFIX\s0 and \s-1LIB\s0 attribute" | |
281 | .IX Subsection "PREFIX and LIB attribute" | |
282 | \&\s-1PREFIX\s0 and \s-1LIB\s0 can be used to set several INSTALL* attributes in one | |
283 | go. The quickest way to install a module in a non-standard place might | |
284 | be | |
285 | .PP | |
286 | .Vb 1 | |
287 | \& perl Makefile.PL PREFIX=~ | |
288 | .Ve | |
289 | .PP | |
290 | This will install all files in the module under your home directory, | |
291 | with man pages and libraries going into an appropriate place (usually | |
292 | ~/man and ~/lib). | |
293 | .PP | |
294 | Another way to specify many \s-1INSTALL\s0 directories with a single | |
295 | parameter is \s-1LIB\s0. | |
296 | .PP | |
297 | .Vb 1 | |
298 | \& perl Makefile.PL LIB=~/lib | |
299 | .Ve | |
300 | .PP | |
301 | This will install the module's architecture-independent files into | |
302 | ~/lib, the architecture-dependent files into ~/lib/$archname. | |
303 | .PP | |
304 | Note, that in both cases the tilde expansion is done by MakeMaker, not | |
305 | by perl by default, nor by make. | |
306 | .PP | |
307 | Conflicts between parameters \s-1LIB\s0, \s-1PREFIX\s0 and the various INSTALL* | |
308 | arguments are resolved so that: | |
309 | .IP "\(bu" 4 | |
310 | setting \s-1LIB\s0 overrides any setting of \s-1INSTALLPRIVLIB\s0, \s-1INSTALLARCHLIB\s0, | |
311 | \&\s-1INSTALLSITELIB\s0, \s-1INSTALLSITEARCH\s0 (and they are not affected by \s-1PREFIX\s0); | |
312 | .IP "\(bu" 4 | |
313 | without \s-1LIB\s0, setting \s-1PREFIX\s0 replaces the initial \f(CW$Config{prefix}\fR | |
314 | part of those INSTALL* arguments, even if the latter are explicitly | |
315 | set (but are set to still start with \f(CW$Config{prefix}\fR). | |
316 | .PP | |
317 | If the user has superuser privileges, and is not working on \s-1AFS\s0 or | |
318 | relatives, then the defaults for \s-1INSTALLPRIVLIB\s0, \s-1INSTALLARCHLIB\s0, | |
319 | \&\s-1INSTALLSCRIPT\s0, etc. will be appropriate, and this incantation will be | |
320 | the best: | |
321 | .PP | |
322 | .Vb 4 | |
323 | \& perl Makefile.PL; | |
324 | \& make; | |
325 | \& make test | |
326 | \& make install | |
327 | .Ve | |
328 | .PP | |
329 | make install per default writes some documentation of what has been | |
330 | done into the file \f(CW\*(C`$(INSTALLARCHLIB)/perllocal.pod\*(C'\fR. This feature | |
331 | can be bypassed by calling make pure_install. | |
332 | .Sh "\s-1AFS\s0 users" | |
333 | .IX Subsection "AFS users" | |
334 | will have to specify the installation directories as these most | |
335 | probably have changed since perl itself has been installed. They will | |
336 | have to do this by calling | |
337 | .PP | |
338 | .Vb 3 | |
339 | \& perl Makefile.PL INSTALLSITELIB=/afs/here/today \e | |
340 | \& INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages | |
341 | \& make | |
342 | .Ve | |
343 | .PP | |
344 | Be careful to repeat this procedure every time you recompile an | |
345 | extension, unless you are sure the \s-1AFS\s0 installation directories are | |
346 | still valid. | |
347 | .Sh "Static Linking of a new Perl Binary" | |
348 | .IX Subsection "Static Linking of a new Perl Binary" | |
349 | An extension that is built with the above steps is ready to use on | |
350 | systems supporting dynamic loading. On systems that do not support | |
351 | dynamic loading, any newly created extension has to be linked together | |
352 | with the available resources. MakeMaker supports the linking process | |
353 | by creating appropriate targets in the Makefile whenever an extension | |
354 | is built. You can invoke the corresponding section of the makefile with | |
355 | .PP | |
356 | .Vb 1 | |
357 | \& make perl | |
358 | .Ve | |
359 | .PP | |
360 | That produces a new perl binary in the current directory with all | |
361 | extensions linked in that can be found in \s-1INST_ARCHLIB\s0, \s-1SITELIBEXP\s0, | |
362 | and \s-1PERL_ARCHLIB\s0. To do that, MakeMaker writes a new Makefile, on | |
363 | \&\s-1UNIX\s0, this is called Makefile.aperl (may be system dependent). If you | |
364 | want to force the creation of a new perl, it is recommended, that you | |
365 | delete this Makefile.aperl, so the directories are searched-through | |
366 | for linkable libraries again. | |
367 | .PP | |
368 | The binary can be installed into the directory where perl normally | |
369 | resides on your machine with | |
370 | .PP | |
371 | .Vb 1 | |
372 | \& make inst_perl | |
373 | .Ve | |
374 | .PP | |
375 | To produce a perl binary with a different name than \f(CW\*(C`perl\*(C'\fR, either say | |
376 | .PP | |
377 | .Vb 3 | |
378 | \& perl Makefile.PL MAP_TARGET=myperl | |
379 | \& make myperl | |
380 | \& make inst_perl | |
381 | .Ve | |
382 | .PP | |
383 | or say | |
384 | .PP | |
385 | .Vb 3 | |
386 | \& perl Makefile.PL | |
387 | \& make myperl MAP_TARGET=myperl | |
388 | \& make inst_perl MAP_TARGET=myperl | |
389 | .Ve | |
390 | .PP | |
391 | In any case you will be prompted with the correct invocation of the | |
392 | \&\f(CW\*(C`inst_perl\*(C'\fR target that installs the new binary into \s-1INSTALLBIN\s0. | |
393 | .PP | |
394 | make inst_perl per default writes some documentation of what has been | |
395 | done into the file \f(CW\*(C`$(INSTALLARCHLIB)/perllocal.pod\*(C'\fR. This | |
396 | can be bypassed by calling make pure_inst_perl. | |
397 | .PP | |
398 | Warning: the inst_perl: target will most probably overwrite your | |
399 | existing perl binary. Use with care! | |
400 | .PP | |
401 | Sometimes you might want to build a statically linked perl although | |
402 | your system supports dynamic loading. In this case you may explicitly | |
403 | set the linktype with the invocation of the Makefile.PL or make: | |
404 | .PP | |
405 | .Vb 1 | |
406 | \& perl Makefile.PL LINKTYPE=static # recommended | |
407 | .Ve | |
408 | .PP | |
409 | or | |
410 | .PP | |
411 | .Vb 1 | |
412 | \& make LINKTYPE=static # works on most systems | |
413 | .Ve | |
414 | .Sh "Determination of Perl Library and Installation Locations" | |
415 | .IX Subsection "Determination of Perl Library and Installation Locations" | |
416 | MakeMaker needs to know, or to guess, where certain things are | |
417 | located. Especially \s-1INST_LIB\s0 and \s-1INST_ARCHLIB\s0 (where to put the files | |
418 | during the \fImake\fR\|(1) run), \s-1PERL_LIB\s0 and \s-1PERL_ARCHLIB\s0 (where to read | |
419 | existing modules from), and \s-1PERL_INC\s0 (header files and \f(CW\*(C`libperl*.*\*(C'\fR). | |
420 | .PP | |
421 | Extensions may be built either using the contents of the perl source | |
422 | directory tree or from the installed perl library. The recommended way | |
423 | is to build extensions after you have run 'make install' on perl | |
424 | itself. You can do that in any directory on your hard disk that is not | |
425 | below the perl source tree. The support for extensions below the ext | |
426 | directory of the perl distribution is only good for the standard | |
427 | extensions that come with perl. | |
428 | .PP | |
429 | If an extension is being built below the \f(CW\*(C`ext/\*(C'\fR directory of the perl | |
430 | source then MakeMaker will set \s-1PERL_SRC\s0 automatically (e.g., | |
431 | \&\f(CW\*(C`../..\*(C'\fR). If \s-1PERL_SRC\s0 is defined and the extension is recognized as | |
432 | a standard extension, then other variables default to the following: | |
433 | .PP | |
434 | .Vb 5 | |
435 | \& PERL_INC = PERL_SRC | |
436 | \& PERL_LIB = PERL_SRC/lib | |
437 | \& PERL_ARCHLIB = PERL_SRC/lib | |
438 | \& INST_LIB = PERL_LIB | |
439 | \& INST_ARCHLIB = PERL_ARCHLIB | |
440 | .Ve | |
441 | .PP | |
442 | If an extension is being built away from the perl source then MakeMaker | |
443 | will leave \s-1PERL_SRC\s0 undefined and default to using the installed copy | |
444 | of the perl library. The other variables default to the following: | |
445 | .PP | |
446 | .Vb 5 | |
447 | \& PERL_INC = $archlibexp/CORE | |
448 | \& PERL_LIB = $privlibexp | |
449 | \& PERL_ARCHLIB = $archlibexp | |
450 | \& INST_LIB = ./blib/lib | |
451 | \& INST_ARCHLIB = ./blib/arch | |
452 | .Ve | |
453 | .PP | |
454 | If perl has not yet been installed then \s-1PERL_SRC\s0 can be defined on the | |
455 | command line as shown in the previous section. | |
456 | .Sh "Which architecture dependent directory?" | |
457 | .IX Subsection "Which architecture dependent directory?" | |
458 | If you don't want to keep the defaults for the INSTALL* macros, | |
459 | MakeMaker helps you to minimize the typing needed: the usual | |
460 | relationship between \s-1INSTALLPRIVLIB\s0 and \s-1INSTALLARCHLIB\s0 is determined | |
461 | by Configure at perl compilation time. MakeMaker supports the user who | |
462 | sets \s-1INSTALLPRIVLIB\s0. If \s-1INSTALLPRIVLIB\s0 is set, but \s-1INSTALLARCHLIB\s0 not, | |
463 | then MakeMaker defaults the latter to be the same subdirectory of | |
464 | \&\s-1INSTALLPRIVLIB\s0 as Configure decided for the counterparts in \f(CW%Config\fR , | |
465 | otherwise it defaults to \s-1INSTALLPRIVLIB\s0. The same relationship holds | |
466 | for \s-1INSTALLSITELIB\s0 and \s-1INSTALLSITEARCH\s0. | |
467 | .PP | |
468 | MakeMaker gives you much more freedom than needed to configure | |
469 | internal variables and get different results. It is worth to mention, | |
470 | that \fImake\fR\|(1) also lets you configure most of the variables that are | |
471 | used in the Makefile. But in the majority of situations this will not | |
472 | be necessary, and should only be done if the author of a package | |
473 | recommends it (or you know what you're doing). | |
474 | .Sh "Using Attributes and Parameters" | |
475 | .IX Subsection "Using Attributes and Parameters" | |
476 | The following attributes may be specified as arguments to \fIWriteMakefile()\fR | |
477 | or as NAME=VALUE pairs on the command line. | |
478 | .IP "\s-1ABSTRACT\s0" 2 | |
479 | .IX Item "ABSTRACT" | |
480 | One line description of the module. Will be included in \s-1PPD\s0 file. | |
481 | .IP "\s-1ABSTRACT_FROM\s0" 2 | |
482 | .IX Item "ABSTRACT_FROM" | |
483 | Name of the file that contains the package description. MakeMaker looks | |
484 | for a line in the \s-1POD\s0 matching /^($package\es\-\es)(.*)/. This is typically | |
485 | the first line in the \*(L"=head1 \s-1NAME\s0\*(R" section. \f(CW$2\fR becomes the abstract. | |
486 | .IP "\s-1AUTHOR\s0" 2 | |
487 | .IX Item "AUTHOR" | |
488 | String containing name (and email address) of package author(s). Is used | |
489 | in \s-1PPD\s0 (Perl Package Description) files for \s-1PPM\s0 (Perl Package Manager). | |
490 | .IP "\s-1BINARY_LOCATION\s0" 2 | |
491 | .IX Item "BINARY_LOCATION" | |
492 | Used when creating \s-1PPD\s0 files for binary packages. It can be set to a | |
493 | full or relative path or \s-1URL\s0 to the binary archive for a particular | |
494 | architecture. For example: | |
495 | .Sp | |
496 | .Vb 1 | |
497 | \& perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz | |
498 | .Ve | |
499 | .Sp | |
500 | builds a \s-1PPD\s0 package that references a binary of the \f(CW\*(C`Agent\*(C'\fR package, | |
501 | located in the \f(CW\*(C`x86\*(C'\fR directory relative to the \s-1PPD\s0 itself. | |
502 | .IP "C" 2 | |
503 | .IX Item "C" | |
504 | Ref to array of *.c file names. Initialised from a directory scan | |
505 | and the values portion of the \s-1XS\s0 attribute hash. This is not | |
506 | currently used by MakeMaker but may be handy in Makefile.PLs. | |
507 | .IP "\s-1CCFLAGS\s0" 2 | |
508 | .IX Item "CCFLAGS" | |
509 | String that will be included in the compiler call command line between | |
510 | the arguments \s-1INC\s0 and \s-1OPTIMIZE\s0. | |
511 | .IP "\s-1CONFIG\s0" 2 | |
512 | .IX Item "CONFIG" | |
513 | Arrayref. E.g. [qw(archname manext)] defines \s-1ARCHNAME\s0 & \s-1MANEXT\s0 from | |
514 | config.sh. MakeMaker will add to \s-1CONFIG\s0 the following values anyway: | |
515 | ar | |
516 | cc | |
517 | cccdlflags | |
518 | ccdlflags | |
519 | dlext | |
520 | dlsrc | |
521 | ld | |
522 | lddlflags | |
523 | ldflags | |
524 | libc | |
525 | lib_ext | |
526 | obj_ext | |
527 | ranlib | |
528 | sitelibexp | |
529 | sitearchexp | |
530 | so | |
531 | .IP "\s-1CONFIGURE\s0" 2 | |
532 | .IX Item "CONFIGURE" | |
533 | \&\s-1CODE\s0 reference. The subroutine should return a hash reference. The | |
534 | hash may contain further attributes, e.g. {\s-1LIBS\s0 => ...}, that have to | |
535 | be determined by some evaluation method. | |
536 | .IP "\s-1DEFINE\s0" 2 | |
537 | .IX Item "DEFINE" | |
538 | Something like \f(CW"\-DHAVE_UNISTD_H"\fR | |
539 | .IP "\s-1DESTDIR\s0" 2 | |
540 | .IX Item "DESTDIR" | |
541 | This is the root directory into which the code will be installed. It | |
542 | \&\fIprepends itself to the normal prefix\fR. For example, if your code | |
543 | would normally go into \fI/usr/local/lib/perl\fR you could set DESTDIR=~/tmp/ | |
544 | and installation would go into \fI~/tmp/usr/local/lib/perl\fR. | |
545 | .Sp | |
546 | This is primarily of use for people who repackage Perl modules. | |
547 | .Sp | |
548 | \&\s-1NOTE:\s0 Due to the nature of make, it is important that you put the trailing | |
549 | slash on your \s-1DESTDIR\s0. \fI~/tmp/\fR not \fI~/tmp\fR. | |
550 | .IP "\s-1DIR\s0" 2 | |
551 | .IX Item "DIR" | |
552 | Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm' | |
553 | ] in ext/SDBM_File | |
554 | .IP "\s-1DISTNAME\s0" 2 | |
555 | .IX Item "DISTNAME" | |
556 | A safe filename for the package. | |
557 | .Sp | |
558 | Defaults to \s-1NAME\s0 above but with :: replaced with \-. | |
559 | .Sp | |
560 | For example, Foo::Bar becomes Foo\-Bar. | |
561 | .IP "\s-1DISTVNAME\s0" 2 | |
562 | .IX Item "DISTVNAME" | |
563 | Your name for distributing the package with the version number | |
564 | included. This is used by 'make dist' to name the resulting archive | |
565 | file. | |
566 | .Sp | |
567 | Defaults to \s-1DISTNAME\-VERSION\s0. | |
568 | .Sp | |
569 | For example, version 1.04 of Foo::Bar becomes Foo\-Bar\-1.04. | |
570 | .Sp | |
571 | On some \s-1OS\s0's where . has special meaning \s-1VERSION_SYM\s0 may be used in | |
572 | place of \s-1VERSION\s0. | |
573 | .IP "\s-1DL_FUNCS\s0" 2 | |
574 | .IX Item "DL_FUNCS" | |
575 | Hashref of symbol names for routines to be made available as universal | |
576 | symbols. Each key/value pair consists of the package name and an | |
577 | array of routine names in that package. Used only under \s-1AIX\s0, \s-1OS/2\s0, | |
578 | \&\s-1VMS\s0 and Win32 at present. The routine names supplied will be expanded | |
579 | in the same way as \s-1XSUB\s0 names are expanded by the \s-1\fIXS\s0()\fR macro. | |
580 | Defaults to | |
581 | .Sp | |
582 | .Vb 1 | |
583 | \& {"$(NAME)" => ["boot_$(NAME)" ] } | |
584 | .Ve | |
585 | .Sp | |
586 | e.g. | |
587 | .Sp | |
588 | .Vb 2 | |
589 | \& {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )], | |
590 | \& "NetconfigPtr" => [ 'DESTROY'] } | |
591 | .Ve | |
592 | .Sp | |
593 | Please see the ExtUtils::Mksymlists documentation for more information | |
594 | about the \s-1DL_FUNCS\s0, \s-1DL_VARS\s0 and \s-1FUNCLIST\s0 attributes. | |
595 | .IP "\s-1DL_VARS\s0" 2 | |
596 | .IX Item "DL_VARS" | |
597 | Array of symbol names for variables to be made available as universal symbols. | |
598 | Used only under \s-1AIX\s0, \s-1OS/2\s0, \s-1VMS\s0 and Win32 at present. Defaults to []. | |
599 | (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ]) | |
600 | .IP "\s-1EXCLUDE_EXT\s0" 2 | |
601 | .IX Item "EXCLUDE_EXT" | |
602 | Array of extension names to exclude when doing a static build. This | |
603 | is ignored if \s-1INCLUDE_EXT\s0 is present. Consult \s-1INCLUDE_EXT\s0 for more | |
604 | details. (e.g. [ qw( Socket \s-1POSIX\s0 ) ] ) | |
605 | .Sp | |
606 | This attribute may be most useful when specified as a string on the | |
607 | command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe' | |
608 | .IP "\s-1EXE_FILES\s0" 2 | |
609 | .IX Item "EXE_FILES" | |
610 | Ref to array of executable files. The files will be copied to the | |
611 | \&\s-1INST_SCRIPT\s0 directory. Make realclean will delete them from there | |
612 | again. | |
613 | .Sp | |
614 | If your executables start with something like #!perl or | |
615 | #!/usr/bin/perl MakeMaker will change this to the path of the perl | |
616 | \&'Makefile.PL' was invoked with so the programs will be sure to run | |
617 | properly even if perl is not in /usr/bin/perl. | |
618 | .IP "\s-1FIRST_MAKEFILE\s0" 2 | |
619 | .IX Item "FIRST_MAKEFILE" | |
620 | The name of the Makefile to be produced. This is used for the second | |
621 | Makefile that will be produced for the \s-1MAP_TARGET\s0. | |
622 | .Sp | |
623 | Defaults to 'Makefile' or 'Descrip.MMS' on \s-1VMS\s0. | |
624 | .Sp | |
625 | (Note: we couldn't use \s-1MAKEFILE\s0 because dmake uses this for something | |
626 | else). | |
627 | .IP "\s-1FULLPERL\s0" 2 | |
628 | .IX Item "FULLPERL" | |
629 | Perl binary able to run this extension, load \s-1XS\s0 modules, etc... | |
630 | .IP "\s-1FULLPERLRUN\s0" 2 | |
631 | .IX Item "FULLPERLRUN" | |
632 | Like \s-1PERLRUN\s0, except it uses \s-1FULLPERL\s0. | |
633 | .IP "\s-1FULLPERLRUNINST\s0" 2 | |
634 | .IX Item "FULLPERLRUNINST" | |
635 | Like \s-1PERLRUNINST\s0, except it uses \s-1FULLPERL\s0. | |
636 | .IP "\s-1FUNCLIST\s0" 2 | |
637 | .IX Item "FUNCLIST" | |
638 | This provides an alternate means to specify function names to be | |
639 | exported from the extension. Its value is a reference to an | |
640 | array of function names to be exported by the extension. These | |
641 | names are passed through unaltered to the linker options file. | |
642 | .IP "H" 2 | |
643 | .IX Item "H" | |
644 | Ref to array of *.h file names. Similar to C. | |
645 | .IP "\s-1IMPORTS\s0" 2 | |
646 | .IX Item "IMPORTS" | |
647 | This attribute is used to specify names to be imported into the | |
648 | extension. Takes a hash ref. | |
649 | .Sp | |
650 | It is only used on \s-1OS/2\s0 and Win32. | |
651 | .IP "\s-1INC\s0" 2 | |
652 | .IX Item "INC" | |
653 | Include file dirs eg: \f(CW"\-I/usr/5include \-I/path/to/inc"\fR | |
654 | .IP "\s-1INCLUDE_EXT\s0" 2 | |
655 | .IX Item "INCLUDE_EXT" | |
656 | Array of extension names to be included when doing a static build. | |
657 | MakeMaker will normally build with all of the installed extensions when | |
658 | doing a static build, and that is usually the desired behavior. If | |
659 | \&\s-1INCLUDE_EXT\s0 is present then MakeMaker will build only with those extensions | |
660 | which are explicitly mentioned. (e.g. [ qw( Socket \s-1POSIX\s0 ) ]) | |
661 | .Sp | |
662 | It is not necessary to mention DynaLoader or the current extension when | |
663 | filling in \s-1INCLUDE_EXT\s0. If the \s-1INCLUDE_EXT\s0 is mentioned but is empty then | |
664 | only DynaLoader and the current extension will be included in the build. | |
665 | .Sp | |
666 | This attribute may be most useful when specified as a string on the | |
667 | command line: perl Makefile.PL INCLUDE_EXT='\s-1POSIX\s0 Socket Devel::Peek' | |
668 | .IP "\s-1INSTALLARCHLIB\s0" 2 | |
669 | .IX Item "INSTALLARCHLIB" | |
670 | Used by 'make install', which copies files from \s-1INST_ARCHLIB\s0 to this | |
671 | directory if \s-1INSTALLDIRS\s0 is set to perl. | |
672 | .IP "\s-1INSTALLBIN\s0" 2 | |
673 | .IX Item "INSTALLBIN" | |
674 | Directory to install binary files (e.g. tkperl) into if | |
675 | INSTALLDIRS=perl. | |
676 | .IP "\s-1INSTALLDIRS\s0" 2 | |
677 | .IX Item "INSTALLDIRS" | |
678 | Determines which of the sets of installation directories to choose: | |
679 | perl, site or vendor. Defaults to site. | |
680 | .IP "\s-1INSTALLMAN1DIR\s0" 2 | |
681 | .IX Item "INSTALLMAN1DIR" | |
682 | .PD 0 | |
683 | .IP "\s-1INSTALLMAN3DIR\s0" 2 | |
684 | .IX Item "INSTALLMAN3DIR" | |
685 | .PD | |
686 | These directories get the man pages at 'make install' time if | |
687 | INSTALLDIRS=perl. Defaults to \f(CW$Config\fR{installman*dir}. | |
688 | .Sp | |
689 | If set to 'none', no man pages will be installed. | |
690 | .IP "\s-1INSTALLPRIVLIB\s0" 2 | |
691 | .IX Item "INSTALLPRIVLIB" | |
692 | Used by 'make install', which copies files from \s-1INST_LIB\s0 to this | |
693 | directory if \s-1INSTALLDIRS\s0 is set to perl. | |
694 | .Sp | |
695 | Defaults to \f(CW$Config\fR{installprivlib}. | |
696 | .IP "\s-1INSTALLSCRIPT\s0" 2 | |
697 | .IX Item "INSTALLSCRIPT" | |
698 | Used by 'make install' which copies files from \s-1INST_SCRIPT\s0 to this | |
699 | directory. | |
700 | .IP "\s-1INSTALLSITEARCH\s0" 2 | |
701 | .IX Item "INSTALLSITEARCH" | |
702 | Used by 'make install', which copies files from \s-1INST_ARCHLIB\s0 to this | |
703 | directory if \s-1INSTALLDIRS\s0 is set to site (default). | |
704 | .IP "\s-1INSTALLSITEBIN\s0" 2 | |
705 | .IX Item "INSTALLSITEBIN" | |
706 | Used by 'make install', which copies files from \s-1INST_BIN\s0 to this | |
707 | directory if \s-1INSTALLDIRS\s0 is set to site (default). | |
708 | .IP "\s-1INSTALLSITELIB\s0" 2 | |
709 | .IX Item "INSTALLSITELIB" | |
710 | Used by 'make install', which copies files from \s-1INST_LIB\s0 to this | |
711 | directory if \s-1INSTALLDIRS\s0 is set to site (default). | |
712 | .IP "\s-1INSTALLSITEMAN1DIR\s0" 2 | |
713 | .IX Item "INSTALLSITEMAN1DIR" | |
714 | .PD 0 | |
715 | .IP "\s-1INSTALLSITEMAN3DIR\s0" 2 | |
716 | .IX Item "INSTALLSITEMAN3DIR" | |
717 | .PD | |
718 | These directories get the man pages at 'make install' time if | |
719 | INSTALLDIRS=site (default). Defaults to | |
720 | $(\s-1SITEPREFIX\s0)/man/man$(MAN*EXT). | |
721 | .Sp | |
722 | If set to 'none', no man pages will be installed. | |
723 | .IP "\s-1INSTALLVENDORARCH\s0" 2 | |
724 | .IX Item "INSTALLVENDORARCH" | |
725 | Used by 'make install', which copies files from \s-1INST_ARCHLIB\s0 to this | |
726 | directory if \s-1INSTALLDIRS\s0 is set to vendor. | |
727 | .IP "\s-1INSTALLVENDORBIN\s0" 2 | |
728 | .IX Item "INSTALLVENDORBIN" | |
729 | Used by 'make install', which copies files from \s-1INST_BIN\s0 to this | |
730 | directory if \s-1INSTALLDIRS\s0 is set to vendor. | |
731 | .IP "\s-1INSTALLVENDORLIB\s0" 2 | |
732 | .IX Item "INSTALLVENDORLIB" | |
733 | Used by 'make install', which copies files from \s-1INST_LIB\s0 to this | |
734 | directory if \s-1INSTALLDIRS\s0 is set to vendor. | |
735 | .IP "\s-1INSTALLVENDORMAN1DIR\s0" 2 | |
736 | .IX Item "INSTALLVENDORMAN1DIR" | |
737 | .PD 0 | |
738 | .IP "\s-1INSTALLVENDORMAN3DIR\s0" 2 | |
739 | .IX Item "INSTALLVENDORMAN3DIR" | |
740 | .PD | |
741 | These directories get the man pages at 'make install' time if | |
742 | INSTALLDIRS=vendor. Defaults to $(\s-1VENDORPREFIX\s0)/man/man$(MAN*EXT). | |
743 | .Sp | |
744 | If set to 'none', no man pages will be installed. | |
745 | .IP "\s-1INST_ARCHLIB\s0" 2 | |
746 | .IX Item "INST_ARCHLIB" | |
747 | Same as \s-1INST_LIB\s0 for architecture dependent files. | |
748 | .IP "\s-1INST_BIN\s0" 2 | |
749 | .IX Item "INST_BIN" | |
750 | Directory to put real binary files during 'make'. These will be copied | |
751 | to \s-1INSTALLBIN\s0 during 'make install' | |
752 | .IP "\s-1INST_LIB\s0" 2 | |
753 | .IX Item "INST_LIB" | |
754 | Directory where we put library files of this extension while building | |
755 | it. | |
756 | .IP "\s-1INST_MAN1DIR\s0" 2 | |
757 | .IX Item "INST_MAN1DIR" | |
758 | Directory to hold the man pages at 'make' time | |
759 | .IP "\s-1INST_MAN3DIR\s0" 2 | |
760 | .IX Item "INST_MAN3DIR" | |
761 | Directory to hold the man pages at 'make' time | |
762 | .IP "\s-1INST_SCRIPT\s0" 2 | |
763 | .IX Item "INST_SCRIPT" | |
764 | Directory, where executable files should be installed during | |
765 | \&'make'. Defaults to \*(L"./blib/script\*(R", just to have a dummy location during | |
766 | testing. make install will copy the files in \s-1INST_SCRIPT\s0 to | |
767 | \&\s-1INSTALLSCRIPT\s0. | |
768 | .IP "\s-1LD\s0" 2 | |
769 | .IX Item "LD" | |
770 | Program to be used to link libraries for dynamic loading. | |
771 | .Sp | |
772 | Defaults to \f(CW$Config\fR{ld}. | |
773 | .IP "\s-1LDDLFLAGS\s0" 2 | |
774 | .IX Item "LDDLFLAGS" | |
775 | Any special flags that might need to be passed to ld to create a | |
776 | shared library suitable for dynamic loading. It is up to the makefile | |
777 | to use it. (See \*(L"lddlflags\*(R" in Config) | |
778 | .Sp | |
779 | Defaults to \f(CW$Config\fR{lddlflags}. | |
780 | .IP "\s-1LDFROM\s0" 2 | |
781 | .IX Item "LDFROM" | |
782 | Defaults to \*(L"$(\s-1OBJECT\s0)\*(R" and is used in the ld command to specify | |
783 | what files to link/load from (also see dynamic_lib below for how to | |
784 | specify ld flags) | |
785 | .IP "\s-1LIB\s0" 2 | |
786 | .IX Item "LIB" | |
787 | \&\s-1LIB\s0 should only be set at \f(CW\*(C`perl Makefile.PL\*(C'\fR time but is allowed as a | |
788 | MakeMaker argument. It has the effect of setting both \s-1INSTALLPRIVLIB\s0 | |
789 | and \s-1INSTALLSITELIB\s0 to that value regardless any explicit setting of | |
790 | those arguments (or of \s-1PREFIX\s0). \s-1INSTALLARCHLIB\s0 and \s-1INSTALLSITEARCH\s0 | |
791 | are set to the corresponding architecture subdirectory. | |
792 | .IP "\s-1LIBPERL_A\s0" 2 | |
793 | .IX Item "LIBPERL_A" | |
794 | The filename of the perllibrary that will be used together with this | |
795 | extension. Defaults to libperl.a. | |
796 | .IP "\s-1LIBS\s0" 2 | |
797 | .IX Item "LIBS" | |
798 | An anonymous array of alternative library | |
799 | specifications to be searched for (in order) until | |
800 | at least one library is found. E.g. | |
801 | .Sp | |
802 | .Vb 1 | |
803 | \& 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"] | |
804 | .Ve | |
805 | .Sp | |
806 | Mind, that any element of the array | |
807 | contains a complete set of arguments for the ld | |
808 | command. So do not specify | |
809 | .Sp | |
810 | .Vb 1 | |
811 | \& 'LIBS' => ["-ltcl", "-ltk", "-lX11"] | |
812 | .Ve | |
813 | .Sp | |
814 | See ODBM_File/Makefile.PL for an example, where an array is needed. If | |
815 | you specify a scalar as in | |
816 | .Sp | |
817 | .Vb 1 | |
818 | \& 'LIBS' => "-ltcl -ltk -lX11" | |
819 | .Ve | |
820 | .Sp | |
821 | MakeMaker will turn it into an array with one element. | |
822 | .IP "\s-1LINKTYPE\s0" 2 | |
823 | .IX Item "LINKTYPE" | |
824 | \&'static' or 'dynamic' (default unless usedl=undef in | |
825 | config.sh). Should only be used to force static linking (also see | |
826 | linkext below). | |
827 | .IP "\s-1MAKEAPERL\s0" 2 | |
828 | .IX Item "MAKEAPERL" | |
829 | Boolean which tells MakeMaker, that it should include the rules to | |
830 | make a perl. This is handled automatically as a switch by | |
831 | MakeMaker. The user normally does not need it. | |
832 | .IP "\s-1MAKEFILE_OLD\s0" 2 | |
833 | .IX Item "MAKEFILE_OLD" | |
834 | When 'make clean' or similar is run, the $(\s-1FIRST_MAKEFILE\s0) will be | |
835 | backed up at this location. | |
836 | .Sp | |
837 | Defaults to $(\s-1FIRST_MAKEFILE\s0).old or $(\s-1FIRST_MAKEFILE\s0)_old on \s-1VMS\s0. | |
838 | .IP "\s-1MAN1PODS\s0" 2 | |
839 | .IX Item "MAN1PODS" | |
840 | Hashref of pod-containing files. MakeMaker will default this to all | |
841 | \&\s-1EXE_FILES\s0 files that include \s-1POD\s0 directives. The files listed | |
842 | here will be converted to man pages and installed as was requested | |
843 | at Configure time. | |
844 | .IP "\s-1MAN3PODS\s0" 2 | |
845 | .IX Item "MAN3PODS" | |
846 | Hashref that assigns to *.pm and *.pod files the files into which the | |
847 | manpages are to be written. MakeMaker parses all *.pod and *.pm files | |
848 | for \s-1POD\s0 directives. Files that contain \s-1POD\s0 will be the default keys of | |
849 | the \s-1MAN3PODS\s0 hashref. These will then be converted to man pages during | |
850 | \&\f(CW\*(C`make\*(C'\fR and will be installed during \f(CW\*(C`make install\*(C'\fR. | |
851 | .IP "\s-1MAP_TARGET\s0" 2 | |
852 | .IX Item "MAP_TARGET" | |
853 | If it is intended, that a new perl binary be produced, this variable | |
854 | may hold a name for that binary. Defaults to perl | |
855 | .IP "\s-1MYEXTLIB\s0" 2 | |
856 | .IX Item "MYEXTLIB" | |
857 | If the extension links to a library that it builds set this to the | |
858 | name of the library (see SDBM_File) | |
859 | .IP "\s-1NAME\s0" 2 | |
860 | .IX Item "NAME" | |
861 | Perl module name for this extension (DBD::Oracle). This will default | |
862 | to the directory name but should be explicitly defined in the | |
863 | Makefile.PL. | |
864 | .IP "\s-1NEEDS_LINKING\s0" 2 | |
865 | .IX Item "NEEDS_LINKING" | |
866 | MakeMaker will figure out if an extension contains linkable code | |
867 | anywhere down the directory tree, and will set this variable | |
868 | accordingly, but you can speed it up a very little bit if you define | |
869 | this boolean variable yourself. | |
870 | .IP "\s-1NOECHO\s0" 2 | |
871 | .IX Item "NOECHO" | |
872 | Command so make does not print the literal commands its running. | |
873 | .Sp | |
874 | By setting it to an empty string you can generate a Makefile that | |
875 | prints all commands. Mainly used in debugging MakeMaker itself. | |
876 | .Sp | |
877 | Defaults to \f(CW\*(C`@\*(C'\fR. | |
878 | .IP "\s-1NORECURS\s0" 2 | |
879 | .IX Item "NORECURS" | |
880 | Boolean. Attribute to inhibit descending into subdirectories. | |
881 | .IP "\s-1NO_META\s0" 2 | |
882 | .IX Item "NO_META" | |
883 | When true, suppresses the generation and addition to the \s-1MANIFEST\s0 of | |
884 | the \s-1META\s0.yml module meta-data file during 'make distdir'. | |
885 | .Sp | |
886 | Defaults to false. | |
887 | .IP "\s-1NO_VC\s0" 2 | |
888 | .IX Item "NO_VC" | |
889 | In general, any generated Makefile checks for the current version of | |
890 | MakeMaker and the version the Makefile was built under. If \s-1NO_VC\s0 is | |
891 | set, the version check is neglected. Do not write this into your | |
892 | Makefile.PL, use it interactively instead. | |
893 | .IP "\s-1OBJECT\s0" 2 | |
894 | .IX Item "OBJECT" | |
895 | List of object files, defaults to '$(\s-1BASEEXT\s0)$(\s-1OBJ_EXT\s0)', but can be a long | |
896 | string containing all object files, e.g. \*(L"tkpBind.o | |
897 | tkpButton.o tkpCanvas.o\*(R" | |
898 | .Sp | |
899 | (Where \s-1BASEEXT\s0 is the last component of \s-1NAME\s0, and \s-1OBJ_EXT\s0 is \f(CW$Config\fR{obj_ext}.) | |
900 | .IP "\s-1OPTIMIZE\s0" 2 | |
901 | .IX Item "OPTIMIZE" | |
902 | Defaults to \f(CW\*(C`\-O\*(C'\fR. Set it to \f(CW\*(C`\-g\*(C'\fR to turn debugging on. The flag is | |
903 | passed to subdirectory makes. | |
904 | .IP "\s-1PERL\s0" 2 | |
905 | .IX Item "PERL" | |
906 | Perl binary for tasks that can be done by miniperl | |
907 | .IP "\s-1PERL_CORE\s0" 2 | |
908 | .IX Item "PERL_CORE" | |
909 | Set only when MakeMaker is building the extensions of the Perl core | |
910 | distribution. | |
911 | .IP "\s-1PERLMAINCC\s0" 2 | |
912 | .IX Item "PERLMAINCC" | |
913 | The call to the program that is able to compile perlmain.c. Defaults | |
914 | to $(\s-1CC\s0). | |
915 | .IP "\s-1PERL_ARCHLIB\s0" 2 | |
916 | .IX Item "PERL_ARCHLIB" | |
917 | Same as for \s-1PERL_LIB\s0, but for architecture dependent files. | |
918 | .Sp | |
919 | Used only when MakeMaker is building the extensions of the Perl core | |
920 | distribution (because normally $(\s-1PERL_ARCHLIB\s0) is automatically in \f(CW@INC\fR, | |
921 | and adding it would get in the way of \s-1PERL5LIB\s0). | |
922 | .IP "\s-1PERL_LIB\s0" 2 | |
923 | .IX Item "PERL_LIB" | |
924 | Directory containing the Perl library to use. | |
925 | .Sp | |
926 | Used only when MakeMaker is building the extensions of the Perl core | |
927 | distribution (because normally $(\s-1PERL_LIB\s0) is automatically in \f(CW@INC\fR, | |
928 | and adding it would get in the way of \s-1PERL5LIB\s0). | |
929 | .IP "\s-1PERL_MALLOC_OK\s0" 2 | |
930 | .IX Item "PERL_MALLOC_OK" | |
931 | defaults to 0. Should be set to \s-1TRUE\s0 if the extension can work with | |
932 | the memory allocation routines substituted by the Perl \fImalloc()\fR subsystem. | |
933 | This should be applicable to most extensions with exceptions of those | |
934 | .RS 2 | |
935 | .IP "*" 4 | |
936 | with bugs in memory allocations which are caught by Perl's \fImalloc()\fR; | |
937 | .IP "*" 4 | |
938 | which interact with the memory allocator in other ways than via | |
939 | \&\fImalloc()\fR, \fIrealloc()\fR, \fIfree()\fR, \fIcalloc()\fR, \fIsbrk()\fR and \fIbrk()\fR; | |
940 | .IP "*" 4 | |
941 | which rely on special alignment which is not provided by Perl's \fImalloc()\fR. | |
942 | .RE | |
943 | .RS 2 | |
944 | .Sp | |
945 | \&\fB\s-1NOTE\s0.\fR Negligence to set this flag in \fIany one\fR of loaded extension | |
946 | nullifies many advantages of Perl's \fImalloc()\fR, such as better usage of | |
947 | system resources, error detection, memory usage reporting, catchable failure | |
948 | of memory allocations, etc. | |
949 | .RE | |
950 | .IP "\s-1PERLPREFIX\s0" 2 | |
951 | .IX Item "PERLPREFIX" | |
952 | Directory under which core modules are to be installed. | |
953 | .Sp | |
954 | Defaults to \f(CW$Config\fR{installprefixexp} falling back to | |
955 | \&\f(CW$Config\fR{installprefix}, \f(CW$Config\fR{prefixexp} or \f(CW$Config\fR{prefix} should | |
956 | \&\f(CW$Config\fR{installprefixexp} not exist. | |
957 | .Sp | |
958 | Overridden by \s-1PREFIX\s0. | |
959 | .IP "\s-1PERLRUN\s0" 2 | |
960 | .IX Item "PERLRUN" | |
961 | Use this instead of $(\s-1PERL\s0) when you wish to run perl. It will set up | |
962 | extra necessary flags for you. | |
963 | .IP "\s-1PERLRUNINST\s0" 2 | |
964 | .IX Item "PERLRUNINST" | |
965 | Use this instead of $(\s-1PERL\s0) when you wish to run perl to work with | |
966 | modules. It will add things like \-I$(\s-1INST_ARCH\s0) and other necessary | |
967 | flags so perl can see the modules you're about to install. | |
968 | .IP "\s-1PERL_SRC\s0" 2 | |
969 | .IX Item "PERL_SRC" | |
970 | Directory containing the Perl source code (use of this should be | |
971 | avoided, it may be undefined) | |
972 | .IP "\s-1PERM_RW\s0" 2 | |
973 | .IX Item "PERM_RW" | |
974 | Desired permission for read/writable files. Defaults to \f(CW644\fR. | |
975 | See also \*(L"perm_rw\*(R" in MM_Unix. | |
976 | .IP "\s-1PERM_RWX\s0" 2 | |
977 | .IX Item "PERM_RWX" | |
978 | Desired permission for executable files. Defaults to \f(CW755\fR. | |
979 | See also \*(L"perm_rwx\*(R" in MM_Unix. | |
980 | .IP "\s-1PL_FILES\s0" 2 | |
981 | .IX Item "PL_FILES" | |
982 | MakeMaker can run programs to generate files for you at build time. | |
983 | By default any file named *.PL (except Makefile.PL and Build.PL) in | |
984 | the top level directory will be assumed to be a Perl program and run | |
985 | passing its own basename in as an argument. For example... | |
986 | .Sp | |
987 | .Vb 1 | |
988 | \& perl foo.PL foo | |
989 | .Ve | |
990 | .Sp | |
991 | This behavior can be overridden by supplying your own set of files to | |
992 | search. \s-1PL_FILES\s0 accepts a hash ref, the key being the file to run | |
993 | and the value is passed in as the first argument when the \s-1PL\s0 file is run. | |
994 | .Sp | |
995 | .Vb 1 | |
996 | \& PL_FILES => {'bin/foobar.PL' => 'bin/foobar'} | |
997 | .Ve | |
998 | .Sp | |
999 | Would run bin/foobar.PL like this: | |
1000 | .Sp | |
1001 | .Vb 1 | |
1002 | \& perl bin/foobar.PL bin/foobar | |
1003 | .Ve | |
1004 | .Sp | |
1005 | If multiple files from one program are desired an array ref can be used. | |
1006 | .Sp | |
1007 | .Vb 1 | |
1008 | \& PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]} | |
1009 | .Ve | |
1010 | .Sp | |
1011 | In this case the program will be run multiple times using each target file. | |
1012 | .Sp | |
1013 | .Vb 2 | |
1014 | \& perl bin/foobar.PL bin/foobar1 | |
1015 | \& perl bin/foobar.PL bin/foobar2 | |
1016 | .Ve | |
1017 | .Sp | |
1018 | \&\s-1PL\s0 files are normally run \fBafter\fR pm_to_blib and include \s-1INST_LIB\s0 and | |
1019 | \&\s-1INST_ARCH\s0 in its \f(CW@INC\fR so the just built modules can be | |
1020 | accessed... unless the \s-1PL\s0 file is making a module (or anything else in | |
1021 | \&\s-1PM\s0) in which case it is run \fBbefore\fR pm_to_blib and does not include | |
1022 | \&\s-1INST_LIB\s0 and \s-1INST_ARCH\s0 in its \f(CW@INC\fR. This apparently odd behavior | |
1023 | is there for backwards compatibility (and its somewhat \s-1DWIM\s0). | |
1024 | .IP "\s-1PM\s0" 2 | |
1025 | .IX Item "PM" | |
1026 | Hashref of .pm files and *.pl files to be installed. e.g. | |
1027 | .Sp | |
1028 | .Vb 1 | |
1029 | \& {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'} | |
1030 | .Ve | |
1031 | .Sp | |
1032 | By default this will include *.pm and *.pl and the files found in | |
1033 | the \s-1PMLIBDIRS\s0 directories. Defining \s-1PM\s0 in the | |
1034 | Makefile.PL will override \s-1PMLIBDIRS\s0. | |
1035 | .IP "\s-1PMLIBDIRS\s0" 2 | |
1036 | .IX Item "PMLIBDIRS" | |
1037 | Ref to array of subdirectories containing library files. Defaults to | |
1038 | [ 'lib', $(\s-1BASEEXT\s0) ]. The directories will be scanned and \fIany\fR files | |
1039 | they contain will be installed in the corresponding location in the | |
1040 | library. A \fIlibscan()\fR method can be used to alter the behaviour. | |
1041 | Defining \s-1PM\s0 in the Makefile.PL will override \s-1PMLIBDIRS\s0. | |
1042 | .Sp | |
1043 | (Where \s-1BASEEXT\s0 is the last component of \s-1NAME\s0.) | |
1044 | .IP "\s-1PM_FILTER\s0" 2 | |
1045 | .IX Item "PM_FILTER" | |
1046 | A filter program, in the traditional Unix sense (input from stdin, output | |
1047 | to stdout) that is passed on each .pm file during the build (in the | |
1048 | \&\fIpm_to_blib()\fR phase). It is empty by default, meaning no filtering is done. | |
1049 | .Sp | |
1050 | Great care is necessary when defining the command if quoting needs to be | |
1051 | done. For instance, you would need to say: | |
1052 | .Sp | |
1053 | .Vb 1 | |
1054 | \& {'PM_FILTER' => 'grep -v \e\e"^\e\e#\e\e"'} | |
1055 | .Ve | |
1056 | .Sp | |
1057 | to remove all the leading coments on the fly during the build. The | |
1058 | extra \e\e are necessary, unfortunately, because this variable is interpolated | |
1059 | within the context of a Perl program built on the command line, and double | |
1060 | quotes are what is used with the \-e switch to build that command line. The | |
1061 | # is escaped for the Makefile, since what is going to be generated will then | |
1062 | be: | |
1063 | .Sp | |
1064 | .Vb 1 | |
1065 | \& PM_FILTER = grep -v \e"^\e#\e" | |
1066 | .Ve | |
1067 | .Sp | |
1068 | Without the \e\e before the #, we'd have the start of a Makefile comment, | |
1069 | and the macro would be incorrectly defined. | |
1070 | .IP "\s-1POLLUTE\s0" 2 | |
1071 | .IX Item "POLLUTE" | |
1072 | Release 5.005 grandfathered old global symbol names by providing preprocessor | |
1073 | macros for extension source compatibility. As of release 5.6, these | |
1074 | preprocessor definitions are not available by default. The \s-1POLLUTE\s0 flag | |
1075 | specifies that the old names should still be defined: | |
1076 | .Sp | |
1077 | .Vb 1 | |
1078 | \& perl Makefile.PL POLLUTE=1 | |
1079 | .Ve | |
1080 | .Sp | |
1081 | Please inform the module author if this is necessary to successfully install | |
1082 | a module under 5.6 or later. | |
1083 | .IP "\s-1PPM_INSTALL_EXEC\s0" 2 | |
1084 | .IX Item "PPM_INSTALL_EXEC" | |
1085 | Name of the executable used to run \f(CW\*(C`PPM_INSTALL_SCRIPT\*(C'\fR below. (e.g. perl) | |
1086 | .IP "\s-1PPM_INSTALL_SCRIPT\s0" 2 | |
1087 | .IX Item "PPM_INSTALL_SCRIPT" | |
1088 | Name of the script that gets executed by the Perl Package Manager after | |
1089 | the installation of a package. | |
1090 | .IP "\s-1PREFIX\s0" 2 | |
1091 | .IX Item "PREFIX" | |
1092 | This overrides all the default install locations. Man pages, | |
1093 | libraries, scripts, etc... MakeMaker will try to make an educated | |
1094 | guess about where to place things under the new \s-1PREFIX\s0 based on your | |
1095 | Config defaults. Failing that, it will fall back to a structure | |
1096 | which should be sensible for your platform. | |
1097 | .Sp | |
1098 | If you specify \s-1LIB\s0 or any INSTALL* variables they will not be effected | |
1099 | by the \s-1PREFIX\s0. | |
1100 | .IP "\s-1PREREQ_FATAL\s0" 2 | |
1101 | .IX Item "PREREQ_FATAL" | |
1102 | Bool. If this parameter is true, failing to have the required modules | |
1103 | (or the right versions thereof) will be fatal. perl Makefile.PL will die | |
1104 | with the proper message. | |
1105 | .Sp | |
1106 | Note: see Test::Harness for a shortcut for stopping tests early if | |
1107 | you are missing dependencies. | |
1108 | .Sp | |
1109 | Do \fInot\fR use this parameter for simple requirements, which could be resolved | |
1110 | at a later time, e.g. after an unsuccessful \fBmake test\fR of your module. | |
1111 | .Sp | |
1112 | It is \fIextremely\fR rare to have to use \f(CW\*(C`PREREQ_FATAL\*(C'\fR at all! | |
1113 | .IP "\s-1PREREQ_PM\s0" 2 | |
1114 | .IX Item "PREREQ_PM" | |
1115 | Hashref: Names of modules that need to be available to run this | |
1116 | extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the | |
1117 | desired version is the value. If the required version number is 0, we | |
1118 | only check if any version is installed already. | |
1119 | .IP "\s-1PREREQ_PRINT\s0" 2 | |
1120 | .IX Item "PREREQ_PRINT" | |
1121 | Bool. If this parameter is true, the prerequisites will be printed to | |
1122 | stdout and MakeMaker will exit. The output format is an evalable hash | |
1123 | ref. | |
1124 | .Sp | |
1125 | $PREREQ_PM = { | |
1126 | 'A::B' => Vers1, | |
1127 | 'C::D' => Vers2, | |
1128 | ... | |
1129 | }; | |
1130 | .IP "\s-1PRINT_PREREQ\s0" 2 | |
1131 | .IX Item "PRINT_PREREQ" | |
1132 | RedHatism for \f(CW\*(C`PREREQ_PRINT\*(C'\fR. The output format is different, though: | |
1133 | .Sp | |
1134 | .Vb 1 | |
1135 | \& perl(A::B)>=Vers1 perl(C::D)>=Vers2 ... | |
1136 | .Ve | |
1137 | .IP "\s-1SITEPREFIX\s0" 2 | |
1138 | .IX Item "SITEPREFIX" | |
1139 | Like \s-1PERLPREFIX\s0, but only for the site install locations. | |
1140 | .Sp | |
1141 | Defaults to \f(CW$Config\fR{siteprefixexp}. Perls prior to 5.6.0 didn't have | |
1142 | an explicit siteprefix in the Config. In those cases | |
1143 | \&\f(CW$Config\fR{installprefix} will be used. | |
1144 | .Sp | |
1145 | Overridable by \s-1PREFIX\s0 | |
1146 | .IP "\s-1SIGN\s0" 2 | |
1147 | .IX Item "SIGN" | |
1148 | When true, perform the generation and addition to the \s-1MANIFEST\s0 of the | |
1149 | \&\s-1SIGNATURE\s0 file in the distdir during 'make distdir', via 'cpansign | |
1150 | \&\-s'. | |
1151 | .Sp | |
1152 | Note that you need to install the Module::Signature module to | |
1153 | perform this operation. | |
1154 | .Sp | |
1155 | Defaults to false. | |
1156 | .IP "\s-1SKIP\s0" 2 | |
1157 | .IX Item "SKIP" | |
1158 | Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the | |
1159 | Makefile. Caution! Do not use the \s-1SKIP\s0 attribute for the negligible | |
1160 | speedup. It may seriously damage the resulting Makefile. Only use it | |
1161 | if you really need it. | |
1162 | .IP "\s-1TYPEMAPS\s0" 2 | |
1163 | .IX Item "TYPEMAPS" | |
1164 | Ref to array of typemap file names. Use this when the typemaps are | |
1165 | in some directory other than the current directory or when they are | |
1166 | not named \fBtypemap\fR. The last typemap in the list takes | |
1167 | precedence. A typemap in the current directory has highest | |
1168 | precedence, even if it isn't listed in \s-1TYPEMAPS\s0. The default system | |
1169 | typemap has lowest precedence. | |
1170 | .IP "\s-1VENDORPREFIX\s0" 2 | |
1171 | .IX Item "VENDORPREFIX" | |
1172 | Like \s-1PERLPREFIX\s0, but only for the vendor install locations. | |
1173 | .Sp | |
1174 | Defaults to \f(CW$Config\fR{vendorprefixexp}. | |
1175 | .Sp | |
1176 | Overridable by \s-1PREFIX\s0 | |
1177 | .IP "\s-1VERBINST\s0" 2 | |
1178 | .IX Item "VERBINST" | |
1179 | If true, make install will be verbose | |
1180 | .IP "\s-1VERSION\s0" 2 | |
1181 | .IX Item "VERSION" | |
1182 | Your version number for distributing the package. This defaults to | |
1183 | 0.1. | |
1184 | .IP "\s-1VERSION_FROM\s0" 2 | |
1185 | .IX Item "VERSION_FROM" | |
1186 | Instead of specifying the \s-1VERSION\s0 in the Makefile.PL you can let | |
1187 | MakeMaker parse a file to determine the version number. The parsing | |
1188 | routine requires that the file named by \s-1VERSION_FROM\s0 contains one | |
1189 | single line to compute the version number. The first line in the file | |
1190 | that contains the regular expression | |
1191 | .Sp | |
1192 | .Vb 1 | |
1193 | \& /([\e$*])(([\ew\e:\e']*)\ebVERSION)\eb.*\e=/ | |
1194 | .Ve | |
1195 | .Sp | |
1196 | will be evaluated with \fIeval()\fR and the value of the named variable | |
1197 | \&\fBafter\fR the \fIeval()\fR will be assigned to the \s-1VERSION\s0 attribute of the | |
1198 | MakeMaker object. The following lines will be parsed o.k.: | |
1199 | .Sp | |
1200 | .Vb 6 | |
1201 | \& $VERSION = '1.00'; | |
1202 | \& *VERSION = \e'1.01'; | |
1203 | \& $VERSION = sprintf "%d.%03d", q$Revision: 4535 $ =~ /(\ed+)/g; | |
1204 | \& $FOO::VERSION = '1.10'; | |
1205 | \& *FOO::VERSION = \e'1.11'; | |
1206 | \& our $VERSION = 1.2.3; # new for perl5.6.0 | |
1207 | .Ve | |
1208 | .Sp | |
1209 | but these will fail: | |
1210 | .Sp | |
1211 | .Vb 3 | |
1212 | \& my $VERSION = '1.01'; | |
1213 | \& local $VERSION = '1.02'; | |
1214 | \& local $FOO::VERSION = '1.30'; | |
1215 | .Ve | |
1216 | .Sp | |
1217 | (Putting \f(CW\*(C`my\*(C'\fR or \f(CW\*(C`local\*(C'\fR on the preceding line will work o.k.) | |
1218 | .Sp | |
1219 | The file named in \s-1VERSION_FROM\s0 is not added as a dependency to | |
1220 | Makefile. This is not really correct, but it would be a major pain | |
1221 | during development to have to rewrite the Makefile for any smallish | |
1222 | change in that file. If you want to make sure that the Makefile | |
1223 | contains the correct \s-1VERSION\s0 macro after any change of the file, you | |
1224 | would have to do something like | |
1225 | .Sp | |
1226 | .Vb 1 | |
1227 | \& depend => { Makefile => '$(VERSION_FROM)' } | |
1228 | .Ve | |
1229 | .Sp | |
1230 | See attribute \f(CW\*(C`depend\*(C'\fR below. | |
1231 | .IP "\s-1VERSION_SYM\s0" 2 | |
1232 | .IX Item "VERSION_SYM" | |
1233 | A sanitized \s-1VERSION\s0 with . replaced by _. For places where . has | |
1234 | special meaning (some filesystems, \s-1RCS\s0 labels, etc...) | |
1235 | .IP "\s-1XS\s0" 2 | |
1236 | .IX Item "XS" | |
1237 | Hashref of .xs files. MakeMaker will default this. e.g. | |
1238 | .Sp | |
1239 | .Vb 1 | |
1240 | \& {'name_of_file.xs' => 'name_of_file.c'} | |
1241 | .Ve | |
1242 | .Sp | |
1243 | The .c files will automatically be included in the list of files | |
1244 | deleted by a make clean. | |
1245 | .IP "\s-1XSOPT\s0" 2 | |
1246 | .IX Item "XSOPT" | |
1247 | String of options to pass to xsubpp. This might include \f(CW\*(C`\-C++\*(C'\fR or | |
1248 | \&\f(CW\*(C`\-extern\*(C'\fR. Do not include typemaps here; the \s-1TYPEMAP\s0 parameter exists for | |
1249 | that purpose. | |
1250 | .IP "\s-1XSPROTOARG\s0" 2 | |
1251 | .IX Item "XSPROTOARG" | |
1252 | May be set to an empty string, which is identical to \f(CW\*(C`\-prototypes\*(C'\fR, or | |
1253 | \&\f(CW\*(C`\-noprototypes\*(C'\fR. See the xsubpp documentation for details. MakeMaker | |
1254 | defaults to the empty string. | |
1255 | .IP "\s-1XS_VERSION\s0" 2 | |
1256 | .IX Item "XS_VERSION" | |
1257 | Your version number for the .xs file of this package. This defaults | |
1258 | to the value of the \s-1VERSION\s0 attribute. | |
1259 | .Sh "Additional lowercase attributes" | |
1260 | .IX Subsection "Additional lowercase attributes" | |
1261 | can be used to pass parameters to the methods which implement that | |
1262 | part of the Makefile. Parameters are specified as a hash ref but are | |
1263 | passed to the method as a hash. | |
1264 | .IP "clean" 2 | |
1265 | .IX Item "clean" | |
1266 | .Vb 1 | |
1267 | \& {FILES => "*.xyz foo"} | |
1268 | .Ve | |
1269 | .IP "depend" 2 | |
1270 | .IX Item "depend" | |
1271 | .Vb 1 | |
1272 | \& {ANY_TARGET => ANY_DEPENDECY, ...} | |
1273 | .Ve | |
1274 | .Sp | |
1275 | (\s-1ANY_TARGET\s0 must not be given a double-colon rule by MakeMaker.) | |
1276 | .IP "dist" 2 | |
1277 | .IX Item "dist" | |
1278 | .Vb 3 | |
1279 | \& {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz', | |
1280 | \& SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip', | |
1281 | \& ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' } | |
1282 | .Ve | |
1283 | .Sp | |
1284 | If you specify \s-1COMPRESS\s0, then \s-1SUFFIX\s0 should also be altered, as it is | |
1285 | needed to tell make the target file of the compression. Setting | |
1286 | \&\s-1DIST_CP\s0 to ln can be useful, if you need to preserve the timestamps on | |
1287 | your files. \s-1DIST_CP\s0 can take the values 'cp', which copies the file, | |
1288 | \&'ln', which links the file, and 'best' which copies symbolic links and | |
1289 | links the rest. Default is 'best'. | |
1290 | .IP "dynamic_lib" 2 | |
1291 | .IX Item "dynamic_lib" | |
1292 | .Vb 1 | |
1293 | \& {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'} | |
1294 | .Ve | |
1295 | .IP "linkext" 2 | |
1296 | .IX Item "linkext" | |
1297 | .Vb 1 | |
1298 | \& {LINKTYPE => 'static', 'dynamic' or ''} | |
1299 | .Ve | |
1300 | .Sp | |
1301 | \&\s-1NB:\s0 Extensions that have nothing but *.pm files had to say | |
1302 | .Sp | |
1303 | .Vb 1 | |
1304 | \& {LINKTYPE => ''} | |
1305 | .Ve | |
1306 | .Sp | |
1307 | with Pre\-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line | |
1308 | can be deleted safely. MakeMaker recognizes when there's nothing to | |
1309 | be linked. | |
1310 | .IP "macro" 2 | |
1311 | .IX Item "macro" | |
1312 | .Vb 1 | |
1313 | \& {ANY_MACRO => ANY_VALUE, ...} | |
1314 | .Ve | |
1315 | .IP "postamble" 2 | |
1316 | .IX Item "postamble" | |
1317 | Anything put here will be passed to \fIMY::postamble()\fR if you have one. | |
1318 | .IP "realclean" 2 | |
1319 | .IX Item "realclean" | |
1320 | .Vb 1 | |
1321 | \& {FILES => '$(INST_ARCHAUTODIR)/*.xyz'} | |
1322 | .Ve | |
1323 | .IP "test" 2 | |
1324 | .IX Item "test" | |
1325 | .Vb 1 | |
1326 | \& {TESTS => 't/*.t'} | |
1327 | .Ve | |
1328 | .IP "tool_autosplit" 2 | |
1329 | .IX Item "tool_autosplit" | |
1330 | .Vb 1 | |
1331 | \& {MAXLEN => 8} | |
1332 | .Ve | |
1333 | .Sh "Overriding MakeMaker Methods" | |
1334 | .IX Subsection "Overriding MakeMaker Methods" | |
1335 | If you cannot achieve the desired Makefile behaviour by specifying | |
1336 | attributes you may define private subroutines in the Makefile.PL. | |
1337 | Each subroutine returns the text it wishes to have written to | |
1338 | the Makefile. To override a section of the Makefile you can | |
1339 | either say: | |
1340 | .PP | |
1341 | .Vb 1 | |
1342 | \& sub MY::c_o { "new literal text" } | |
1343 | .Ve | |
1344 | .PP | |
1345 | or you can edit the default by saying something like: | |
1346 | .PP | |
1347 | .Vb 6 | |
1348 | \& package MY; # so that "SUPER" works right | |
1349 | \& sub c_o { | |
1350 | \& my $inherited = shift->SUPER::c_o(@_); | |
1351 | \& $inherited =~ s/old text/new text/; | |
1352 | \& $inherited; | |
1353 | \& } | |
1354 | .Ve | |
1355 | .PP | |
1356 | If you are running experiments with embedding perl as a library into | |
1357 | other applications, you might find MakeMaker is not sufficient. You'd | |
1358 | better have a look at ExtUtils::Embed which is a collection of utilities | |
1359 | for embedding. | |
1360 | .PP | |
1361 | If you still need a different solution, try to develop another | |
1362 | subroutine that fits your needs and submit the diffs to | |
1363 | \&\f(CW\*(C`makemaker@perl.org\*(C'\fR | |
1364 | .PP | |
1365 | For a complete description of all MakeMaker methods see | |
1366 | ExtUtils::MM_Unix. | |
1367 | .PP | |
1368 | Here is a simple example of how to add a new target to the generated | |
1369 | Makefile: | |
1370 | .PP | |
1371 | .Vb 4 | |
1372 | \& sub MY::postamble { | |
1373 | \& return <<'MAKE_FRAG'; | |
1374 | \& $(MYEXTLIB): sdbm/Makefile | |
1375 | \& cd sdbm && $(MAKE) all | |
1376 | .Ve | |
1377 | .PP | |
1378 | .Vb 2 | |
1379 | \& MAKE_FRAG | |
1380 | \& } | |
1381 | .Ve | |
1382 | .Sh "The End Of Cargo Cult Programming" | |
1383 | .IX Subsection "The End Of Cargo Cult Programming" | |
1384 | \&\fIWriteMakefile()\fR now does some basic sanity checks on its parameters to | |
1385 | protect against typos and malformatted values. This means some things | |
1386 | which happened to work in the past will now throw warnings and | |
1387 | possibly produce internal errors. | |
1388 | .PP | |
1389 | Some of the most common mistakes: | |
1390 | .ie n .IP """MAN3PODS => ' '""" 2 | |
1391 | .el .IP "\f(CWMAN3PODS => ' '\fR" 2 | |
1392 | .IX Item "MAN3PODS => ' '" | |
1393 | This is commonly used to supress the creation of man pages. \s-1MAN3PODS\s0 | |
1394 | takes a hash ref not a string, but the above worked by accident in old | |
1395 | versions of MakeMaker. | |
1396 | .Sp | |
1397 | The correct code is \f(CW\*(C`MAN3PODS => { }\*(C'\fR. | |
1398 | .Sh "Hintsfile support" | |
1399 | .IX Subsection "Hintsfile support" | |
1400 | MakeMaker.pm uses the architecture specific information from | |
1401 | Config.pm. In addition it evaluates architecture specific hints files | |
1402 | in a \f(CW\*(C`hints/\*(C'\fR directory. The hints files are expected to be named | |
1403 | like their counterparts in \f(CW\*(C`PERL_SRC/hints\*(C'\fR, but with an \f(CW\*(C`.pl\*(C'\fR file | |
1404 | name extension (eg. \f(CW\*(C`next_3_2.pl\*(C'\fR). They are simply \f(CW\*(C`eval\*(C'\fRed by | |
1405 | MakeMaker within the \fIWriteMakefile()\fR subroutine, and can be used to | |
1406 | execute commands as well as to include special variables. The rules | |
1407 | which hintsfile is chosen are the same as in Configure. | |
1408 | .PP | |
1409 | The hintsfile is \fIeval()\fRed immediately after the arguments given to | |
1410 | WriteMakefile are stuffed into a hash reference \f(CW$self\fR but before this | |
1411 | reference becomes blessed. So if you want to do the equivalent to | |
1412 | override or create an attribute you would say something like | |
1413 | .PP | |
1414 | .Vb 1 | |
1415 | \& $self->{LIBS} = ['-ldbm -lucb -lc']; | |
1416 | .Ve | |
1417 | .Sh "Distribution Support" | |
1418 | .IX Subsection "Distribution Support" | |
1419 | For authors of extensions MakeMaker provides several Makefile | |
1420 | targets. Most of the support comes from the ExtUtils::Manifest module, | |
1421 | where additional documentation can be found. | |
1422 | .IP "make distcheck" 4 | |
1423 | .IX Item "make distcheck" | |
1424 | reports which files are below the build directory but not in the | |
1425 | \&\s-1MANIFEST\s0 file and vice versa. (See \fIExtUtils::Manifest::fullcheck()\fR for | |
1426 | details) | |
1427 | .IP "make skipcheck" 4 | |
1428 | .IX Item "make skipcheck" | |
1429 | reports which files are skipped due to the entries in the | |
1430 | \&\f(CW\*(C`MANIFEST.SKIP\*(C'\fR file (See \fIExtUtils::Manifest::skipcheck()\fR for | |
1431 | details) | |
1432 | .IP "make distclean" 4 | |
1433 | .IX Item "make distclean" | |
1434 | does a realclean first and then the distcheck. Note that this is not | |
1435 | needed to build a new distribution as long as you are sure that the | |
1436 | \&\s-1MANIFEST\s0 file is ok. | |
1437 | .IP "make manifest" 4 | |
1438 | .IX Item "make manifest" | |
1439 | rewrites the \s-1MANIFEST\s0 file, adding all remaining files found (See | |
1440 | \&\fIExtUtils::Manifest::mkmanifest()\fR for details) | |
1441 | .IP "make distdir" 4 | |
1442 | .IX Item "make distdir" | |
1443 | Copies all the files that are in the \s-1MANIFEST\s0 file to a newly created | |
1444 | directory with the name \f(CW\*(C`$(DISTNAME)\-$(VERSION)\*(C'\fR. If that directory | |
1445 | exists, it will be removed first. | |
1446 | .Sp | |
1447 | Additionally, it will create a \s-1META\s0.yml module meta-data file in the | |
1448 | distdir and add this to the distdir's \s-1MANFIEST\s0. You can shut this | |
1449 | behavior off with the \s-1NO_META\s0 flag. | |
1450 | .IP "make disttest" 4 | |
1451 | .IX Item "make disttest" | |
1452 | Makes a distdir first, and runs a \f(CW\*(C`perl Makefile.PL\*(C'\fR, a make, and | |
1453 | a make test in that directory. | |
1454 | .IP "make tardist" 4 | |
1455 | .IX Item "make tardist" | |
1456 | First does a distdir. Then a command $(\s-1PREOP\s0) which defaults to a null | |
1457 | command, followed by $(\s-1TOUNIX\s0), which defaults to a null command under | |
1458 | \&\s-1UNIX\s0, and will convert files in distribution directory to \s-1UNIX\s0 format | |
1459 | otherwise. Next it runs \f(CW\*(C`tar\*(C'\fR on that directory into a tarfile and | |
1460 | deletes the directory. Finishes with a command $(\s-1POSTOP\s0) which | |
1461 | defaults to a null command. | |
1462 | .IP "make dist" 4 | |
1463 | .IX Item "make dist" | |
1464 | Defaults to $(\s-1DIST_DEFAULT\s0) which in turn defaults to tardist. | |
1465 | .IP "make uutardist" 4 | |
1466 | .IX Item "make uutardist" | |
1467 | Runs a tardist first and uuencodes the tarfile. | |
1468 | .IP "make shdist" 4 | |
1469 | .IX Item "make shdist" | |
1470 | First does a distdir. Then a command $(\s-1PREOP\s0) which defaults to a null | |
1471 | command. Next it runs \f(CW\*(C`shar\*(C'\fR on that directory into a sharfile and | |
1472 | deletes the intermediate directory again. Finishes with a command | |
1473 | $(\s-1POSTOP\s0) which defaults to a null command. Note: For shdist to work | |
1474 | properly a \f(CW\*(C`shar\*(C'\fR program that can handle directories is mandatory. | |
1475 | .IP "make zipdist" 4 | |
1476 | .IX Item "make zipdist" | |
1477 | First does a distdir. Then a command $(\s-1PREOP\s0) which defaults to a null | |
1478 | command. Runs \f(CW\*(C`$(ZIP) $(ZIPFLAGS)\*(C'\fR on that directory into a | |
1479 | zipfile. Then deletes that directory. Finishes with a command | |
1480 | $(\s-1POSTOP\s0) which defaults to a null command. | |
1481 | .IP "make ci" 4 | |
1482 | .IX Item "make ci" | |
1483 | Does a $(\s-1CI\s0) and a $(\s-1RCS_LABEL\s0) on all files in the \s-1MANIFEST\s0 file. | |
1484 | .PP | |
1485 | Customization of the dist targets can be done by specifying a hash | |
1486 | reference to the dist attribute of the WriteMakefile call. The | |
1487 | following parameters are recognized: | |
1488 | .PP | |
1489 | .Vb 12 | |
1490 | \& CI ('ci -u') | |
1491 | \& COMPRESS ('gzip --best') | |
1492 | \& POSTOP ('@ :') | |
1493 | \& PREOP ('@ :') | |
1494 | \& TO_UNIX (depends on the system) | |
1495 | \& RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):') | |
1496 | \& SHAR ('shar') | |
1497 | \& SUFFIX ('.gz') | |
1498 | \& TAR ('tar') | |
1499 | \& TARFLAGS ('cvf') | |
1500 | \& ZIP ('zip') | |
1501 | \& ZIPFLAGS ('-r') | |
1502 | .Ve | |
1503 | .PP | |
1504 | An example: | |
1505 | .PP | |
1506 | .Vb 1 | |
1507 | \& WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" }) | |
1508 | .Ve | |
1509 | .Sh "Module Meta-Data" | |
1510 | .IX Subsection "Module Meta-Data" | |
1511 | Long plaguing users of MakeMaker based modules has been the problem of | |
1512 | getting basic information about the module out of the sources | |
1513 | \&\fIwithout\fR running the \fIMakefile.PL\fR and doing a bunch of messy | |
1514 | heuristics on the resulting \fIMakefile\fR. To this end a simple module | |
1515 | meta-data file has been introduced, \fI\s-1META\s0.yml\fR. | |
1516 | .PP | |
1517 | \&\fI\s-1META\s0.yml\fR is a \s-1YAML\s0 document (see http://www.yaml.org) containing | |
1518 | basic information about the module (name, version, prerequisites...) | |
1519 | in an easy to read format. The format is developed and defined by the | |
1520 | Module::Build developers (see | |
1521 | http://module\-build.sourceforge.net/META\-spec.html) | |
1522 | .PP | |
1523 | MakeMaker will automatically generate a \fI\s-1META\s0.yml\fR file for you and | |
1524 | add it to your \fI\s-1MANIFEST\s0\fR as part of the 'distdir' target (and thus | |
1525 | the 'dist' target). This is intended to seamlessly and rapidly | |
1526 | populate \s-1CPAN\s0 with module meta\-data. If you wish to shut this feature | |
1527 | off, set the \f(CW\*(C`NO_META\*(C'\fR \f(CW\*(C`WriteMakefile()\*(C'\fR flag to true. | |
1528 | .Sh "Disabling an extension" | |
1529 | .IX Subsection "Disabling an extension" | |
1530 | If some events detected in \fIMakefile.PL\fR imply that there is no way | |
1531 | to create the Module, but this is a normal state of things, then you | |
1532 | can create a \fIMakefile\fR which does nothing, but succeeds on all the | |
1533 | \&\*(L"usual\*(R" build targets. To do so, use | |
1534 | .PP | |
1535 | .Vb 1 | |
1536 | \& ExtUtils::MakeMaker::WriteEmptyMakefile(); | |
1537 | .Ve | |
1538 | .PP | |
1539 | instead of \fIWriteMakefile()\fR. | |
1540 | .PP | |
1541 | This may be useful if other modules expect this module to be \fIbuilt\fR | |
1542 | \&\s-1OK\s0, as opposed to \fIwork\fR \s-1OK\s0 (say, this system-dependent module builds | |
1543 | in a subdirectory of some other distribution, or is listed as a | |
1544 | dependency in a CPAN::Bundle, but the functionality is supported by | |
1545 | different means on the current architecture). | |
1546 | .Sh "Other Handy Functions" | |
1547 | .IX Subsection "Other Handy Functions" | |
1548 | .IP "prompt" 4 | |
1549 | .IX Item "prompt" | |
1550 | .Vb 2 | |
1551 | \& my $value = prompt($message); | |
1552 | \& my $value = prompt($message, $default); | |
1553 | .Ve | |
1554 | .Sp | |
1555 | The \f(CW\*(C`prompt()\*(C'\fR function provides an easy way to request user input | |
1556 | used to write a makefile. It displays the \f(CW$message\fR as a prompt for | |
1557 | input. If a \f(CW$default\fR is provided it will be used as a default. The | |
1558 | function returns the \f(CW$value\fR selected by the user. | |
1559 | .Sp | |
1560 | If \f(CW\*(C`prompt()\*(C'\fR detects that it is not running interactively and there | |
1561 | is nothing on \s-1STDIN\s0 or if the \s-1PERL_MM_USE_DEFAULT\s0 environment variable | |
1562 | is set to true, the \f(CW$default\fR will be used without prompting. This | |
1563 | prevents automated processes from blocking on user input. | |
1564 | .Sp | |
1565 | If no \f(CW$default\fR is provided an empty string will be used instead. | |
1566 | .SH "ENVIRONMENT" | |
1567 | .IX Header "ENVIRONMENT" | |
1568 | .IP "\s-1PERL_MM_OPT\s0" 4 | |
1569 | .IX Item "PERL_MM_OPT" | |
1570 | Command line options used by \f(CW\*(C`MakeMaker\->new()\*(C'\fR, and thus by | |
1571 | \&\f(CW\*(C`WriteMakefile()\*(C'\fR. The string is split on whitespace, and the result | |
1572 | is processed before any actual command line arguments are processed. | |
1573 | .IP "\s-1PERL_MM_USE_DEFAULT\s0" 4 | |
1574 | .IX Item "PERL_MM_USE_DEFAULT" | |
1575 | If set to a true value then MakeMaker's prompt function will | |
1576 | always return the default without waiting for user input. | |
1577 | .IP "\s-1PERL_CORE\s0" 4 | |
1578 | .IX Item "PERL_CORE" | |
1579 | Same as the \s-1PERL_CORE\s0 parameter. The parameter overrides this. | |
1580 | .SH "SEE ALSO" | |
1581 | .IX Header "SEE ALSO" | |
1582 | ExtUtils::MM_Unix, ExtUtils::Manifest ExtUtils::Install, | |
1583 | ExtUtils::Embed | |
1584 | .SH "AUTHORS" | |
1585 | .IX Header "AUTHORS" | |
1586 | Andy Dougherty \f(CW\*(C`doughera@lafayette.edu\*(C'\fR, Andreas Ko\*:nig | |
1587 | \&\f(CW\*(C`andreas.koenig@mind.de\*(C'\fR, Tim Bunce \f(CW\*(C`timb@cpan.org\*(C'\fR. \s-1VMS\s0 | |
1588 | support by Charles Bailey \f(CW\*(C`bailey@newman.upenn.edu\*(C'\fR. \s-1OS/2\s0 support | |
1589 | by Ilya Zakharevich \f(CW\*(C`ilya@math.ohio\-state.edu\*(C'\fR. | |
1590 | .PP | |
1591 | Currently maintained by Michael G Schwern \f(CW\*(C`schwern@pobox.com\*(C'\fR | |
1592 | .PP | |
1593 | Send patches and ideas to \f(CW\*(C`makemaker@perl.org\*(C'\fR. | |
1594 | .PP | |
1595 | Send bug reports via http://rt.cpan.org/. Please send your | |
1596 | generated Makefile along with your report. | |
1597 | .PP | |
1598 | For more up-to-date information, see <http://www.makemaker.org>. | |
1599 | .SH "LICENSE" | |
1600 | .IX Header "LICENSE" | |
1601 | This program is free software; you can redistribute it and/or | |
1602 | modify it under the same terms as Perl itself. | |
1603 | .PP | |
1604 | See <http://www.perl.com/perl/misc/Artistic.html> |