Debian Codegraph @

upstream/mageia-cauldron/man3pm/ExtUtils::MakeMaker.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "ExtUtils::MakeMaker 3pm"
61 .TH ExtUtils::MakeMaker 3pm 2026-05-26 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 ExtUtils::MakeMaker \- Create a module Makefile
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use ExtUtils::MakeMaker;
72 \&
73 \& WriteMakefile(
74 \& NAME => "Foo::Bar",
75 \& VERSION_FROM => "lib/Foo/Bar.pm",
76 \& );
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 This utility is designed to write a Makefile for an extension module
81 from a Makefile.PL. It is based on the Makefile.SH model provided by
82 Andy Dougherty and the perl5\-porters.
83 .PP
84 It splits the task of generating the Makefile into several subroutines
85 that can be individually overridden. Each subroutine returns the text
86 it wishes to have written to the Makefile.
87 .PP
88 As there are various Make programs with incompatible syntax, which
89 use operating system shells, again with incompatible syntax, it is
90 important for users of this module to know which flavour of Make
91 a Makefile has been written for so they\*(Aqll use the correct one and
92 won\*(Aqt have to face the possibly bewildering errors resulting from
93 using the wrong one.
94 .PP
95 On POSIX systems, that program will likely be GNU Make; on Microsoft
96 Windows, it will be either Microsoft NMake, DMake or GNU Make.
97 See the section on the "MAKE" parameter for details.
98 .PP
99 ExtUtils::MakeMaker (EUMM) is object oriented. Each directory below the current
100 directory that contains a Makefile.PL is treated as a separate
101 object. This makes it possible to write an unlimited number of
102 Makefiles with a single invocation of \fBWriteMakefile()\fR.
103 .PP
104 All inputs to WriteMakefile are Unicode characters, not just octets. EUMM
105 seeks to handle all of these correctly. It is currently still not possible
106 to portably use Unicode characters in module names, because this requires
107 Perl to handle Unicode filenames, which is not yet the case on Windows.
108 .PP
109 See ExtUtils::MakeMaker::FAQ for details of the design and usage.
110 .SS "How To Write A Makefile.PL"
111 .IX Subsection "How To Write A Makefile.PL"
112 See ExtUtils::MakeMaker::Tutorial.
113 .PP
114 The long answer is the rest of the manpage :\-)
115 .SS "Default Makefile Behaviour"
116 .IX Subsection "Default Makefile Behaviour"
117 The generated Makefile enables the user of the extension to invoke
118 .PP
119 .Vb 4
120 \& perl Makefile.PL # optionally "perl Makefile.PL verbose"
121 \& make
122 \& make test # optionally set TEST_VERBOSE=1
123 \& make install # See below
124 .Ve
125 .PP
126 The Makefile to be produced may be altered by adding arguments of the
127 form \f(CW\*(C`KEY=VALUE\*(C'\fR. E.g.
128 .PP
129 .Vb 1
130 \& perl Makefile.PL INSTALL_BASE=~
131 .Ve
132 .PP
133 Other interesting targets in the generated Makefile are
134 .PP
135 .Vb 5
136 \& make config # to check if the Makefile is up\-to\-date
137 \& make clean # delete local temp files (Makefile gets renamed)
138 \& make realclean # delete derived files (including ./blib)
139 \& make ci # check in all the files in the MANIFEST file
140 \& make dist # see below the Distribution Support section
141 .Ve
142 .SS "make test"
143 .IX Subsection "make test"
144 MakeMaker checks for the existence of a file named \fItest.pl\fR in the
145 current directory, and if it exists it executes the script with the
146 proper set of perl \f(CW\*(C`\-I\*(C'\fR options.
147 .PP
148 MakeMaker also checks for any files matching glob("t/*.t"). It will
149 execute all matching files in alphabetical order via the
150 Test::Harness module with the \f(CW\*(C`\-I\*(C'\fR switches set correctly.
151 .PP
152 You can also organize your tests within subdirectories in the \fIt/\fR directory.
153 To do so, use the \fItest\fR directive in your \fIMakefile.PL\fR. For example, if you
154 had tests in:
155 .PP
156 .Vb 2
157 \& t/foo
158 \& t/foo/bar
159 .Ve
160 .PP
161 You could tell make to run tests in both of those directories with the
162 following directives:
163 .PP
164 .Vb 2
165 \& test => {TESTS => \*(Aqt/*/*.t t/*/*/*.t\*(Aq}
166 \& test => {TESTS => \*(Aqt/foo/*.t t/foo/bar/*.t\*(Aq}
167 .Ve
168 .PP
169 The first will run all test files in all first\-level subdirectories and all
170 subdirectories they contain. The second will run tests in only the \fIt/foo\fR
171 and \fIt/foo/bar\fR.
172 .PP
173 If you\*(Aqd like to see the raw output of your tests, set the
174 \&\f(CW\*(C`TEST_VERBOSE\*(C'\fR variable to true.
175 .PP
176 .Vb 1
177 \& make test TEST_VERBOSE=1
178 .Ve
179 .PP
180 If you want to run particular test files, set the \f(CW\*(C`TEST_FILES\*(C'\fR variable.
181 It is possible to use globbing with this mechanism.
182 .PP
183 .Vb 1
184 \& make test TEST_FILES=\*(Aqt/foobar.t t/dagobah*.t\*(Aq
185 .Ve
186 .PP
187 Windows users who are using \f(CW\*(C`nmake\*(C'\fR should note that due to a bug in \f(CW\*(C`nmake\*(C'\fR,
188 when specifying \f(CW\*(C`TEST_FILES\*(C'\fR you must use back\-slashes instead of forward\-slashes.
189 .PP
190 .Vb 1
191 \& nmake test TEST_FILES=\*(Aqt\efoobar.t t\edagobah*.t\*(Aq
192 .Ve
193 .SS "make testdb"
194 .IX Subsection "make testdb"
195 A useful variation of the above is the target \f(CW\*(C`testdb\*(C'\fR. It runs the
196 test under the Perl debugger (see perldebug). If the file
197 \&\fItest.pl\fR exists in the current directory, it is used for the test.
198 .PP
199 If you want to debug some other testfile, set the \f(CW\*(C`TEST_FILE\*(C'\fR variable
200 thusly:
201 .PP
202 .Vb 1
203 \& make testdb TEST_FILE=t/mytest.t
204 .Ve
205 .PP
206 By default the debugger is called using \f(CW\*(C`\-d\*(C'\fR option to perl. If you
207 want to specify some other option, set the \f(CW\*(C`TESTDB_SW\*(C'\fR variable:
208 .PP
209 .Vb 1
210 \& make testdb TESTDB_SW=\-Dx
211 .Ve
212 .SS "make install"
213 .IX Subsection "make install"
214 make alone puts all relevant files into directories that are named by
215 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
216 INST_MAN3DIR. All these default to something below ./blib if you are
217 \&\fInot\fR building below the perl source directory. If you \fIare\fR
218 building below the perl source, INST_LIB and INST_ARCHLIB default to
219 \&../../lib, and INST_SCRIPT is not defined.
220 .PP
221 The \fIinstall\fR target of the generated Makefile copies the files found
222 below each of the INST_* directories to their INSTALL*
223 counterparts. Which counterparts are chosen depends on the setting of
224 INSTALLDIRS according to the following table:
225 .PP
226 .Vb 2
227 \& INSTALLDIRS set to
228 \& perl site vendor
229 \&
230 \& PERLPREFIX SITEPREFIX VENDORPREFIX
231 \& INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
232 \& INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
233 \& INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
234 \& INST_SCRIPT INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
235 \& INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
236 \& INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
237 .Ve
238 .PP
239 The INSTALL... macros in turn default to their \f(CW%Config\fR
240 ($Config{installprivlib}, \f(CW$Config\fR{installarchlib}, etc.) counterparts.
241 .PP
242 You can check the values of these variables on your system with
243 .PP
244 .Vb 1
245 \& perl \*(Aq\-V:install.*\*(Aq
246 .Ve
247 .PP
248 And to check the sequence in which the library directories are
249 searched by perl, run
250 .PP
251 .Vb 1
252 \& perl \-le \*(Aqprint join $/, @INC\*(Aq
253 .Ve
254 .PP
255 Sometimes older versions of the module you\*(Aqre installing live in other
256 directories in \f(CW@INC\fR. Because Perl loads the first version of a module it
257 finds, not the newest, you might accidentally get one of these older
258 versions even after installing a brand new version. To delete \fIall other
259 versions of the module you\*(Aqre installing\fR (not simply older ones) set the
260 \&\f(CW\*(C`UNINST\*(C'\fR variable.
261 .PP
262 .Vb 1
263 \& make install UNINST=1
264 .Ve
265 .SS INSTALL_BASE
266 .IX Subsection "INSTALL_BASE"
267 INSTALL_BASE can be passed into Makefile.PL to change where your
268 module will be installed. INSTALL_BASE is more like what everyone
269 else calls "prefix" than PREFIX is.
270 .PP
271 To have everything installed in your home directory, do the following.
272 .PP
273 .Vb 2
274 \& # Unix users, INSTALL_BASE=~ works fine
275 \& perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
276 .Ve
277 .PP
278 Like PREFIX, it sets several INSTALL* attributes at once. Unlike
279 PREFIX it is easy to predict where the module will end up. The
280 installation pattern looks like this:
281 .PP
282 .Vb 6
283 \& INSTALLARCHLIB INSTALL_BASE/lib/perl5/$Config{archname}
284 \& INSTALLPRIVLIB INSTALL_BASE/lib/perl5
285 \& INSTALLBIN INSTALL_BASE/bin
286 \& INSTALLSCRIPT INSTALL_BASE/bin
287 \& INSTALLMAN1DIR INSTALL_BASE/man/man1
288 \& INSTALLMAN3DIR INSTALL_BASE/man/man3
289 .Ve
290 .PP
291 INSTALL_BASE in MakeMaker and \f(CW\*(C`\-\-install_base\*(C'\fR in Module::Build (as
292 of 0.28) install to the same location. If you want MakeMaker and
293 Module::Build to install to the same location simply set INSTALL_BASE
294 and \f(CW\*(C`\-\-install_base\*(C'\fR to the same location.
295 .PP
296 INSTALL_BASE was added in 6.31.
297 .SS "PREFIX and LIB attribute"
298 .IX Subsection "PREFIX and LIB attribute"
299 PREFIX and LIB can be used to set several INSTALL* attributes in one
300 go. Here\*(Aqs an example for installing into your home directory.
301 .PP
302 .Vb 2
303 \& # Unix users, PREFIX=~ works fine
304 \& perl Makefile.PL PREFIX=/path/to/your/home/dir
305 .Ve
306 .PP
307 This will install all files in the module under your home directory,
308 with man pages and libraries going into an appropriate place (usually
309 ~/man and ~/lib). How the exact location is determined is complicated
310 and depends on how your Perl was configured. INSTALL_BASE works more
311 like what other build systems call "prefix" than PREFIX and we
312 recommend you use that instead.
313 .PP
314 Another way to specify many INSTALL directories with a single
315 parameter is LIB.
316 .PP
317 .Vb 1
318 \& perl Makefile.PL LIB=~/lib
319 .Ve
320 .PP
321 This will install the module\*(Aqs architecture\-independent files into
322 ~/lib, the architecture\-dependent files into ~/lib/$archname.
323 .PP
324 Note, that in both cases the tilde expansion is done by MakeMaker, not
325 by perl by default, nor by make.
326 .PP
327 Conflicts between parameters LIB, PREFIX and the various INSTALL*
328 arguments are resolved so that:
329 .IP \(bu 4
330 setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
331 INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
332 .IP \(bu 4
333 without LIB, setting PREFIX replaces the initial \f(CW$Config{prefix}\fR
334 part of those INSTALL* arguments, even if the latter are explicitly
335 set (but are set to still start with \f(CW$Config{prefix}\fR).
336 .PP
337 If the user has superuser privileges, and is not working on AFS or
338 relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
339 INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
340 the best:
341 .PP
342 .Vb 4
343 \& perl Makefile.PL;
344 \& make;
345 \& make test
346 \& make install
347 .Ve
348 .PP
349 make install by default writes some documentation of what has been
350 done into the file \f(CW\*(C`$(INSTALLARCHLIB)/perllocal.pod\*(C'\fR. This feature
351 can be bypassed by calling make pure_install.
352 .SS "AFS users"
353 .IX Subsection "AFS users"
354 will have to specify the installation directories as these most
355 probably have changed since perl itself has been installed. They will
356 have to do this by calling
357 .PP
358 .Vb 3
359 \& perl Makefile.PL INSTALLSITELIB=/afs/here/today \e
360 \& INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
361 \& make
362 .Ve
363 .PP
364 Be careful to repeat this procedure every time you recompile an
365 extension, unless you are sure the AFS installation directories are
366 still valid.
367 .SS "Static Linking of a new Perl Binary"
368 .IX Subsection "Static Linking of a new Perl Binary"
369 An extension that is built with the above steps is ready to use on
370 systems supporting dynamic loading. On systems that do not support
371 dynamic loading, any newly created extension has to be linked together
372 with the available resources. MakeMaker supports the linking process
373 by creating appropriate targets in the Makefile whenever an extension
374 is built. You can invoke the corresponding section of the makefile with
375 .PP
376 .Vb 1
377 \& make perl
378 .Ve
379 .PP
380 That produces a new perl binary in the current directory with all
381 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
382 and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
383 UNIX, this is called \fIMakefile.aperl\fR (may be system dependent). If you
384 want to force the creation of a new perl, it is recommended that you
385 delete this \fIMakefile.aperl\fR, so the directories are searched through
386 for linkable libraries again.
387 .PP
388 The binary can be installed into the directory where perl normally
389 resides on your machine with
390 .PP
391 .Vb 1
392 \& make inst_perl
393 .Ve
394 .PP
395 To produce a perl binary with a different name than \f(CW\*(C`perl\*(C'\fR, either say
396 .PP
397 .Vb 3
398 \& perl Makefile.PL MAP_TARGET=myperl
399 \& make myperl
400 \& make inst_perl
401 .Ve
402 .PP
403 or say
404 .PP
405 .Vb 3
406 \& perl Makefile.PL
407 \& make myperl MAP_TARGET=myperl
408 \& make inst_perl MAP_TARGET=myperl
409 .Ve
410 .PP
411 In any case you will be prompted with the correct invocation of the
412 \&\f(CW\*(C`inst_perl\*(C'\fR target that installs the new binary into INSTALLBIN.
413 .PP
414 make inst_perl by default writes some documentation of what has been
415 done into the file \f(CW\*(C`$(INSTALLARCHLIB)/perllocal.pod\*(C'\fR. This
416 can be bypassed by calling make pure_inst_perl.
417 .PP
418 Warning: the inst_perl: target will most probably overwrite your
419 existing perl binary. Use with care!
420 .PP
421 Sometimes you might want to build a statically linked perl although
422 your system supports dynamic loading. In this case you may explicitly
423 set the linktype with the invocation of the Makefile.PL or make:
424 .PP
425 .Vb 1
426 \& perl Makefile.PL LINKTYPE=static # recommended
427 .Ve
428 .PP
429 or
430 .PP
431 .Vb 1
432 \& make LINKTYPE=static # works on most systems
433 .Ve
434 .SS "Determination of Perl Library and Installation Locations"
435 .IX Subsection "Determination of Perl Library and Installation Locations"
436 MakeMaker needs to know, or to guess, where certain things are
437 located. Especially INST_LIB and INST_ARCHLIB (where to put the files
438 during the \fBmake\fR\|(1) run), PERL_LIB and PERL_ARCHLIB (where to read
439 existing modules from), and PERL_INC (header files and \f(CW\*(C`libperl*.*\*(C'\fR).
440 .PP
441 Extensions may be built either using the contents of the perl source
442 directory tree or from the installed perl library. The recommended way
443 is to build extensions after you have run \*(Aqmake install\*(Aq on perl
444 itself. You can do that in any directory on your hard disk that is not
445 below the perl source tree. The support for extensions below the ext
446 directory of the perl distribution is only good for the standard
447 extensions that come with perl.
448 .PP
449 If an extension is being built below the \f(CW\*(C`ext/\*(C'\fR directory of the perl
450 source then MakeMaker will set PERL_SRC automatically (e.g.,
451 \&\f(CW\*(C`../..\*(C'\fR). If PERL_SRC is defined and the extension is recognized as
452 a standard extension, then other variables default to the following:
453 .PP
454 .Vb 5
455 \& PERL_INC = PERL_SRC
456 \& PERL_LIB = PERL_SRC/lib
457 \& PERL_ARCHLIB = PERL_SRC/lib
458 \& INST_LIB = PERL_LIB
459 \& INST_ARCHLIB = PERL_ARCHLIB
460 .Ve
461 .PP
462 If an extension is being built away from the perl source then MakeMaker
463 will leave PERL_SRC undefined and default to using the installed copy
464 of the perl library. The other variables default to the following:
465 .PP
466 .Vb 5
467 \& PERL_INC = $archlibexp/CORE
468 \& PERL_LIB = $privlibexp
469 \& PERL_ARCHLIB = $archlibexp
470 \& INST_LIB = ./blib/lib
471 \& INST_ARCHLIB = ./blib/arch
472 .Ve
473 .PP
474 If perl has not yet been installed then PERL_SRC can be defined on the
475 command line as shown in the previous section.
476 .SS "Which architecture dependent directory?"
477 .IX Subsection "Which architecture dependent directory?"
478 If you don\*(Aqt want to keep the defaults for the INSTALL* macros,
479 MakeMaker helps you to minimize the typing needed: the usual
480 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
481 by Configure at perl compilation time. MakeMaker supports the user who
482 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
483 then MakeMaker defaults the latter to be the same subdirectory of
484 INSTALLPRIVLIB as Configure decided for the counterparts in \f(CW%Config\fR,
485 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
486 for INSTALLSITELIB and INSTALLSITEARCH.
487 .PP
488 MakeMaker gives you much more freedom than needed to configure
489 internal variables and get different results. It is worth mentioning
490 that \fBmake\fR\|(1) also lets you configure most of the variables that are
491 used in the Makefile. But in the majority of situations this will not
492 be necessary, and should only be done if the author of a package
493 recommends it (or you know what you\*(Aqre doing).
494 .SS "Using Attributes and Parameters"
495 .IX Subsection "Using Attributes and Parameters"
496 The following attributes may be specified as arguments to \fBWriteMakefile()\fR
497 or as NAME=VALUE pairs on the command line. Attributes that became
498 available with later versions of MakeMaker are indicated.
499 .PP
500 A computer\-readable list of recognized attributes is available as
501 \&\f(CW%ExtUtils::MakeMakers::Recognized_Att_Keys\fR, supported since 7.72. You
502 can check whether a particular parameter is supported by the current
503 version of ExtUtils::MakeMaker by checking whether it exists in the hash.
504 .PP
505 In order to maintain portability of attributes with older versions of
506 MakeMaker you may want to use App::EUMM::Upgrade with your \f(CW\*(C`Makefile.PL\*(C'\fR.
507 .IP ABSTRACT 2
508 .IX Item "ABSTRACT"
509 One line description of the module. Will be included in PPD file.
510 .IP ABSTRACT_FROM 2
511 .IX Item "ABSTRACT_FROM"
512 Name of the file that contains the package description. MakeMaker looks
513 for a line in the POD matching /^($package\es\-\es)(.*)/. This is typically
514 the first line in the "=head1 NAME" section. \f(CW$2\fR becomes the abstract.
515 .IP AUTHOR 2
516 .IX Item "AUTHOR"
517 Array of strings containing name (and email address) of package author(s).
518 Is used in CPAN Meta files (META.yml or META.json) and PPD
519 (Perl Package Description) files for PPM (Perl Package Manager).
520 .IP BINARY_LOCATION 2
521 .IX Item "BINARY_LOCATION"
522 Used when creating PPD files for binary packages. It can be set to a
523 full or relative path or URL to the binary archive for a particular
524 architecture. For example:
525 .Sp
526 .Vb 1
527 \& perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
528 .Ve
529 .Sp
530 builds a PPD package that references a binary of the \f(CW\*(C`Agent\*(C'\fR package,
531 located in the \f(CW\*(C`x86\*(C'\fR directory relative to the PPD itself.
532 .IP BUILD_REQUIRES 2
533 .IX Item "BUILD_REQUIRES"
534 Available in version 6.55_03 and above.
535 .Sp
536 A hash of modules that are needed to build your module but not run it.
537 .Sp
538 This will go into the \f(CW\*(C`build_requires\*(C'\fR field of your \fIMETA.yml\fR and the \f(CW\*(C`build\*(C'\fR of the \f(CW\*(C`prereqs\*(C'\fR field of your \fIMETA.json\fR.
539 .Sp
540 Defaults to \f(CW\*(C`{ "ExtUtils::MakeMaker" => 0 }\*(C'\fR if this attribute is not specified.
541 .Sp
542 The format is the same as PREREQ_PM.
543 .IP C 2
544 .IX Item "C"
545 Ref to array of *.c file names. Initialised from a directory scan
546 and the values portion of the XS attribute hash. This is not
547 currently used by MakeMaker but may be handy in Makefile.PLs.
548 .IP CCFLAGS 2
549 .IX Item "CCFLAGS"
550 String that will be included in the compiler call command line between
551 the arguments INC and OPTIMIZE. Note that setting this will overwrite its
552 default value (\f(CW$Config::Config{ccflags}\fR); to preserve that, include
553 the default value directly, e.g.:
554 .Sp
555 .Vb 1
556 \& CCFLAGS => "$Config::Config{ccflags} ..."
557 .Ve
558 .IP CONFIG 2
559 .IX Item "CONFIG"
560 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
561 config.sh. MakeMaker will add to CONFIG the following values anyway:
562 ar
563 cc
564 cccdlflags
565 ccdlflags
566 cpprun
567 dlext
568 dlsrc
569 ld
570 lddlflags
571 ldflags
572 libc
573 lib_ext
574 obj_ext
575 ranlib
576 sitelibexp
577 sitearchexp
578 so
579 .IP CONFIGURE 2
580 .IX Item "CONFIGURE"
581 CODE reference. The subroutine should return a hash reference. The
582 hash may contain further attributes, e.g. {LIBS => ...}, that have to
583 be determined by some evaluation method.
584 .IP CONFIGURE_REQUIRES 2
585 .IX Item "CONFIGURE_REQUIRES"
586 Available in version 6.52 and above.
587 .Sp
588 A hash of modules that are required to run Makefile.PL itself, but not
589 to run your distribution.
590 .Sp
591 This will go into the \f(CW\*(C`configure_requires\*(C'\fR field of your \fIMETA.yml\fR and the \f(CW\*(C`configure\*(C'\fR of the \f(CW\*(C`prereqs\*(C'\fR field of your \fIMETA.json\fR.
592 .Sp
593 Defaults to \f(CW\*(C`{ "ExtUtils::MakeMaker" => 0 }\*(C'\fR if this attribute is not specified.
594 .Sp
595 The format is the same as PREREQ_PM.
596 .IP DEFINE 2
597 .IX Item "DEFINE"
598 Something like \f(CW"\-DHAVE_UNISTD_H"\fR
599 .IP DESTDIR 2
600 .IX Item "DESTDIR"
601 This is the root directory into which the code will be installed. It
602 \&\fIprepends itself to the normal prefix\fR. For example, if your code
603 would normally go into \fI/usr/local/lib/perl\fR you could set DESTDIR=~/tmp/
604 and installation would go into \fI~/tmp/usr/local/lib/perl\fR.
605 .Sp
606 This is primarily of use for people who repackage Perl modules.
607 .Sp
608 NOTE: Due to the nature of make, it is important that you put the trailing
609 slash on your DESTDIR. \fI~/tmp/\fR not \fI~/tmp\fR.
610 .IP DIR 2
611 .IX Item "DIR"
612 Ref to array of subdirectories containing Makefile.PLs e.g. [\*(Aqsdbm\*(Aq]
613 in ext/SDBM_File
614 .IP DISTNAME 2
615 .IX Item "DISTNAME"
616 A safe filename for the package.
617 .Sp
618 Defaults to NAME below but with :: replaced with \-.
619 .Sp
620 For example, Foo::Bar becomes Foo\-Bar.
621 .IP DISTVNAME 2
622 .IX Item "DISTVNAME"
623 Your name for distributing the package with the version number
624 included. This is used by \*(Aqmake dist\*(Aq to name the resulting archive
625 file.
626 .Sp
627 Defaults to DISTNAME\-VERSION.
628 .Sp
629 For example, version 1.04 of Foo::Bar becomes Foo\-Bar\-1.04.
630 .Sp
631 On some OS\*(Aqs where . has special meaning VERSION_SYM may be used in
632 place of VERSION.
633 .IP DLEXT 2
634 .IX Item "DLEXT"
635 Specifies the extension of the module\*(Aqs loadable object. For example:
636 .Sp
637 .Vb 1
638 \& DLEXT => \*(Aqunusual_ext\*(Aq, # Default value is $Config{so}
639 .Ve
640 .Sp
641 NOTE: When using this option to alter the extension of a module\*(Aqs
642 loadable object, it is also necessary that the module\*(Aqs pm file
643 specifies the same change:
644 .Sp
645 .Vb 1
646 \& local $DynaLoader::dl_dlext = \*(Aqunusual_ext\*(Aq;
647 .Ve
648 .IP DL_FUNCS 2
649 .IX Item "DL_FUNCS"
650 Hashref of symbol names for routines to be made available as universal
651 symbols. Each key/value pair consists of the package name and an
652 array of routine names in that package. Used only under AIX, OS/2,
653 VMS and Win32 at present. The routine names supplied will be expanded
654 in the same way as XSUB names are expanded by the \fBXS()\fR macro.
655 Defaults to
656 .Sp
657 .Vb 1
658 \& {"$(NAME)" => ["boot_$(NAME)" ] }
659 .Ve
660 .Sp
661 e.g.
662 .Sp
663 .Vb 2
664 \& {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
665 \& "NetconfigPtr" => [ \*(AqDESTROY\*(Aq] }
666 .Ve
667 .Sp
668 Please see the ExtUtils::Mksymlists documentation for more information
669 about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
670 .IP DL_VARS 2
671 .IX Item "DL_VARS"
672 Array of symbol names for variables to be made available as universal symbols.
673 Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
674 (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
675 .IP EXCLUDE_EXT 2
676 .IX Item "EXCLUDE_EXT"
677 Array of extension names to exclude when doing a static build. This
678 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
679 details. (e.g. [ qw( Socket POSIX ) ] )
680 .Sp
681 This attribute may be most useful when specified as a string on the
682 command line: perl Makefile.PL EXCLUDE_EXT=\*(AqSocket Safe\*(Aq
683 .IP EXE_FILES 2
684 .IX Item "EXE_FILES"
685 Ref to array of executable files. The files will be copied to the
686 INST_SCRIPT directory. Make realclean will delete them from there
687 again.
688 .Sp
689 If your executables start with something like #!perl or
690 #!/usr/bin/perl MakeMaker will change this to the path of the perl
691 \&\*(AqMakefile.PL\*(Aq was invoked with so the programs will be sure to run
692 properly even if perl is not in /usr/bin/perl.
693 .IP FIRST_MAKEFILE 2
694 .IX Item "FIRST_MAKEFILE"
695 The name of the Makefile to be produced. This is used for the second
696 Makefile that will be produced for the MAP_TARGET.
697 .Sp
698 Defaults to \*(AqMakefile\*(Aq or \*(AqDescrip.MMS\*(Aq on VMS.
699 .Sp
700 (Note: we couldn\*(Aqt use MAKEFILE because dmake uses this for something
701 else).
702 .IP FULLPERL 2
703 .IX Item "FULLPERL"
704 Perl binary able to run this extension, load XS modules, etc...
705 .IP FULLPERLRUN 2
706 .IX Item "FULLPERLRUN"
707 Like PERLRUN, except it uses FULLPERL.
708 .IP FULLPERLRUNINST 2
709 .IX Item "FULLPERLRUNINST"
710 Like PERLRUNINST, except it uses FULLPERL.
711 .IP FUNCLIST 2
712 .IX Item "FUNCLIST"
713 This provides an alternate means to specify function names to be
714 exported from the extension. Its value is a reference to an
715 array of function names to be exported by the extension. These
716 names are passed through unaltered to the linker options file.
717 .IP H 2
718 .IX Item "H"
719 Ref to array of *.h file names. Similar to C.
720 .IP IMPORTS 2
721 .IX Item "IMPORTS"
722 This attribute is used to specify names to be imported into the
723 extension. Takes a hash ref.
724 .Sp
725 It is only used on OS/2 and Win32.
726 .IP INC 2
727 .IX Item "INC"
728 Include file dirs eg: \f(CW"\-I/usr/5include \-I/path/to/inc"\fR
729 .IP INCLUDE_EXT 2
730 .IX Item "INCLUDE_EXT"
731 Array of extension names to be included when doing a static build.
732 MakeMaker will normally build with all of the installed extensions when
733 doing a static build, and that is usually the desired behavior. If
734 INCLUDE_EXT is present then MakeMaker will build only with those extensions
735 which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
736 .Sp
737 It is not necessary to mention DynaLoader or the current extension when
738 filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
739 only DynaLoader and the current extension will be included in the build.
740 .Sp
741 This attribute may be most useful when specified as a string on the
742 command line: perl Makefile.PL INCLUDE_EXT=\*(AqPOSIX Socket Devel::Peek\*(Aq
743 .IP INSTALLARCHLIB 2
744 .IX Item "INSTALLARCHLIB"
745 Used by \*(Aqmake install\*(Aq, which copies files from INST_ARCHLIB to this
746 directory if INSTALLDIRS is set to perl.
747 .IP INSTALLBIN 2
748 .IX Item "INSTALLBIN"
749 Directory to install binary files (e.g. tkperl) into if
750 INSTALLDIRS=perl.
751 .IP INSTALLDIRS 2
752 .IX Item "INSTALLDIRS"
753 Determines which of the sets of installation directories to choose:
754 perl, site or vendor. Defaults to site.
755 .IP INSTALLMAN1DIR 2
756 .IX Item "INSTALLMAN1DIR"
757 .PD 0
758 .IP INSTALLMAN3DIR 2
759 .IX Item "INSTALLMAN3DIR"
760 .PD
761 These directories get the man pages at \*(Aqmake install\*(Aq time if
762 INSTALLDIRS=perl. Defaults to \f(CW$Config\fR{installman*dir}.
763 .Sp
764 If set to \*(Aqnone\*(Aq, no man pages will be installed.
765 .IP INSTALLPRIVLIB 2
766 .IX Item "INSTALLPRIVLIB"
767 Used by \*(Aqmake install\*(Aq, which copies files from INST_LIB to this
768 directory if INSTALLDIRS is set to perl.
769 .Sp
770 Defaults to \f(CW$Config\fR{installprivlib}.
771 .IP INSTALLSCRIPT 2
772 .IX Item "INSTALLSCRIPT"
773 Available in version 6.30_02 and above.
774 .Sp
775 Used by \*(Aqmake install\*(Aq which copies files from INST_SCRIPT to this
776 directory if INSTALLDIRS=perl.
777 .IP INSTALLSITEARCH 2
778 .IX Item "INSTALLSITEARCH"
779 Used by \*(Aqmake install\*(Aq, which copies files from INST_ARCHLIB to this
780 directory if INSTALLDIRS is set to site (default).
781 .IP INSTALLSITEBIN 2
782 .IX Item "INSTALLSITEBIN"
783 Used by \*(Aqmake install\*(Aq, which copies files from INST_BIN to this
784 directory if INSTALLDIRS is set to site (default).
785 .IP INSTALLSITELIB 2
786 .IX Item "INSTALLSITELIB"
787 Used by \*(Aqmake install\*(Aq, which copies files from INST_LIB to this
788 directory if INSTALLDIRS is set to site (default).
789 .IP INSTALLSITEMAN1DIR 2
790 .IX Item "INSTALLSITEMAN1DIR"
791 .PD 0
792 .IP INSTALLSITEMAN3DIR 2
793 .IX Item "INSTALLSITEMAN3DIR"
794 .PD
795 These directories get the man pages at \*(Aqmake install\*(Aq time if
796 INSTALLDIRS=site (default). Defaults to
797 $(SITEPREFIX)/man/man$(MAN*EXT).
798 .Sp
799 If set to \*(Aqnone\*(Aq, no man pages will be installed.
800 .IP INSTALLSITESCRIPT 2
801 .IX Item "INSTALLSITESCRIPT"
802 Used by \*(Aqmake install\*(Aq which copies files from INST_SCRIPT to this
803 directory if INSTALLDIRS is set to site (default).
804 .IP INSTALLVENDORARCH 2
805 .IX Item "INSTALLVENDORARCH"
806 Used by \*(Aqmake install\*(Aq, which copies files from INST_ARCHLIB to this
807 directory if INSTALLDIRS is set to vendor. Note that if you do not set
808 this, the value of INSTALLVENDORLIB will be used, which is probably not
809 what you want.
810 .IP INSTALLVENDORBIN 2
811 .IX Item "INSTALLVENDORBIN"
812 Used by \*(Aqmake install\*(Aq, which copies files from INST_BIN to this
813 directory if INSTALLDIRS is set to vendor.
814 .IP INSTALLVENDORLIB 2
815 .IX Item "INSTALLVENDORLIB"
816 Used by \*(Aqmake install\*(Aq, which copies files from INST_LIB to this
817 directory if INSTALLDIRS is set to vendor.
818 .IP INSTALLVENDORMAN1DIR 2
819 .IX Item "INSTALLVENDORMAN1DIR"
820 .PD 0
821 .IP INSTALLVENDORMAN3DIR 2
822 .IX Item "INSTALLVENDORMAN3DIR"
823 .PD
824 These directories get the man pages at \*(Aqmake install\*(Aq time if
825 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
826 .Sp
827 If set to \*(Aqnone\*(Aq, no man pages will be installed.
828 .IP INSTALLVENDORSCRIPT 2
829 .IX Item "INSTALLVENDORSCRIPT"
830 Available in version 6.30_02 and above.
831 .Sp
832 Used by \*(Aqmake install\*(Aq which copies files from INST_SCRIPT to this
833 directory if INSTALLDIRS is set to vendor.
834 .IP INST_ARCHLIB 2
835 .IX Item "INST_ARCHLIB"
836 Same as INST_LIB for architecture dependent files.
837 .IP INST_BIN 2
838 .IX Item "INST_BIN"
839 Directory to put real binary files during \*(Aqmake\*(Aq. These will be copied
840 to INSTALLBIN during \*(Aqmake install\*(Aq
841 .IP INST_LIB 2
842 .IX Item "INST_LIB"
843 Directory where we put library files of this extension while building
844 it.
845 .IP INST_MAN1DIR 2
846 .IX Item "INST_MAN1DIR"
847 Directory to hold the man pages at \*(Aqmake\*(Aq time
848 .IP INST_MAN3DIR 2
849 .IX Item "INST_MAN3DIR"
850 Directory to hold the man pages at \*(Aqmake\*(Aq time
851 .IP INST_SCRIPT 2
852 .IX Item "INST_SCRIPT"
853 Directory where executable files should be installed during
854 \&\*(Aqmake\*(Aq. Defaults to "./blib/script", just to have a dummy location during
855 testing. make install will copy the files in INST_SCRIPT to
856 INSTALLSCRIPT.
857 .IP LD 2
858 .IX Item "LD"
859 Program to be used to link libraries for dynamic loading.
860 .Sp
861 Defaults to \f(CW$Config\fR{ld}.
862 .IP LDDLFLAGS 2
863 .IX Item "LDDLFLAGS"
864 Any special flags that might need to be passed to ld to create a
865 shared library suitable for dynamic loading. It is up to the makefile
866 to use it. (See "lddlflags" in Config)
867 .Sp
868 Defaults to \f(CW$Config\fR{lddlflags}.
869 .IP LDFROM 2
870 .IX Item "LDFROM"
871 Defaults to "$(OBJECT)" and is used in the ld command to specify
872 what files to link/load from (also see dynamic_lib below for how to
873 specify ld flags)
874 .IP LIB 2
875 .IX Item "LIB"
876 LIB should only be set at \f(CW\*(C`perl Makefile.PL\*(C'\fR time but is allowed as a
877 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
878 and INSTALLSITELIB to that value regardless any explicit setting of
879 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
880 are set to the corresponding architecture subdirectory.
881 .IP LIBPERL_A 2
882 .IX Item "LIBPERL_A"
883 The filename of the perllibrary that will be used together with this
884 extension. Defaults to libperl.a.
885 .IP LIBS 2
886 .IX Item "LIBS"
887 An anonymous array of alternative library
888 specifications to be searched for (in order) until
889 at least one library is found. E.g.
890 .Sp
891 .Vb 1
892 \& \*(AqLIBS\*(Aq => ["\-lgdbm", "\-ldbm \-lfoo", "\-L/path \-ldbm.nfs"]
893 .Ve
894 .Sp
895 Mind, that any element of the array
896 contains a complete set of arguments for the ld
897 command. So do not specify
898 .Sp
899 .Vb 1
900 \& \*(AqLIBS\*(Aq => ["\-ltcl", "\-ltk", "\-lX11"]
901 .Ve
902 .Sp
903 See ODBM_File/Makefile.PL for an example, where an array is needed. If
904 you specify a scalar as in
905 .Sp
906 .Vb 1
907 \& \*(AqLIBS\*(Aq => "\-ltcl \-ltk \-lX11"
908 .Ve
909 .Sp
910 MakeMaker will turn it into an array with one element.
911 .IP LICENSE 2
912 .IX Item "LICENSE"
913 Available in version 6.31 and above.
914 .Sp
915 The licensing terms of your distribution. Generally it\*(Aqs "perl_5" for the
916 same license as Perl itself.
917 .Sp
918 See CPAN::Meta::Spec for the list of options.
919 .Sp
920 Defaults to "unknown".
921 .IP LINKTYPE 2
922 .IX Item "LINKTYPE"
923 \&\*(Aqstatic\*(Aq or \*(Aqdynamic\*(Aq (default unless usedl=undef in
924 config.sh). Should only be used to force static linking (also see
925 linkext below).
926 .IP MAGICXS 2
927 .IX Item "MAGICXS"
928 Available in version 6.8305 and above.
929 .Sp
930 When this is set to \f(CW1\fR, \f(CW\*(C`OBJECT\*(C'\fR will be automagically derived from
931 \&\f(CW\*(C`O_FILES\*(C'\fR.
932 .IP MAKE 2
933 .IX Item "MAKE"
934 Available in version 6.30_01 and above.
935 .Sp
936 Variant of make you intend to run the generated Makefile with. This
937 parameter lets Makefile.PL know what make quirks to account for when
938 generating the Makefile.
939 .Sp
940 MakeMaker also honors the MAKE environment variable. This parameter
941 takes precedence.
942 .Sp
943 Currently the only significant values are \*(Aqdmake\*(Aq and \*(Aqnmake\*(Aq for Windows
944 users, instructing MakeMaker to generate a Makefile in the flavour of
945 DMake ("Dennis Vadura\*(Aqs Make") or Microsoft NMake respectively.
946 .Sp
947 Defaults to \f(CW$Config\fR{make}, which may go looking for a Make program
948 in your environment.
949 .Sp
950 How are you supposed to know what flavour of Make a Makefile has
951 been generated for if you didn\*(Aqt specify a value explicitly? Search
952 the generated Makefile for the definition of the MAKE variable,
953 which is used to recursively invoke the Make utility. That will tell
954 you what Make you\*(Aqre supposed to invoke the Makefile with.
955 .IP MAKEAPERL 2
956 .IX Item "MAKEAPERL"
957 Boolean which tells MakeMaker that it should include the rules to
958 make a perl. This is handled automatically as a switch by
959 MakeMaker. The user normally does not need it.
960 .IP MAKEFILE_OLD 2
961 .IX Item "MAKEFILE_OLD"
962 When \*(Aqmake clean\*(Aq or similar is run, the $(FIRST_MAKEFILE) will be
963 backed up at this location.
964 .Sp
965 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
966 .IP MAN1PODS 2
967 .IX Item "MAN1PODS"
968 Hashref of pod\-containing files. MakeMaker will default this to all
969 EXE_FILES files that include POD directives. The files listed
970 here will be converted to man pages and installed as was requested
971 at Configure time.
972 .Sp
973 This hash should map POD files (or scripts containing POD) to the
974 man file names under the \f(CW\*(C`blib/man1/\*(C'\fR directory, as in the following
975 example:
976 .Sp
977 .Vb 4
978 \& MAN1PODS => {
979 \& \*(Aqdoc/command.pod\*(Aq => \*(Aqblib/man1/command.1\*(Aq,
980 \& \*(Aqscripts/script.pl\*(Aq => \*(Aqblib/man1/script.1\*(Aq,
981 \& }
982 .Ve
983 .IP MAN3PODS 2
984 .IX Item "MAN3PODS"
985 Hashref that assigns to *.pm and *.pod files the files into which the
986 manpages are to be written. MakeMaker parses all *.pod and *.pm files
987 for POD directives. Files that contain POD will be the default keys of
988 the MAN3PODS hashref. These will then be converted to man pages during
989 \&\f(CW\*(C`make\*(C'\fR and will be installed during \f(CW\*(C`make install\*(C'\fR.
990 .Sp
991 Example similar to MAN1PODS.
992 .IP MAP_TARGET 2
993 .IX Item "MAP_TARGET"
994 If it is intended that a new perl binary be produced, this variable
995 may hold a name for that binary. Defaults to perl
996 .IP META_ADD 2
997 .IX Item "META_ADD"
998 .PD 0
999 .IP META_MERGE 2
1000 .IX Item "META_MERGE"
1001 .PD
1002 Available in version 6.46 and above.
1003 .Sp
1004 A hashref of items to add to the CPAN Meta file (\fIMETA.yml\fR or
1005 \&\fIMETA.json\fR).
1006 .Sp
1007 They differ in how they behave if they have the same key as the
1008 default metadata. META_ADD will override the default value with its
1009 own. META_MERGE will merge its value with the default.
1010 .Sp
1011 Unless you want to override the defaults, prefer META_MERGE so as to
1012 get the advantage of any future defaults.
1013 .Sp
1014 Where prereqs are concerned, if META_MERGE is used, prerequisites are merged
1015 with their counterpart \f(CWWriteMakefile()\fR argument
1016 (PREREQ_PM is merged into {prereqs}{runtime}{requires},
1017 BUILD_REQUIRES into \f(CW\*(C`{prereqs}{build}{requires}\*(C'\fR,
1018 CONFIGURE_REQUIRES into \f(CW\*(C`{prereqs}{configure}{requires}\*(C'\fR,
1019 and TEST_REQUIRES into \f(CW\*(C`{prereqs}{test}{requires})\*(C'\fR.
1020 When prereqs are specified with META_ADD, the only prerequisites added to the
1021 file come from the metadata, not \f(CWWriteMakefile()\fR arguments.
1022 .Sp
1023 Note that these configuration options are only used for generating \fIMETA.yml\fR
1024 and \fIMETA.json\fR \-\- they are NOT used for \fIMYMETA.yml\fR and \fIMYMETA.json\fR.
1025 Therefore data in these fields should NOT be used for dynamic (user\-side)
1026 configuration.
1027 .Sp
1028 By default CPAN Meta specification \f(CW1.4\fR is used. In order to use
1029 CPAN Meta specification \f(CW2.0\fR, indicate with \f(CW\*(C`meta\-spec\*(C'\fR the version
1030 you want to use.
1031 .Sp
1032 .Vb 1
1033 \& META_MERGE => {
1034 \&
1035 \& "meta\-spec" => { version => 2 },
1036 \&
1037 \& resources => {
1038 \&
1039 \& repository => {
1040 \& type => \*(Aqgit\*(Aq,
1041 \& url => \*(Aqgit://github.com/Perl\-Toolchain\-Gang/ExtUtils\-MakeMaker.git\*(Aq,
1042 \& web => \*(Aqhttps://github.com/Perl\-Toolchain\-Gang/ExtUtils\-MakeMaker\*(Aq,
1043 \& },
1044 \&
1045 \& },
1046 \&
1047 \& },
1048 .Ve
1049 .IP MIN_PERL_VERSION 2
1050 .IX Item "MIN_PERL_VERSION"
1051 Available in version 6.48 and above.
1052 .Sp
1053 The minimum required version of Perl for this distribution.
1054 .Sp
1055 Either the 5.006001 or the 5.6.1 format is acceptable.
1056 .IP MYEXTLIB 2
1057 .IX Item "MYEXTLIB"
1058 If the extension links to a library that it builds, set this to the
1059 name of the library (see SDBM_File)
1060 .IP NAME 2
1061 .IX Item "NAME"
1062 The package representing the distribution. For example, \f(CW\*(C`Test::More\*(C'\fR
1063 or \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. It will be used to derive information about
1064 the distribution such as the "DISTNAME", installation locations
1065 within the Perl library and where XS files will be looked for by
1066 default (see "XS").
1067 .Sp
1068 \&\f(CW\*(C`NAME\*(C'\fR \fImust\fR be a valid Perl package name and it \fImust\fR have an
1069 associated \f(CW\*(C`.pm\*(C'\fR file. For example, \f(CW\*(C`Foo::Bar\*(C'\fR is a valid \f(CW\*(C`NAME\*(C'\fR
1070 and there must exist \fIFoo/Bar.pm\fR. Any XS code should be in
1071 \&\fIBar.xs\fR unless stated otherwise.
1072 .Sp
1073 Your distribution \fBmust\fR have a \f(CW\*(C`NAME\*(C'\fR.
1074 .IP NEEDS_LINKING 2
1075 .IX Item "NEEDS_LINKING"
1076 MakeMaker will figure out if an extension contains linkable code
1077 anywhere down the directory tree, and will set this variable
1078 accordingly, but you can speed it up a very little bit if you define
1079 this boolean variable yourself.
1080 .IP NOECHO 2
1081 .IX Item "NOECHO"
1082 Command so make does not print the literal commands it\*(Aqs running.
1083 .Sp
1084 By setting it to an empty string you can generate a Makefile that
1085 prints all commands. Mainly used in debugging MakeMaker itself.
1086 .Sp
1087 Defaults to \f(CW\*(C`@\*(C'\fR.
1088 .IP NORECURS 2
1089 .IX Item "NORECURS"
1090 Boolean. Attribute to inhibit descending into subdirectories.
1091 .IP NO_META 2
1092 .IX Item "NO_META"
1093 When true, suppresses the generation and addition to the MANIFEST of
1094 the META.yml and META.json module meta\-data files during \*(Aqmake distdir\*(Aq.
1095 .Sp
1096 Defaults to false.
1097 .IP NO_MYMETA 2
1098 .IX Item "NO_MYMETA"
1099 Available in version 6.57_02 and above.
1100 .Sp
1101 When true, suppresses the generation of MYMETA.yml and MYMETA.json module
1102 meta\-data files during \*(Aqperl Makefile.PL\*(Aq.
1103 .Sp
1104 Defaults to false.
1105 .IP NO_PACKLIST 2
1106 .IX Item "NO_PACKLIST"
1107 Available in version 6.7501 and above.
1108 .Sp
1109 When true, suppresses the writing of \f(CW\*(C`packlist\*(C'\fR files for installs.
1110 .Sp
1111 Defaults to false.
1112 .IP NO_PERLLOCAL 2
1113 .IX Item "NO_PERLLOCAL"
1114 Available in version 6.7501 and above.
1115 .Sp
1116 When true, suppresses the appending of installations to \f(CW\*(C`perllocal\*(C'\fR.
1117 .Sp
1118 Defaults to false.
1119 .IP NO_VC 2
1120 .IX Item "NO_VC"
1121 In general, any generated Makefile checks for the current version of
1122 MakeMaker and the version the Makefile was built under. If NO_VC is
1123 set, the version check is neglected. Do not write this into your
1124 Makefile.PL, use it interactively instead.
1125 .IP OBJECT 2
1126 .IX Item "OBJECT"
1127 List of object files, defaults to \*(Aq$(BASEEXT)$(OBJ_EXT)\*(Aq, but can be a long
1128 string or an array containing all object files, e.g. "tkpBind.o
1129 tkpButton.o tkpCanvas.o" or ["tkpBind.o", "tkpButton.o", "tkpCanvas.o"]
1130 .Sp
1131 (Where BASEEXT is the last component of NAME, and OBJ_EXT is \f(CW$Config\fR{obj_ext}.)
1132 .IP OPTIMIZE 2
1133 .IX Item "OPTIMIZE"
1134 Defaults to \f(CW\*(C`\-O\*(C'\fR. Set it to \f(CW\*(C`\-g\*(C'\fR to turn debugging on. The flag is
1135 passed to subdirectory makes.
1136 .IP PERL 2
1137 .IX Item "PERL"
1138 Perl binary for tasks that can be done by miniperl. If it contains
1139 spaces or other shell metacharacters, it needs to be quoted in a way
1140 that protects them, since this value is intended to be inserted in a
1141 shell command line in the Makefile. E.g.:
1142 .Sp
1143 .Vb 3
1144 \& # Perl executable lives in "C:/Program Files/Perl/bin"
1145 \& # Normally you don\*(Aqt need to set this yourself!
1146 \& $ perl Makefile.PL PERL=\*(Aq"C:/Program Files/Perl/bin/perl.exe" \-w\*(Aq
1147 .Ve
1148 .IP PERL_CORE 2
1149 .IX Item "PERL_CORE"
1150 Set only when MakeMaker is building the extensions of the Perl core
1151 distribution.
1152 .IP PERLMAINCC 2
1153 .IX Item "PERLMAINCC"
1154 The call to the program that is able to compile perlmain.c. Defaults
1155 to $(CC).
1156 .IP PERL_ARCHLIB 2
1157 .IX Item "PERL_ARCHLIB"
1158 Same as for PERL_LIB, but for architecture dependent files.
1159 .Sp
1160 Used only when MakeMaker is building the extensions of the Perl core
1161 distribution (because normally $(PERL_ARCHLIB) is automatically in \f(CW@INC\fR,
1162 and adding it would get in the way of PERL5LIB).
1163 .IP PERL_LIB 2
1164 .IX Item "PERL_LIB"
1165 Directory containing the Perl library to use.
1166 .Sp
1167 Used only when MakeMaker is building the extensions of the Perl core
1168 distribution (because normally $(PERL_LIB) is automatically in \f(CW@INC\fR,
1169 and adding it would get in the way of PERL5LIB).
1170 .IP PERL_MALLOC_OK 2
1171 .IX Item "PERL_MALLOC_OK"
1172 defaults to 0. Should be set to TRUE if the extension can work with
1173 the memory allocation routines substituted by the Perl \fBmalloc()\fR subsystem.
1174 This should be applicable to most extensions with exceptions of those
1175 .RS 2
1176 .IP \(bu 4
1177 with bugs in memory allocations which are caught by Perl\*(Aqs \fBmalloc()\fR;
1178 .IP \(bu 4
1179 which interact with the memory allocator in other ways than via
1180 \&\fBmalloc()\fR, \fBrealloc()\fR, \fBfree()\fR, \fBcalloc()\fR, \fBsbrk()\fR and \fBbrk()\fR;
1181 .IP \(bu 4
1182 which rely on special alignment which is not provided by Perl\*(Aqs \fBmalloc()\fR.
1183 .RE
1184 .RS 2
1185 .Sp
1186 \&\fBNOTE.\fR Neglecting to set this flag in \fIany one\fR of the loaded extension
1187 nullifies many advantages of Perl\*(Aqs \fBmalloc()\fR, such as better usage of
1188 system resources, error detection, memory usage reporting, catchable failure
1189 of memory allocations, etc.
1190 .RE
1191 .IP PERLPREFIX 2
1192 .IX Item "PERLPREFIX"
1193 Directory under which core modules are to be installed.
1194 .Sp
1195 Defaults to \f(CW$Config\fR{installprefixexp}, falling back to
1196 \&\f(CW$Config\fR{installprefix}, \f(CW$Config\fR{prefixexp} or \f(CW$Config\fR{prefix} should
1197 \&\f(CW$Config\fR{installprefixexp} not exist.
1198 .Sp
1199 Overridden by PREFIX.
1200 .IP PERLRUN 2
1201 .IX Item "PERLRUN"
1202 Use this instead of $(PERL) when you wish to run perl. It will set up
1203 extra necessary flags for you.
1204 .IP PERLRUNINST 2
1205 .IX Item "PERLRUNINST"
1206 Use this instead of $(PERL) when you wish to run perl to work with
1207 modules. It will add things like \-I$(INST_ARCH) and other necessary
1208 flags so perl can see the modules you\*(Aqre about to install.
1209 .IP PERL_SRC 2
1210 .IX Item "PERL_SRC"
1211 Directory containing the Perl source code (use of this should be
1212 avoided, it may be undefined)
1213 .IP PERM_DIR 2
1214 .IX Item "PERM_DIR"
1215 Available in version 6.51_01 and above.
1216 .Sp
1217 Desired permission for directories. Defaults to \f(CW755\fR.
1218 .IP PERM_RW 2
1219 .IX Item "PERM_RW"
1220 Desired permission for read/writable files. Defaults to \f(CW644\fR.
1221 .IP PERM_RWX 2
1222 .IX Item "PERM_RWX"
1223 Desired permission for executable files. Defaults to \f(CW755\fR.
1224 .IP PL_FILES 2
1225 .IX Item "PL_FILES"
1226 MakeMaker can run programs to generate files for you at build time.
1227 By default any file named *.PL (except Makefile.PL and Build.PL) in
1228 the top level directory will be assumed to be a Perl program and run
1229 passing its own basename in as an argument. This basename is actually a build
1230 target, and there is an intention, but not a requirement, that the *.PL file
1231 make the file passed to to as an argument. For example...
1232 .Sp
1233 .Vb 1
1234 \& perl foo.PL foo
1235 .Ve
1236 .Sp
1237 This behavior can be overridden by supplying your own set of files to
1238 search. PL_FILES accepts a hash ref, the key being the file to run
1239 and the value is passed in as the first argument when the PL file is run.
1240 .Sp
1241 .Vb 1
1242 \& PL_FILES => {\*(Aqbin/foobar.PL\*(Aq => \*(Aqbin/foobar\*(Aq}
1243 \&
1244 \& PL_FILES => {\*(Aqfoo.PL\*(Aq => \*(Aqfoo.c\*(Aq}
1245 .Ve
1246 .Sp
1247 Would run bin/foobar.PL like this:
1248 .Sp
1249 .Vb 1
1250 \& perl bin/foobar.PL bin/foobar
1251 .Ve
1252 .Sp
1253 If multiple files from one program are desired an array ref can be used.
1254 .Sp
1255 .Vb 1
1256 \& PL_FILES => {\*(Aqbin/foobar.PL\*(Aq => [qw(bin/foobar1 bin/foobar2)]}
1257 .Ve
1258 .Sp
1259 In this case the program will be run multiple times using each target file.
1260 .Sp
1261 .Vb 2
1262 \& perl bin/foobar.PL bin/foobar1
1263 \& perl bin/foobar.PL bin/foobar2
1264 .Ve
1265 .Sp
1266 If an output file depends on extra input files beside the script itself,
1267 a hash ref can be used in version 7.36 and above:
1268 .Sp
1269 .Vb 4
1270 \& PL_FILES => { \*(Aqfoo.PL\*(Aq => {
1271 \& \*(Aqfoo.out\*(Aq => \*(Aqfoo.in\*(Aq,
1272 \& \*(Aqbar.out\*(Aq => [qw(bar1.in bar2.in)],
1273 \& }
1274 .Ve
1275 .Sp
1276 In this case the extra input files will be passed to the program after
1277 the target file:
1278 .Sp
1279 .Vb 2
1280 \& perl foo.PL foo.out foo.in
1281 \& perl foo.PL bar.out bar1.in bar2.in
1282 .Ve
1283 .Sp
1284 PL files are normally run \fBafter\fR pm_to_blib and include INST_LIB and
1285 INST_ARCH in their \f(CW@INC\fR, so the just built modules can be
1286 accessed... unless the PL file is making a module (or anything else in
1287 PM) in which case it is run \fBbefore\fR pm_to_blib and does not include
1288 INST_LIB and INST_ARCH in its \f(CW@INC\fR. This apparently odd behavior
1289 is there for backwards compatibility (and it\*(Aqs somewhat DWIM). The argument
1290 passed to the .PL is set up as a target to build in the Makefile. In other
1291 sections such as \f(CW\*(C`postamble\*(C'\fR you can specify a dependency on the
1292 filename/argument that the .PL is supposed (or will have, now that that is
1293 is a dependency) to generate. Note the file to be generated will still be
1294 generated and the .PL will still run even without an explicit dependency created
1295 by you, since the \f(CW\*(C`all\*(C'\fR target still depends on running all eligible to run.PL
1296 files.
1297 .IP PM 2
1298 .IX Item "PM"
1299 Hashref of .pm files and *.pl files to be installed. e.g.
1300 .Sp
1301 .Vb 1
1302 \& {\*(Aqname_of_file.pm\*(Aq => \*(Aq$(INST_LIB)/install_as.pm\*(Aq}
1303 .Ve
1304 .Sp
1305 By default this will include *.pm and *.pl and the files found in
1306 the PMLIBDIRS directories. Defining PM in the
1307 Makefile.PL will override PMLIBDIRS.
1308 .IP PMLIBDIRS 2
1309 .IX Item "PMLIBDIRS"
1310 Ref to array of subdirectories containing library files. Defaults to
1311 [ \*(Aqlib\*(Aq, $(BASEEXT) ]. The directories will be scanned and \fIany\fR files
1312 they contain will be installed in the corresponding location in the
1313 library. A \fBlibscan()\fR method can be used to alter the behaviour.
1314 Defining PM in the Makefile.PL will override PMLIBDIRS.
1315 .Sp
1316 (Where BASEEXT is the last component of NAME.)
1317 .IP PM_FILTER 2
1318 .IX Item "PM_FILTER"
1319 A filter program, in the traditional Unix sense (input from stdin, output
1320 to stdout) that is passed on each .pm file during the build (in the
1321 \&\fBpm_to_blib()\fR phase). It is empty by default, meaning no filtering is done.
1322 You could use:
1323 .Sp
1324 .Vb 1
1325 \& PM_FILTER => \*(Aqperl \-ne "print unless /^#/"\*(Aq,
1326 .Ve
1327 .Sp
1328 to remove all the leading comments on the fly during the build. In order
1329 to be as portable as possible, please consider using a Perl one\-liner
1330 rather than Unix (or other) utilities, as above. MakeMaker will escape the
1331 \&\f(CW\*(C`#\*(C'\fR for the Makefile, since what goes in the Makefile will depend on
1332 which \f(CW\*(C`make\*(C'\fR implementation is being targeted.
1333 .Sp
1334 You will almost certainly be better off using the \f(CW\*(C`PL_FILES\*(C'\fR system,
1335 instead. See above, or the ExtUtils::MakeMaker::FAQ entry.
1336 .IP POLLUTE 2
1337 .IX Item "POLLUTE"
1338 Prior to 5.6 various interpreter variables were available without a \f(CW\*(C`PL_\*(C'\fR
1339 prefix, eg. \f(CW\*(C`PL_undef\*(C'\fR was available as \f(CW\*(C`undef\*(C'\fR. As of release 5.6, these
1340 are only defined if the POLLUTE flag is enabled:
1341 .Sp
1342 .Vb 1
1343 \& perl Makefile.PL POLLUTE=1
1344 .Ve
1345 .Sp
1346 Please inform the module author if this is necessary to successfully install
1347 a module under 5.6 or later.
1348 .IP PPM_INSTALL_EXEC 2
1349 .IX Item "PPM_INSTALL_EXEC"
1350 Name of the executable used to run \f(CW\*(C`PPM_INSTALL_SCRIPT\*(C'\fR below. (e.g. perl)
1351 .IP PPM_INSTALL_SCRIPT 2
1352 .IX Item "PPM_INSTALL_SCRIPT"
1353 Name of the script that gets executed by the Perl Package Manager after
1354 the installation of a package.
1355 .IP PPM_UNINSTALL_EXEC 2
1356 .IX Item "PPM_UNINSTALL_EXEC"
1357 Available in version 6.8502 and above.
1358 .Sp
1359 Name of the executable used to run \f(CW\*(C`PPM_UNINSTALL_SCRIPT\*(C'\fR below. (e.g. perl)
1360 .IP PPM_UNINSTALL_SCRIPT 2
1361 .IX Item "PPM_UNINSTALL_SCRIPT"
1362 Available in version 6.8502 and above.
1363 .Sp
1364 Name of the script that gets executed by the Perl Package Manager before
1365 the removal of a package.
1366 .IP PREFIX 2
1367 .IX Item "PREFIX"
1368 This overrides all the default install locations. Man pages,
1369 libraries, scripts, etc... MakeMaker will try to make an educated
1370 guess about where to place things under the new PREFIX based on your
1371 Config defaults. Failing that, it will fall back to a structure
1372 which should be sensible for your platform.
1373 .Sp
1374 If you specify LIB or any INSTALL* variables they will not be affected
1375 by the PREFIX.
1376 .IP PREREQ_FATAL 2
1377 .IX Item "PREREQ_FATAL"
1378 Bool. If this parameter is true, failing to have the required modules
1379 (or the right versions thereof) will be fatal. \f(CW\*(C`perl Makefile.PL\*(C'\fR
1380 will \f(CW\*(C`die\*(C'\fR instead of simply informing the user of the missing dependencies.
1381 .Sp
1382 It is \fIextremely\fR rare to have to use \f(CW\*(C`PREREQ_FATAL\*(C'\fR. Its use by module
1383 authors is \fIstrongly discouraged\fR and should never be used lightly.
1384 .Sp
1385 For dependencies that are required in order to run \f(CW\*(C`Makefile.PL\*(C'\fR,
1386 see \f(CW\*(C`CONFIGURE_REQUIRES\*(C'\fR.
1387 .Sp
1388 Module installation tools have ways of resolving unmet dependencies but
1389 to do that they need a \fIMakefile\fR. Using \f(CW\*(C`PREREQ_FATAL\*(C'\fR breaks this.
1390 That\*(Aqs bad.
1391 .Sp
1392 Assuming you have good test coverage, your tests should fail with
1393 missing dependencies informing the user more strongly that something
1394 is wrong. You can write a \fIt/00compile.t\fR test which will simply
1395 check that your code compiles and stop "make test" prematurely if it
1396 doesn\*(Aqt. See "BAIL_OUT" in Test::More for more details.
1397 .IP PREREQ_PM 2
1398 .IX Item "PREREQ_PM"
1399 A hash of modules that are needed to run your module. The keys are
1400 the module names ie. Test::More, and the minimum version is the
1401 value. If the required version number is 0 any version will do.
1402 The versions given may be a Perl v\-string (see version) or a range
1403 (see CPAN::Meta::Requirements).
1404 .Sp
1405 This will go into the \f(CW\*(C`requires\*(C'\fR field of your \fIMETA.yml\fR and the
1406 \&\f(CW\*(C`runtime\*(C'\fR of the \f(CW\*(C`prereqs\*(C'\fR field of your \fIMETA.json\fR.
1407 .Sp
1408 .Vb 3
1409 \& PREREQ_PM => {
1410 \& # Require Test::More at least 0.47
1411 \& "Test::More" => "0.47",
1412 \&
1413 \& # Require any version of Acme::Buffy
1414 \& "Acme::Buffy" => 0,
1415 \& }
1416 .Ve
1417 .IP PREREQ_PRINT 2
1418 .IX Item "PREREQ_PRINT"
1419 Bool. If this parameter is true, the prerequisites will be printed to
1420 stdout and MakeMaker will exit. The output format is an evalable hash
1421 ref.
1422 .Sp
1423 .Vb 5
1424 \& $PREREQ_PM = {
1425 \& \*(AqA::B\*(Aq => Vers1,
1426 \& \*(AqC::D\*(Aq => Vers2,
1427 \& ...
1428 \& };
1429 .Ve
1430 .Sp
1431 If a distribution defines a minimal required perl version, this is
1432 added to the output as an additional line of the form:
1433 .Sp
1434 .Vb 1
1435 \& $MIN_PERL_VERSION = \*(Aq5.008001\*(Aq;
1436 .Ve
1437 .Sp
1438 If BUILD_REQUIRES is not empty, it will be dumped as \f(CW$BUILD_REQUIRES\fR hashref.
1439 .IP PRINT_PREREQ 2
1440 .IX Item "PRINT_PREREQ"
1441 RedHatism for \f(CW\*(C`PREREQ_PRINT\*(C'\fR. The output format is different, though:
1442 .Sp
1443 .Vb 1
1444 \& perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1445 .Ve
1446 .Sp
1447 A minimal required perl version, if present, will look like this:
1448 .Sp
1449 .Vb 1
1450 \& perl(perl)>=5.008001
1451 .Ve
1452 .IP SITEPREFIX 2
1453 .IX Item "SITEPREFIX"
1454 Like PERLPREFIX, but only for the site install locations.
1455 .Sp
1456 Defaults to \f(CW$Config\fR{siteprefixexp}. Perls prior to 5.6.0 didn\*(Aqt have
1457 an explicit siteprefix in the Config. In those cases
1458 \&\f(CW$Config\fR{installprefix} will be used.
1459 .Sp
1460 Overridable by PREFIX
1461 .IP SIGN 2
1462 .IX Item "SIGN"
1463 Available in version 6.18 and above.
1464 .Sp
1465 When true, perform the generation and addition to the MANIFEST of the
1466 SIGNATURE file in the distdir during \*(Aqmake distdir\*(Aq, via \*(Aqcpansign
1467 \&\-s\*(Aq.
1468 .Sp
1469 Note that you need to install the Module::Signature module to
1470 perform this operation.
1471 .Sp
1472 Defaults to false.
1473 .IP SKIP 2
1474 .IX Item "SKIP"
1475 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1476 Makefile. Caution! Do not use the SKIP attribute for the negligible
1477 speedup. It may seriously damage the resulting Makefile. Only use it
1478 if you really need it.
1479 .IP TEST_REQUIRES 2
1480 .IX Item "TEST_REQUIRES"
1481 Available in version 6.64 and above.
1482 .Sp
1483 A hash of modules that are needed to test your module but not run or
1484 build it.
1485 .Sp
1486 This will go into the \f(CW\*(C`build_requires\*(C'\fR field of your \fIMETA.yml\fR and the \f(CW\*(C`test\*(C'\fR of the \f(CW\*(C`prereqs\*(C'\fR field of your \fIMETA.json\fR.
1487 .Sp
1488 The format is the same as PREREQ_PM.
1489 .IP TYPEMAPS 2
1490 .IX Item "TYPEMAPS"
1491 Ref to array of typemap file names. Use this when the typemaps are
1492 in some directory other than the current directory or when they are
1493 not named \fBtypemap\fR. The last typemap in the list takes
1494 precedence. A typemap in the current directory has highest
1495 precedence, even if it isn\*(Aqt listed in TYPEMAPS. The default system
1496 typemap has lowest precedence.
1497 .IP USE_MM_LD_RUN_PATH 2
1498 .IX Item "USE_MM_LD_RUN_PATH"
1499 boolean
1500 The Fedora perl MakeMaker distribution differs from the standard
1501 upstream release in that it disables use of the MakeMaker generated
1502 LD_RUN_PATH by default, UNLESS this attribute is specified , or the
1503 USE_MM_LD_RUN_PATH environment variable is set during the MakeMaker run.
1504 .Sp
1505 The upstream MakeMaker will set the \fBld\fR\|(1) environment variable LD_RUN_PATH
1506 to the concatenation of every \-L \fBld\fR\|(1) option directory in which a \-l \fBld\fR\|(1)
1507 option library is found, which is used as the \fBld\fR\|(1) \-rpath option if none
1508 is specified. This means that, if your application builds shared libraries
1509 and your MakeMaker application links to them, that the absolute paths of the
1510 libraries in the build tree will be inserted into the RPATH header of all
1511 MakeMaker generated binaries, and that such binaries will be unable to link
1512 to these libraries if they do not still reside in the build tree directories
1513 (unlikely) or in the system library directories (/lib or /usr/lib), regardless
1514 of any LD_LIBRARY_PATH setting. So if you specified \-L../mylib \-lmylib , and
1515 your \*(Aqlibmylib.so\*(Aq gets installed into /some_directory_other_than_usr_lib,
1516 your MakeMaker application will be unable to link to it, even if LD_LIBRARY_PATH
1517 is set to include /some_directory_other_than_usr_lib, because RPATH overrides
1518 LD_LIBRARY_PATH.
1519 .Sp
1520 So for Fedora MakeMaker builds LD_RUN_PATH is NOT generated by default for
1521 every link. You can still use explicit \-rpath ld options or the LD_RUN_PATH
1522 environment variable during the build to generate an RPATH for the binaries.
1523 .Sp
1524 You can set the USE_MM_LD_RUN_PATH attribute to 1 on the MakeMaker command
1525 line or in the WriteMakefile arguments to enable generation of LD_RUN_PATH
1526 for every link command.
1527 .Sp
1528 USE_MM_LD_RUN_PATH will default to 1 (LD_RUN_PATH will be used) IF the
1529 \&\f(CW$USE_MM_LD_RUN_PATH\fR environment variable is set during a MakeMaker run.
1530 .IP VENDORPREFIX 2
1531 .IX Item "VENDORPREFIX"
1532 Like PERLPREFIX, but only for the vendor install locations.
1533 .Sp
1534 Defaults to \f(CW$Config\fR{vendorprefixexp}.
1535 .Sp
1536 Overridable by PREFIX
1537 .IP VERBINST 2
1538 .IX Item "VERBINST"
1539 If true, make install will be verbose
1540 .IP VERSION 2
1541 .IX Item "VERSION"
1542 Your version number for distributing the package. This defaults to
1543 0.1.
1544 .IP VERSION_FROM 2
1545 .IX Item "VERSION_FROM"
1546 Instead of specifying the VERSION in the Makefile.PL you can let
1547 MakeMaker parse a file to determine the version number. The parsing
1548 routine requires that the file named by VERSION_FROM contains one
1549 single line to compute the version number. The first line in the file
1550 that contains something like a \f(CW$VERSION\fR assignment or \f(CW\*(C`package Name
1551 VERSION\*(C'\fR will be used. The following lines will be parsed o.k.:
1552 .Sp
1553 .Vb 7
1554 \& # Good
1555 \& package Foo::Bar 1.23; # 1.23
1556 \& $VERSION = \*(Aq1.00\*(Aq; # 1.00
1557 \& *VERSION = \e\*(Aq1.01\*(Aq; # 1.01
1558 \& ($VERSION) = q$Revision$ =~ /(\ed+)/g; # The digits in $Revision$
1559 \& $FOO::VERSION = \*(Aq1.10\*(Aq; # 1.10
1560 \& *FOO::VERSION = \e\*(Aq1.11\*(Aq; # 1.11
1561 .Ve
1562 .Sp
1563 but these will fail:
1564 .Sp
1565 .Vb 4
1566 \& # Bad
1567 \& my $VERSION = \*(Aq1.01\*(Aq;
1568 \& local $VERSION = \*(Aq1.02\*(Aq;
1569 \& local $FOO::VERSION = \*(Aq1.30\*(Aq;
1570 .Ve
1571 .Sp
1572 (Putting \f(CW\*(C`my\*(C'\fR or \f(CW\*(C`local\*(C'\fR on the preceding line will work o.k.)
1573 .Sp
1574 "Version strings" are incompatible and should not be used.
1575 .Sp
1576 .Vb 3
1577 \& # Bad
1578 \& $VERSION = 1.2.3;
1579 \& $VERSION = v1.2.3;
1580 .Ve
1581 .Sp
1582 version objects are fine. As of MakeMaker 6.35 version.pm will be
1583 automatically loaded, but you must declare the dependency on version.pm.
1584 For compatibility with older MakeMaker you should load on the same line
1585 as \f(CW$VERSION\fR is declared.
1586 .Sp
1587 .Vb 2
1588 \& # All on one line
1589 \& use version; our $VERSION = qv(1.2.3);
1590 .Ve
1591 .Sp
1592 The file named in VERSION_FROM is not added as a dependency to
1593 Makefile. This is not really correct, but it would be a major pain
1594 during development to have to rewrite the Makefile for any smallish
1595 change in that file. If you want to make sure that the Makefile
1596 contains the correct VERSION macro after any change of the file, you
1597 would have to do something like
1598 .Sp
1599 .Vb 1
1600 \& depend => { Makefile => \*(Aq$(VERSION_FROM)\*(Aq }
1601 .Ve
1602 .Sp
1603 See attribute \f(CW\*(C`depend\*(C'\fR below.
1604 .IP VERSION_SYM 2
1605 .IX Item "VERSION_SYM"
1606 A sanitized VERSION with . replaced by _. For places where . has
1607 special meaning (some filesystems, RCS labels, etc...)
1608 .IP XS 2
1609 .IX Item "XS"
1610 Hashref of .xs files. MakeMaker will default this. e.g.
1611 .Sp
1612 .Vb 1
1613 \& {\*(Aqname_of_file.xs\*(Aq => \*(Aqname_of_file.c\*(Aq}
1614 .Ve
1615 .Sp
1616 The .c files will automatically be included in the list of files
1617 deleted by a make clean.
1618 .IP XSBUILD 2
1619 .IX Item "XSBUILD"
1620 Available in version 7.12 and above.
1621 .Sp
1622 Hashref with options controlling the operation of \f(CW\*(C`XSMULTI\*(C'\fR:
1623 .Sp
1624 .Vb 10
1625 \& {
1626 \& xs => {
1627 \& all => {
1628 \& # options applying to all .xs files for this distribution
1629 \& },
1630 \& \*(Aqlib/Class/Name/File\*(Aq => { # specifically for this file
1631 \& DEFINE => \*(Aq\-Dfunktastic\*(Aq, # defines for only this file
1632 \& INC => "\-I$funkyliblocation", # include flags for only this file
1633 \& # OBJECT => \*(Aqlib/Class/Name/File$(OBJ_EXT)\*(Aq, # default
1634 \& LDFROM => "lib/Class/Name/File\e$(OBJ_EXT) $otherfile\e$(OBJ_EXT)", # what\*(Aqs linked
1635 \& },
1636 \& },
1637 \& }
1638 .Ve
1639 .Sp
1640 Note \f(CW\*(C`xs\*(C'\fR is the file\-extension. More possibilities may arise in the
1641 future. Note that object names are specified without their XS extension.
1642 .Sp
1643 \&\f(CW\*(C`LDFROM\*(C'\fR defaults to the same as \f(CW\*(C`OBJECT\*(C'\fR. \f(CW\*(C`OBJECT\*(C'\fR defaults to,
1644 for \f(CW\*(C`XSMULTI\*(C'\fR, just the XS filename with the extension replaced with
1645 the compiler\-specific object\-file extension.
1646 .Sp
1647 The distinction between \f(CW\*(C`OBJECT\*(C'\fR and \f(CW\*(C`LDFROM\*(C'\fR: \f(CW\*(C`OBJECT\*(C'\fR is the make
1648 target, so make will try to build it. However, \f(CW\*(C`LDFROM\*(C'\fR is what will
1649 actually be linked together to make the shared object or static library
1650 (SO/SL), so if you override it, make sure it includes what you want to
1651 make the final SO/SL, almost certainly including the XS basename with
1652 \&\f(CW\*(C`$(OBJ_EXT)\*(C'\fR appended.
1653 .IP XSMULTI 2
1654 .IX Item "XSMULTI"
1655 Available in version 7.12 and above.
1656 .Sp
1657 When this is set to \f(CW1\fR, multiple XS files may be placed under \fIlib/\fR
1658 next to their corresponding \f(CW\*(C`*.pm\*(C'\fR files (this is essential for compiling
1659 with the correct \f(CW\*(C`VERSION\*(C'\fR values). This feature should be considered
1660 experimental, and details of it may change.
1661 .Sp
1662 This feature was inspired by, and small portions of code copied from,
1663 ExtUtils::MakeMaker::BigHelper. Hopefully this feature will render
1664 that module mainly obsolete.
1665 .IP XSOPT 2
1666 .IX Item "XSOPT"
1667 String of options to pass to xsubpp. This might include \f(CW\*(C`\-C++\*(C'\fR or
1668 \&\f(CW\*(C`\-extern\*(C'\fR. Do not include typemaps here; the TYPEMAP parameter exists for
1669 that purpose.
1670 .IP XSPROTOARG 2
1671 .IX Item "XSPROTOARG"
1672 May be set to \f(CW\*(C`\-prototypes\*(C'\fR, \f(CW\*(C`\-noprototypes\*(C'\fR or the empty string. The
1673 empty string is equivalent to the xsubpp default, or \f(CW\*(C`\-noprototypes\*(C'\fR.
1674 See the xsubpp documentation for details. MakeMaker
1675 defaults to the empty string.
1676 .IP XS_VERSION 2
1677 .IX Item "XS_VERSION"
1678 Your version number for the .xs file of this package. This defaults
1679 to the value of the VERSION attribute.
1680 .SS "Additional lowercase attributes"
1681 .IX Subsection "Additional lowercase attributes"
1682 can be used to pass parameters to the methods which implement that
1683 part of the Makefile. Parameters are specified as a hash ref but are
1684 passed to the method as a hash.
1685 .IP clean 2
1686 .IX Item "clean"
1687 .Vb 1
1688 \& {FILES => "*.xyz foo"}
1689 .Ve
1690 .IP depend 2
1691 .IX Item "depend"
1692 .Vb 1
1693 \& {ANY_TARGET => ANY_DEPENDENCY, ...}
1694 .Ve
1695 .Sp
1696 (ANY_TARGET must not be given a double\-colon rule by MakeMaker.)
1697 .IP dist 2
1698 .IX Item "dist"
1699 .Vb 3
1700 \& {TARFLAGS => \*(AqcvfF\*(Aq, COMPRESS => \*(Aqgzip\*(Aq, SUFFIX => \*(Aq.gz\*(Aq,
1701 \& SHAR => \*(Aqshar \-m\*(Aq, DIST_CP => \*(Aqln\*(Aq, ZIP => \*(Aq/bin/zip\*(Aq,
1702 \& ZIPFLAGS => \*(Aq\-rl\*(Aq, DIST_DEFAULT => \*(Aqprivate tardist\*(Aq }
1703 .Ve
1704 .Sp
1705 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1706 needed to tell make the target file of the compression. Setting
1707 DIST_CP to ln can be useful, if you need to preserve the timestamps on
1708 your files. DIST_CP can take the values \*(Aqcp\*(Aq, which copies the file,
1709 \&\*(Aqln\*(Aq, which links the file, and \*(Aqbest\*(Aq which copies symbolic links and
1710 links the rest. Default is \*(Aqbest\*(Aq.
1711 .IP dynamic_lib 2
1712 .IX Item "dynamic_lib"
1713 .Vb 1
1714 \& {ARMAYBE => \*(Aqar\*(Aq, OTHERLDFLAGS => \*(Aq...\*(Aq, INST_DYNAMIC_DEP => \*(Aq...\*(Aq}
1715 .Ve
1716 .IP linkext 2
1717 .IX Item "linkext"
1718 .Vb 1
1719 \& {LINKTYPE => \*(Aqstatic\*(Aq, \*(Aqdynamic\*(Aq or \*(Aq\*(Aq}
1720 .Ve
1721 .Sp
1722 NB: Extensions that have nothing but *.pm files had to say
1723 .Sp
1724 .Vb 1
1725 \& {LINKTYPE => \*(Aq\*(Aq}
1726 .Ve
1727 .Sp
1728 with Pre\-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1729 can be deleted safely. MakeMaker recognizes when there\*(Aqs nothing to
1730 be linked.
1731 .IP macro 2
1732 .IX Item "macro"
1733 .Vb 1
1734 \& {ANY_MACRO => ANY_VALUE, ...}
1735 .Ve
1736 .IP postamble 2
1737 .IX Item "postamble"
1738 Anything put here will be passed to
1739 \&\fBMY::postamble()\fR if you have one.
1740 .IP realclean 2
1741 .IX Item "realclean"
1742 .Vb 1
1743 \& {FILES => \*(Aq$(INST_ARCHAUTODIR)/*.xyz\*(Aq}
1744 .Ve
1745 .IP test 2
1746 .IX Item "test"
1747 Specify the targets for testing.
1748 .Sp
1749 .Vb 1
1750 \& {TESTS => \*(Aqt/*.t\*(Aq}
1751 .Ve
1752 .Sp
1753 \&\f(CW\*(C`RECURSIVE_TEST_FILES\*(C'\fR can be used to include all directories
1754 recursively under \f(CW\*(C`t\*(C'\fR that contain \f(CW\*(C`.t\*(C'\fR files. It will be ignored if
1755 you provide your own \f(CW\*(C`TESTS\*(C'\fR attribute, defaults to false.
1756 .Sp
1757 .Vb 1
1758 \& {RECURSIVE_TEST_FILES=>1}
1759 .Ve
1760 .Sp
1761 This is supported since 6.76
1762 .IP tool_autosplit 2
1763 .IX Item "tool_autosplit"
1764 .Vb 1
1765 \& {MAXLEN => 8}
1766 .Ve
1767 .SS "Overriding MakeMaker Methods"
1768 .IX Subsection "Overriding MakeMaker Methods"
1769 If you cannot achieve the desired Makefile behaviour by specifying
1770 attributes you may define private subroutines in the Makefile.PL.
1771 Each subroutine returns the text it wishes to have written to
1772 the Makefile. To override a section of the Makefile you can
1773 either say:
1774 .PP
1775 .Vb 1
1776 \& sub MY::c_o { "new literal text" }
1777 .Ve
1778 .PP
1779 or you can edit the default by saying something like:
1780 .PP
1781 .Vb 6
1782 \& package MY; # so that "SUPER" works right
1783 \& sub c_o {
1784 \& my $inherited = shift\->SUPER::c_o(@_);
1785 \& $inherited =~ s/old text/new text/;
1786 \& $inherited;
1787 \& }
1788 .Ve
1789 .PP
1790 If you are running experiments with embedding perl as a library into
1791 other applications, you might find MakeMaker is not sufficient. You\*(Aqd
1792 better have a look at ExtUtils::Embed which is a collection of utilities
1793 for embedding.
1794 .PP
1795 If you still need a different solution, try to develop another
1796 subroutine that fits your needs and submit the diffs to
1797 \&\f(CW\*(C`[email protected]\*(C'\fR
1798 .PP
1799 For a complete description of all MakeMaker methods see
1800 ExtUtils::MM_Unix.
1801 .PP
1802 Here is a simple example of how to add a new target to the generated
1803 Makefile:
1804 .PP
1805 .Vb 4
1806 \& sub MY::postamble {
1807 \& return <<\*(AqMAKE_FRAG\*(Aq;
1808 \& $(MYEXTLIB): sdbm/Makefile
1809 \& cd sdbm && $(MAKE) all
1810 \&
1811 \& MAKE_FRAG
1812 \& }
1813 .Ve
1814 .SS "The End Of Cargo Cult Programming"
1815 .IX Subsection "The End Of Cargo Cult Programming"
1816 \&\fBWriteMakefile()\fR now does some basic sanity checks on its parameters to
1817 protect against typos and malformatted values. This means some things
1818 which happened to work in the past will now throw warnings and
1819 possibly produce internal errors.
1820 .PP
1821 Some of the most common mistakes:
1822 .ie n .IP """MAN3PODS => \*(Aq \*(Aq""" 2
1823 .el .IP "\f(CWMAN3PODS => \*(Aq \*(Aq\fR" 2
1824 .IX Item "MAN3PODS => ' '"
1825 This is commonly used to suppress the creation of man pages. MAN3PODS
1826 takes a hash ref not a string, but the above worked by accident in old
1827 versions of MakeMaker.
1828 .Sp
1829 The correct code is \f(CW\*(C`MAN3PODS => { }\*(C'\fR.
1830 .SS "Hintsfile support"
1831 .IX Subsection "Hintsfile support"
1832 MakeMaker.pm uses the architecture\-specific information from
1833 Config.pm. In addition it evaluates architecture specific hints files
1834 in a \f(CW\*(C`hints/\*(C'\fR directory. The hints files are expected to be named
1835 like their counterparts in \f(CW\*(C`PERL_SRC/hints\*(C'\fR, but with an \f(CW\*(C`.pl\*(C'\fR file
1836 name extension (eg. \f(CW\*(C`next_3_2.pl\*(C'\fR). They are simply \f(CW\*(C`eval\*(C'\fRed by
1837 MakeMaker within the \fBWriteMakefile()\fR subroutine, and can be used to
1838 execute commands as well as to include special variables. The rules
1839 which hintsfile is chosen are the same as in Configure.
1840 .PP
1841 The hintsfile is \fBeval()\fRed immediately after the arguments given to
1842 WriteMakefile are stuffed into a hash reference \f(CW$self\fR but before this
1843 reference becomes blessed. So if you want to do the equivalent to
1844 override or create an attribute you would say something like
1845 .PP
1846 .Vb 1
1847 \& $self\->{LIBS} = [\*(Aq\-ldbm \-lucb \-lc\*(Aq];
1848 .Ve
1849 .SS "Distribution Support"
1850 .IX Subsection "Distribution Support"
1851 For authors of extensions MakeMaker provides several Makefile
1852 targets. Most of the support comes from the ExtUtils::Manifest module,
1853 where additional documentation can be found.
1854 .IP "make distcheck" 4
1855 .IX Item "make distcheck"
1856 reports which files are below the build directory but not in the
1857 MANIFEST file and vice versa. (See "fullcheck" in ExtUtils::Manifest for
1858 details)
1859 .IP "make skipcheck" 4
1860 .IX Item "make skipcheck"
1861 reports which files are skipped due to the entries in the
1862 \&\f(CW\*(C`MANIFEST.SKIP\*(C'\fR file (See "skipcheck" in ExtUtils::Manifest for
1863 details)
1864 .IP "make distclean" 4
1865 .IX Item "make distclean"
1866 does a realclean first and then the distcheck. Note that this is not
1867 needed to build a new distribution as long as you are sure that the
1868 MANIFEST file is ok.
1869 .IP "make veryclean" 4
1870 .IX Item "make veryclean"
1871 does a realclean first and then removes backup files such as \f(CW\*(C`*~\*(C'\fR,
1872 \&\f(CW\*(C`*.bak\*(C'\fR, \f(CW\*(C`*.old\*(C'\fR and \f(CW\*(C`*.orig\*(C'\fR
1873 .IP "make manifest" 4
1874 .IX Item "make manifest"
1875 rewrites the MANIFEST file, adding all remaining files found (See
1876 "mkmanifest" in ExtUtils::Manifest for details)
1877 .IP "make distdir" 4
1878 .IX Item "make distdir"
1879 Copies all the files that are in the MANIFEST file to a newly created
1880 directory with the name \f(CW\*(C`$(DISTNAME)\-$(VERSION)\*(C'\fR. If that directory
1881 exists, it will be removed first.
1882 .Sp
1883 Additionally, it will create META.yml and META.json module meta\-data file
1884 in the distdir and add this to the distdir\*(Aqs MANIFEST. You can shut this
1885 behavior off with the NO_META flag.
1886 .IP "make disttest" 4
1887 .IX Item "make disttest"
1888 Makes a distdir first, and runs a \f(CW\*(C`perl Makefile.PL\*(C'\fR, a make, and
1889 a make test in that directory.
1890 .IP "make tardist" 4
1891 .IX Item "make tardist"
1892 First does a distdir. Then a command $(PREOP) which defaults to a null
1893 command, followed by $(TO_UNIX), which defaults to a null command under
1894 UNIX, and will convert files in distribution directory to UNIX format
1895 otherwise. Next it runs \f(CW\*(C`tar\*(C'\fR on that directory into a tarfile and
1896 deletes the directory. Finishes with a command $(POSTOP) which
1897 defaults to a null command.
1898 .IP "make dist" 4
1899 .IX Item "make dist"
1900 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1901 .IP "make uutardist" 4
1902 .IX Item "make uutardist"
1903 Runs a tardist first and uuencodes the tarfile.
1904 .IP "make shdist" 4
1905 .IX Item "make shdist"
1906 First does a distdir. Then a command $(PREOP) which defaults to a null
1907 command. Next it runs \f(CW\*(C`shar\*(C'\fR on that directory into a sharfile and
1908 deletes the intermediate directory again. Finishes with a command
1909 $(POSTOP) which defaults to a null command. Note: For shdist to work
1910 properly a \f(CW\*(C`shar\*(C'\fR program that can handle directories is mandatory.
1911 .IP "make zipdist" 4
1912 .IX Item "make zipdist"
1913 First does a distdir. Then a command $(PREOP) which defaults to a null
1914 command. Runs \f(CW\*(C`$(ZIP) $(ZIPFLAGS)\*(C'\fR on that directory into a
1915 zipfile. Then deletes that directory. Finishes with a command
1916 $(POSTOP) which defaults to a null command.
1917 .IP "make ci" 4
1918 .IX Item "make ci"
1919 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1920 .PP
1921 Customization of the dist targets can be done by specifying a hash
1922 reference to the dist attribute of the WriteMakefile call. The
1923 following parameters are recognized:
1924 .PP
1925 .Vb 12
1926 \& CI (\*(Aqci \-u\*(Aq)
1927 \& COMPRESS (\*(Aqgzip \-\-best\*(Aq)
1928 \& POSTOP (\*(Aq@ :\*(Aq)
1929 \& PREOP (\*(Aq@ :\*(Aq)
1930 \& TO_UNIX (depends on the system)
1931 \& RCS_LABEL (\*(Aqrcs \-q \-Nv$(VERSION_SYM):\*(Aq)
1932 \& SHAR (\*(Aqshar\*(Aq)
1933 \& SUFFIX (\*(Aq.gz\*(Aq)
1934 \& TAR (\*(Aqtar\*(Aq)
1935 \& TARFLAGS (\*(Aqcvf\*(Aq)
1936 \& ZIP (\*(Aqzip\*(Aq)
1937 \& ZIPFLAGS (\*(Aq\-r\*(Aq)
1938 .Ve
1939 .PP
1940 An example:
1941 .PP
1942 .Vb 7
1943 \& WriteMakefile(
1944 \& ...other options...
1945 \& dist => {
1946 \& COMPRESS => "bzip2",
1947 \& SUFFIX => ".bz2"
1948 \& }
1949 \& );
1950 .Ve
1951 .SS "Module Meta\-Data (META and MYMETA)"
1952 .IX Subsection "Module Meta-Data (META and MYMETA)"
1953 Long plaguing users of MakeMaker based modules has been the problem of
1954 getting basic information about the module out of the sources
1955 \&\fIwithout\fR running the \fIMakefile.PL\fR and doing a bunch of messy
1956 heuristics on the resulting \fIMakefile\fR. Over the years, it has become
1957 standard to keep this information in one or more CPAN Meta files
1958 distributed with each distribution.
1959 .PP
1960 The original format of CPAN Meta files was YAML and the corresponding
1961 file was called \fIMETA.yml\fR. In 2010, version 2 of the CPAN::Meta::Spec
1962 was released, which mandates JSON format for the metadata in order to
1963 overcome certain compatibility issues between YAML serializers and to
1964 avoid breaking older clients unable to handle a new version of the spec.
1965 The CPAN::Meta library is now standard for accessing old and new\-style
1966 Meta files.
1967 .PP
1968 If CPAN::Meta is installed, MakeMaker will automatically generate
1969 \&\fIMETA.json\fR and \fIMETA.yml\fR files for you and add them to your \fIMANIFEST\fR as
1970 part of the \*(Aqdistdir\*(Aq target (and thus the \*(Aqdist\*(Aq target). This is intended to
1971 seamlessly and rapidly populate CPAN with module meta\-data. If you wish to
1972 shut this feature off, set the \f(CW\*(C`NO_META\*(C'\fR \f(CWWriteMakefile()\fR flag to true.
1973 .PP
1974 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers agreed
1975 to use the CPAN Meta format to communicate post\-configuration requirements
1976 between toolchain components. These files, \fIMYMETA.json\fR and \fIMYMETA.yml\fR,
1977 are generated when \fIMakefile.PL\fR generates a \fIMakefile\fR (if CPAN::Meta
1978 is installed). Clients like CPAN or CPANPLUS will read these
1979 files to see what prerequisites must be fulfilled before building or testing
1980 the distribution. If you wish to shut this feature off, set the \f(CW\*(C`NO_MYMETA\*(C'\fR
1981 \&\f(CWWriteMakefile()\fR flag to true.
1982 .SS "Disabling an extension"
1983 .IX Subsection "Disabling an extension"
1984 If some events detected in \fIMakefile.PL\fR imply that there is no way
1985 to create the Module, but this is a normal state of things, then you
1986 can create a \fIMakefile\fR which does nothing, but succeeds on all the
1987 "usual" build targets. To do so, use
1988 .PP
1989 .Vb 2
1990 \& use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1991 \& WriteEmptyMakefile();
1992 .Ve
1993 .PP
1994 instead of \fBWriteMakefile()\fR.
1995 .PP
1996 This may be useful if other modules expect this module to be \fIbuilt\fR
1997 OK, as opposed to \fIwork\fR OK (say, this system\-dependent module builds
1998 in a subdirectory of some other distribution, or is listed as a
1999 dependency in a CPAN::Bundle, but the functionality is supported by
2000 different means on the current architecture).
2001 .SS "Other Handy Functions"
2002 .IX Subsection "Other Handy Functions"
2003 .IP prompt 4
2004 .IX Item "prompt"
2005 .Vb 2
2006 \& my $value = prompt($message);
2007 \& my $value = prompt($message, $default);
2008 .Ve
2009 .Sp
2010 The \f(CWprompt()\fR function provides an easy way to request user input
2011 used to write a makefile. It displays the \f(CW$message\fR as a prompt for
2012 input. If a \f(CW$default\fR is provided it will be used as a default. The
2013 function returns the \f(CW$value\fR selected by the user.
2014 .Sp
2015 If \f(CWprompt()\fR detects that it is not running interactively and there
2016 is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
2017 is set to true, the \f(CW$default\fR will be used without prompting. This
2018 prevents automated processes from blocking on user input.
2019 .Sp
2020 If no \f(CW$default\fR is provided an empty string will be used instead.
2021 .IP os_unsupported 4
2022 .IX Item "os_unsupported"
2023 .Vb 2
2024 \& os_unsupported();
2025 \& os_unsupported if $^O eq \*(AqMSWin32\*(Aq;
2026 .Ve
2027 .Sp
2028 The \f(CWos_unsupported()\fR function provides a way to correctly exit your
2029 \&\f(CW\*(C`Makefile.PL\*(C'\fR before calling \f(CW\*(C`WriteMakefile\*(C'\fR. It is essentially a
2030 \&\f(CW\*(C`die\*(C'\fR with the message "OS unsupported".
2031 .Sp
2032 This is supported since 7.26
2033 .SS "Supported versions of Perl"
2034 .IX Subsection "Supported versions of Perl"
2035 Please note that while this module works on Perl 5.6, it is no longer
2036 being routinely tested on 5.6 \- the earliest Perl version being routinely
2037 tested, and expressly supported, is 5.8.1. However, patches to repair
2038 any breakage on 5.6 are still being accepted.
2039 .SH ENVIRONMENT
2040 .IX Header "ENVIRONMENT"
2041 .IP PERL_MM_OPT 4
2042 .IX Item "PERL_MM_OPT"
2043 Command line options used by \f(CW\*(C`MakeMaker\->new()\*(C'\fR, and thus by
2044 \&\f(CWWriteMakefile()\fR. The string is split as the shell would, and the result
2045 is processed before any actual command line arguments are processed.
2046 .Sp
2047 .Vb 1
2048 \& PERL_MM_OPT=\*(AqCCFLAGS="\-Wl,\-rpath \-Wl,/foo/bar/lib" LIBS="\-lwibble \-lwobble"\*(Aq
2049 .Ve
2050 .IP PERL_MM_USE_DEFAULT 4
2051 .IX Item "PERL_MM_USE_DEFAULT"
2052 If set to a true value then MakeMaker\*(Aqs prompt function will
2053 always return the default without waiting for user input.
2054 .IP PERL_CORE 4
2055 .IX Item "PERL_CORE"
2056 Same as the PERL_CORE parameter. The parameter overrides this.
2057 .SH "SEE ALSO"
2058 .IX Header "SEE ALSO"
2059 Module::Build is a pure\-Perl alternative to MakeMaker which does
2060 not rely on make or any other external utility. It may be easier to
2061 extend to suit your needs.
2062 .PP
2063 Module::Build::Tiny is a minimal pure\-Perl alternative to MakeMaker
2064 that follows the Build.PL protocol of Module::Build but without its
2065 complexity and cruft, implementing only the installation of the module
2066 and leaving authoring to mbtiny or other authoring tools.
2067 .PP
2068 Module::Install is a (now discouraged) wrapper around MakeMaker which
2069 adds features not normally available.
2070 .PP
2071 ExtUtils::ModuleMaker and Module::Starter are both modules to
2072 help you setup your distribution.
2073 .PP
2074 CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
2075 .PP
2076 File::ShareDir::Install makes it easy to install static, sometimes
2077 also referred to as \*(Aqshared\*(Aq files. File::ShareDir helps accessing
2078 the shared files after installation. Test::File::ShareDir helps when
2079 writing tests to use the shared files both before and after installation.
2080 .PP
2081 Dist::Zilla is an authoring tool which allows great customization and
2082 extensibility of the author experience, relying on the existing install
2083 tools like ExtUtils::MakeMaker only for installation.
2084 .PP
2085 Dist::Milla is a Dist::Zilla bundle that greatly simplifies common
2086 usage.
2087 .PP
2088 Minilla is a minimal authoring tool that does the same things as
2089 Dist::Milla without the overhead of Dist::Zilla.
2090 .SH AUTHORS
2091 .IX Header "AUTHORS"
2092 Andy Dougherty \f(CW\*(C`[email protected]\*(C'\fR, Andreas König
2093 \&\f(CW\*(C`[email protected]\*(C'\fR, Tim Bunce \f(CW\*(C`[email protected]\*(C'\fR. VMS
2094 support by Charles Bailey \f(CW\*(C`[email protected]\*(C'\fR. OS/2 support
2095 by Ilya Zakharevich \f(CW\*(C`[email protected]\-state.edu\*(C'\fR.
2096 .PP
2097 Currently maintained by Michael G Schwern \f(CW\*(C`[email protected]\*(C'\fR
2098 .PP
2099 Send patches and ideas to \f(CW\*(C`[email protected]\*(C'\fR.
2100 .PP
2101 Send bug reports via http://rt.cpan.org/. Please send your
2102 generated Makefile along with your report.
2103 .PP
2104 For more up\-to\-date information, see <https://metacpan.org/release/ExtUtils\-MakeMaker>.
2105 .PP
2106 Repository available at <https://github.com/Perl\-Toolchain\-Gang/ExtUtils\-MakeMaker>.
2107 .SH LICENSE
2108 .IX Header "LICENSE"
2109 This program is free software; you can redistribute it and/or
2110 modify it under the same terms as Perl itself.
2111 .PP
2112 See <http://www.perl.com/perl/misc/Artistic.html>