1ExtUtils::MakeMaker(3)User Contributed Perl DocumentationExtUtils::MakeMaker(3)
2
6 ExtUtils::MakeMaker - Create a module Makefile
7
9 use ExtUtils::MakeMaker;
10 WriteMakefile(
12 NAME => "Foo::Bar",
13 VERSION_FROM => "lib/Foo/Bar.pm",
14 );
15
17 This utility is designed to write a Makefile for an extension module
18 from a Makefile.PL. It is based on the Makefile.SH model provided by
19 Andy Dougherty and the perl5-porters.
20 It splits the task of generating the Makefile into several subroutines
22 that can be individually overridden. Each subroutine returns the text
23 it wishes to have written to the Makefile.
24 As there are various Make programs with incompatible syntax, which use
26 operating system shells, again with incompatible syntax, it is
27 important for users of this module to know which flavour of Make a
28 Makefile has been written for so they'll use the correct one and won't
29 have to face the possibly bewildering errors resulting from using the
30 wrong one.
31 On POSIX systems, that program will likely be GNU Make; on Microsoft
33 Windows, it will be either Microsoft NMake, DMake or GNU Make. See the
34 section on the "MAKE" parameter for details.
35 ExtUtils::MakeMaker (EUMM) is object oriented. Each directory below the
37 current directory that contains a Makefile.PL is treated as a separate
38 object. This makes it possible to write an unlimited number of
39 Makefiles with a single invocation of WriteMakefile().
40 All inputs to WriteMakefile are Unicode characters, not just octets.
42 EUMM seeks to handle all of these correctly. It is currently still not
43 possible to portably use Unicode characters in module names, because
44 this requires Perl to handle Unicode filenames, which is not yet the
45 case on Windows.
46 How To Write A Makefile.PL
48 See ExtUtils::MakeMaker::Tutorial.
49 The long answer is the rest of the manpage :-)
51 Default Makefile Behaviour
53 The generated Makefile enables the user of the extension to invoke
54 perl Makefile.PL # optionally "perl Makefile.PL verbose"
56 make
57 make test # optionally set TEST_VERBOSE=1
58 make install # See below
59 The Makefile to be produced may be altered by adding arguments of the
61 form "KEY=VALUE". E.g.
62 perl Makefile.PL INSTALL_BASE=~
64 Other interesting targets in the generated Makefile are
66 make config # to check if the Makefile is up-to-date
68 make clean # delete local temp files (Makefile gets renamed)
69 make realclean # delete derived files (including ./blib)
70 make ci # check in all the files in the MANIFEST file
71 make dist # see below the Distribution Support section
72 make test
74 MakeMaker checks for the existence of a file named test.pl in the
75 current directory, and if it exists it executes the script with the
76 proper set of perl "-I" options.
77 MakeMaker also checks for any files matching glob("t/*.t"). It will
79 execute all matching files in alphabetical order via the Test::Harness
80 module with the "-I" switches set correctly.
81 You can also organize your tests within subdirectories in the t/
83 directory. To do so, use the test directive in your Makefile.PL. For
84 example, if you had tests in:
85 t/foo
87 t/foo/bar
88 You could tell make to run tests in both of those directories with the
90 following directives:
91 test => {TESTS => 't/*/*.t t/*/*/*.t'}
93 test => {TESTS => 't/foo/*.t t/foo/bar/*.t'}
94 The first will run all test files in all first-level subdirectories and
96 all subdirectories they contain. The second will run tests in only the
97 t/foo and t/foo/bar.
98 If you'd like to see the raw output of your tests, set the
100 "TEST_VERBOSE" variable to true.
101 make test TEST_VERBOSE=1
103 If you want to run particular test files, set the "TEST_FILES"
105 variable. It is possible to use globbing with this mechanism.
106 make test TEST_FILES='t/foobar.t t/dagobah*.t'
108 Windows users who are using "nmake" should note that due to a bug in
110 "nmake", when specifying "TEST_FILES" you must use back-slashes instead
111 of forward-slashes.
112 nmake test TEST_FILES='t\foobar.t t\dagobah*.t'
114 make testdb
116 A useful variation of the above is the target "testdb". It runs the
117 test under the Perl debugger (see perldebug). If the file test.pl
118 exists in the current directory, it is used for the test.
119 If you want to debug some other testfile, set the "TEST_FILE" variable
121 thusly:
122 make testdb TEST_FILE=t/mytest.t
124 By default the debugger is called using "-d" option to perl. If you
126 want to specify some other option, set the "TESTDB_SW" variable:
127 make testdb TESTDB_SW=-Dx
129 make install
131 make alone puts all relevant files into directories that are named by
132 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
133 INST_MAN3DIR. All these default to something below ./blib if you are
134 not building below the perl source directory. If you are building below
135 the perl source, INST_LIB and INST_ARCHLIB default to ../../lib, and
136 INST_SCRIPT is not defined.
137 The install target of the generated Makefile copies the files found
139 below each of the INST_* directories to their INSTALL* counterparts.
140 Which counterparts are chosen depends on the setting of INSTALLDIRS
141 according to the following table:
142 INSTALLDIRS set to
144 perl site vendor
145 PERLPREFIX SITEPREFIX VENDORPREFIX
147 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
148 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
149 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
150 INST_SCRIPT INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
151 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
152 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
153 The INSTALL... macros in turn default to their %Config
155 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
156 You can check the values of these variables on your system with
158 perl '-V:install.*'
160 And to check the sequence in which the library directories are searched
162 by perl, run
163 perl -le 'print join $/, @INC'
165 Sometimes older versions of the module you're installing live in other
167 directories in @INC. Because Perl loads the first version of a module
168 it finds, not the newest, you might accidentally get one of these older
169 versions even after installing a brand new version. To delete all
170 other versions of the module you're installing (not simply older ones)
171 set the "UNINST" variable.
172 make install UNINST=1
174 INSTALL_BASE
176 INSTALL_BASE can be passed into Makefile.PL to change where your module
177 will be installed. INSTALL_BASE is more like what everyone else calls
178 "prefix" than PREFIX is.
179 To have everything installed in your home directory, do the following.
181 # Unix users, INSTALL_BASE=~ works fine
183 perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
184 Like PREFIX, it sets several INSTALL* attributes at once. Unlike
186 PREFIX it is easy to predict where the module will end up. The
187 installation pattern looks like this:
188 INSTALLARCHLIB INSTALL_BASE/lib/perl5/$Config{archname}
190 INSTALLPRIVLIB INSTALL_BASE/lib/perl5
191 INSTALLBIN INSTALL_BASE/bin
192 INSTALLSCRIPT INSTALL_BASE/bin
193 INSTALLMAN1DIR INSTALL_BASE/man/man1
194 INSTALLMAN3DIR INSTALL_BASE/man/man3
195 INSTALL_BASE in MakeMaker and "--install_base" in Module::Build (as of
197 0.28) install to the same location. If you want MakeMaker and
198 Module::Build to install to the same location simply set INSTALL_BASE
199 and "--install_base" to the same location.
200 INSTALL_BASE was added in 6.31.
202 PREFIX and LIB attribute
204 PREFIX and LIB can be used to set several INSTALL* attributes in one
205 go. Here's an example for installing into your home directory.
206 # Unix users, PREFIX=~ works fine
208 perl Makefile.PL PREFIX=/path/to/your/home/dir
209 This will install all files in the module under your home directory,
211 with man pages and libraries going into an appropriate place (usually
212 ~/man and ~/lib). How the exact location is determined is complicated
213 and depends on how your Perl was configured. INSTALL_BASE works more
214 like what other build systems call "prefix" than PREFIX and we
215 recommend you use that instead.
216 Another way to specify many INSTALL directories with a single parameter
218 is LIB.
219 perl Makefile.PL LIB=~/lib
221 This will install the module's architecture-independent files into
223 ~/lib, the architecture-dependent files into ~/lib/$archname.
224 Note, that in both cases the tilde expansion is done by MakeMaker, not
226 by perl by default, nor by make.
227 Conflicts between parameters LIB, PREFIX and the various INSTALL*
229 arguments are resolved so that:
230 · setting LIB overrides any setting of INSTALLPRIVLIB,
232 INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not
233 affected by PREFIX);
234 · without LIB, setting PREFIX replaces the initial $Config{prefix}
236 part of those INSTALL* arguments, even if the latter are explicitly
237 set (but are set to still start with $Config{prefix}).
238 If the user has superuser privileges, and is not working on AFS or
240 relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
241 INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
242 the best:
243 perl Makefile.PL;
245 make;
246 make test
247 make install
248 make install by default writes some documentation of what has been done
250 into the file "$(INSTALLARCHLIB)/perllocal.pod". This feature can be
251 bypassed by calling make pure_install.
252 AFS users
254 will have to specify the installation directories as these most
255 probably have changed since perl itself has been installed. They will
256 have to do this by calling
257 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
259 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
260 make
261 Be careful to repeat this procedure every time you recompile an
263 extension, unless you are sure the AFS installation directories are
264 still valid.
265 Static Linking of a new Perl Binary
267 An extension that is built with the above steps is ready to use on
268 systems supporting dynamic loading. On systems that do not support
269 dynamic loading, any newly created extension has to be linked together
270 with the available resources. MakeMaker supports the linking process by
271 creating appropriate targets in the Makefile whenever an extension is
272 built. You can invoke the corresponding section of the makefile with
273 make perl
275 That produces a new perl binary in the current directory with all
277 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP, and
278 PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on UNIX,
279 this is called Makefile.aperl (may be system dependent). If you want to
280 force the creation of a new perl, it is recommended that you delete
281 this Makefile.aperl, so the directories are searched through for
282 linkable libraries again.
283 The binary can be installed into the directory where perl normally
285 resides on your machine with
286 make inst_perl
288 To produce a perl binary with a different name than "perl", either say
290 perl Makefile.PL MAP_TARGET=myperl
292 make myperl
293 make inst_perl
294 or say
296 perl Makefile.PL
298 make myperl MAP_TARGET=myperl
299 make inst_perl MAP_TARGET=myperl
300 In any case you will be prompted with the correct invocation of the
302 "inst_perl" target that installs the new binary into INSTALLBIN.
303 make inst_perl by default writes some documentation of what has been
305 done into the file "$(INSTALLARCHLIB)/perllocal.pod". This can be
306 bypassed by calling make pure_inst_perl.
307 Warning: the inst_perl: target will most probably overwrite your
309 existing perl binary. Use with care!
310 Sometimes you might want to build a statically linked perl although
312 your system supports dynamic loading. In this case you may explicitly
313 set the linktype with the invocation of the Makefile.PL or make:
314 perl Makefile.PL LINKTYPE=static # recommended
316 or
318 make LINKTYPE=static # works on most systems
320 Determination of Perl Library and Installation Locations
322 MakeMaker needs to know, or to guess, where certain things are located.
323 Especially INST_LIB and INST_ARCHLIB (where to put the files during the
324 make(1) run), PERL_LIB and PERL_ARCHLIB (where to read existing modules
325 from), and PERL_INC (header files and "libperl*.*").
326 Extensions may be built either using the contents of the perl source
328 directory tree or from the installed perl library. The recommended way
329 is to build extensions after you have run 'make install' on perl
330 itself. You can do that in any directory on your hard disk that is not
331 below the perl source tree. The support for extensions below the ext
332 directory of the perl distribution is only good for the standard
333 extensions that come with perl.
334 If an extension is being built below the "ext/" directory of the perl
336 source then MakeMaker will set PERL_SRC automatically (e.g., "../..").
337 If PERL_SRC is defined and the extension is recognized as a standard
338 extension, then other variables default to the following:
339 PERL_INC = PERL_SRC
341 PERL_LIB = PERL_SRC/lib
342 PERL_ARCHLIB = PERL_SRC/lib
343 INST_LIB = PERL_LIB
344 INST_ARCHLIB = PERL_ARCHLIB
345 If an extension is being built away from the perl source then MakeMaker
347 will leave PERL_SRC undefined and default to using the installed copy
348 of the perl library. The other variables default to the following:
349 PERL_INC = $archlibexp/CORE
351 PERL_LIB = $privlibexp
352 PERL_ARCHLIB = $archlibexp
353 INST_LIB = ./blib/lib
354 INST_ARCHLIB = ./blib/arch
355 If perl has not yet been installed then PERL_SRC can be defined on the
357 command line as shown in the previous section.
358 Which architecture dependent directory?
360 If you don't want to keep the defaults for the INSTALL* macros,
361 MakeMaker helps you to minimize the typing needed: the usual
362 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined by
363 Configure at perl compilation time. MakeMaker supports the user who
364 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
365 then MakeMaker defaults the latter to be the same subdirectory of
366 INSTALLPRIVLIB as Configure decided for the counterparts in %Config,
367 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
368 for INSTALLSITELIB and INSTALLSITEARCH.
369 MakeMaker gives you much more freedom than needed to configure internal
371 variables and get different results. It is worth mentioning that
372 make(1) also lets you configure most of the variables that are used in
373 the Makefile. But in the majority of situations this will not be
374 necessary, and should only be done if the author of a package
375 recommends it (or you know what you're doing).
376 Using Attributes and Parameters
378 The following attributes may be specified as arguments to
379 WriteMakefile() or as NAME=VALUE pairs on the command line. Attributes
380 that became available with later versions of MakeMaker are indicated.
381 In order to maintain portability of attributes with older versions of
383 MakeMaker you may want to use App::EUMM::Upgrade with your
384 "Makefile.PL".
385 ABSTRACT
387 One line description of the module. Will be included in PPD file.
388 ABSTRACT_FROM
390 Name of the file that contains the package description. MakeMaker
391 looks for a line in the POD matching /^($package\s-\s)(.*)/. This is
392 typically the first line in the "=head1 NAME" section. $2 becomes the
393 abstract.
394 AUTHOR
396 Array of strings containing name (and email address) of package
397 author(s). Is used in CPAN Meta files (META.yml or META.json) and
398 PPD (Perl Package Description) files for PPM (Perl Package Manager).
399 BINARY_LOCATION
401 Used when creating PPD files for binary packages. It can be set to a
402 full or relative path or URL to the binary archive for a particular
403 architecture. For example:
404 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
406 builds a PPD package that references a binary of the "Agent" package,
408 located in the "x86" directory relative to the PPD itself.
409 BUILD_REQUIRES
411 Available in version 6.55_03 and above.
412 A hash of modules that are needed to build your module but not run
414 it.
415 This will go into the "build_requires" field of your META.yml and the
417 "build" of the "prereqs" field of your META.json.
418 Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
420 specified.
421 The format is the same as PREREQ_PM.
423 C Ref to array of *.c file names. Initialised from a directory scan and
425 the values portion of the XS attribute hash. This is not currently
426 used by MakeMaker but may be handy in Makefile.PLs.
427 CCFLAGS
429 String that will be included in the compiler call command line
430 between the arguments INC and OPTIMIZE.
431 CONFIG
433 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
434 config.sh. MakeMaker will add to CONFIG the following values anyway:
435 ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
436 lib_ext obj_ext ranlib sitelibexp sitearchexp so
437 CONFIGURE
439 CODE reference. The subroutine should return a hash reference. The
440 hash may contain further attributes, e.g. {LIBS => ...}, that have to
441 be determined by some evaluation method.
442 CONFIGURE_REQUIRES
444 Available in version 6.52 and above.
445 A hash of modules that are required to run Makefile.PL itself, but
447 not to run your distribution.
448 This will go into the "configure_requires" field of your META.yml and
450 the "configure" of the "prereqs" field of your META.json.
451 Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
453 specified.
454 The format is the same as PREREQ_PM.
456 DEFINE
458 Something like "-DHAVE_UNISTD_H"
459 DESTDIR
461 This is the root directory into which the code will be installed. It
462 prepends itself to the normal prefix. For example, if your code
463 would normally go into /usr/local/lib/perl you could set
464 DESTDIR=~/tmp/ and installation would go into
465 ~/tmp/usr/local/lib/perl.
466 This is primarily of use for people who repackage Perl modules.
468 NOTE: Due to the nature of make, it is important that you put the
470 trailing slash on your DESTDIR. ~/tmp/ not ~/tmp.
471 DIR
473 Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
474 in ext/SDBM_File
475 DISTNAME
477 A safe filename for the package.
478 Defaults to NAME below but with :: replaced with -.
480 For example, Foo::Bar becomes Foo-Bar.
482 DISTVNAME
484 Your name for distributing the package with the version number
485 included. This is used by 'make dist' to name the resulting archive
486 file.
487 Defaults to DISTNAME-VERSION.
489 For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
491 On some OS's where . has special meaning VERSION_SYM may be used in
493 place of VERSION.
494 DLEXT
496 Specifies the extension of the module's loadable object. For example:
497 DLEXT => 'unusual_ext', # Default value is $Config{so}
499 NOTE: When using this option to alter the extension of a module's
501 loadable object, it is also necessary that the module's pm file
502 specifies the same change:
503 local $DynaLoader::dl_dlext = 'unusual_ext';
505 DL_FUNCS
507 Hashref of symbol names for routines to be made available as
508 universal symbols. Each key/value pair consists of the package name
509 and an array of routine names in that package. Used only under AIX,
510 OS/2, VMS and Win32 at present. The routine names supplied will be
511 expanded in the same way as XSUB names are expanded by the XS()
512 macro. Defaults to
513 {"$(NAME)" => ["boot_$(NAME)" ] }
515 e.g.
517 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
519 "NetconfigPtr" => [ 'DESTROY'] }
520 Please see the ExtUtils::Mksymlists documentation for more
522 information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
523 DL_VARS
525 Array of symbol names for variables to be made available as universal
526 symbols. Used only under AIX, OS/2, VMS and Win32 at present.
527 Defaults to []. (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
528 EXCLUDE_EXT
530 Array of extension names to exclude when doing a static build. This
531 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
532 details. (e.g. [ qw( Socket POSIX ) ] )
533 This attribute may be most useful when specified as a string on the
535 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
536 EXE_FILES
538 Ref to array of executable files. The files will be copied to the
539 INST_SCRIPT directory. Make realclean will delete them from there
540 again.
541 If your executables start with something like #!perl or
543 #!/usr/bin/perl MakeMaker will change this to the path of the perl
544 'Makefile.PL' was invoked with so the programs will be sure to run
545 properly even if perl is not in /usr/bin/perl.
546 FIRST_MAKEFILE
548 The name of the Makefile to be produced. This is used for the second
549 Makefile that will be produced for the MAP_TARGET.
550 Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
552 (Note: we couldn't use MAKEFILE because dmake uses this for something
554 else).
555 FULLPERL
557 Perl binary able to run this extension, load XS modules, etc...
558 FULLPERLRUN
560 Like PERLRUN, except it uses FULLPERL.
561 FULLPERLRUNINST
563 Like PERLRUNINST, except it uses FULLPERL.
564 FUNCLIST
566 This provides an alternate means to specify function names to be
567 exported from the extension. Its value is a reference to an array of
568 function names to be exported by the extension. These names are
569 passed through unaltered to the linker options file.
570 H Ref to array of *.h file names. Similar to C.
572 IMPORTS
574 This attribute is used to specify names to be imported into the
575 extension. Takes a hash ref.
576 It is only used on OS/2 and Win32.
578 INC
580 Include file dirs eg: "-I/usr/5include -I/path/to/inc"
581 INCLUDE_EXT
583 Array of extension names to be included when doing a static build.
584 MakeMaker will normally build with all of the installed extensions
585 when doing a static build, and that is usually the desired behavior.
586 If INCLUDE_EXT is present then MakeMaker will build only with those
587 extensions which are explicitly mentioned. (e.g. [ qw( Socket POSIX
588 ) ])
589 It is not necessary to mention DynaLoader or the current extension
591 when filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is
592 empty then only DynaLoader and the current extension will be included
593 in the build.
594 This attribute may be most useful when specified as a string on the
596 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket
597 Devel::Peek'
598 INSTALLARCHLIB
600 Used by 'make install', which copies files from INST_ARCHLIB to this
601 directory if INSTALLDIRS is set to perl.
602 INSTALLBIN
604 Directory to install binary files (e.g. tkperl) into if
605 INSTALLDIRS=perl.
606 INSTALLDIRS
608 Determines which of the sets of installation directories to choose:
609 perl, site or vendor. Defaults to site.
610 INSTALLMAN1DIR
612 INSTALLMAN3DIR
613 These directories get the man pages at 'make install' time if
614 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
615 If set to 'none', no man pages will be installed.
617 INSTALLPRIVLIB
619 Used by 'make install', which copies files from INST_LIB to this
620 directory if INSTALLDIRS is set to perl.
621 Defaults to $Config{installprivlib}.
623 INSTALLSCRIPT
625 Available in version 6.30_02 and above.
626 Used by 'make install' which copies files from INST_SCRIPT to this
628 directory if INSTALLDIRS=perl.
629 INSTALLSITEARCH
631 Used by 'make install', which copies files from INST_ARCHLIB to this
632 directory if INSTALLDIRS is set to site (default).
633 INSTALLSITEBIN
635 Used by 'make install', which copies files from INST_BIN to this
636 directory if INSTALLDIRS is set to site (default).
637 INSTALLSITELIB
639 Used by 'make install', which copies files from INST_LIB to this
640 directory if INSTALLDIRS is set to site (default).
641 INSTALLSITEMAN1DIR
643 INSTALLSITEMAN3DIR
644 These directories get the man pages at 'make install' time if
645 INSTALLDIRS=site (default). Defaults to
646 $(SITEPREFIX)/man/man$(MAN*EXT).
647 If set to 'none', no man pages will be installed.
649 INSTALLSITESCRIPT
651 Used by 'make install' which copies files from INST_SCRIPT to this
652 directory if INSTALLDIRS is set to site (default).
653 INSTALLVENDORARCH
655 Used by 'make install', which copies files from INST_ARCHLIB to this
656 directory if INSTALLDIRS is set to vendor. Note that if you do not
657 set this, the value of INSTALLVENDORLIB will be used, which is
658 probably not what you want.
659 INSTALLVENDORBIN
661 Used by 'make install', which copies files from INST_BIN to this
662 directory if INSTALLDIRS is set to vendor.
663 INSTALLVENDORLIB
665 Used by 'make install', which copies files from INST_LIB to this
666 directory if INSTALLDIRS is set to vendor.
667 INSTALLVENDORMAN1DIR
669 INSTALLVENDORMAN3DIR
670 These directories get the man pages at 'make install' time if
671 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
672 If set to 'none', no man pages will be installed.
674 INSTALLVENDORSCRIPT
676 Available in version 6.30_02 and above.
677 Used by 'make install' which copies files from INST_SCRIPT to this
679 directory if INSTALLDIRS is set to vendor.
680 INST_ARCHLIB
682 Same as INST_LIB for architecture dependent files.
683 INST_BIN
685 Directory to put real binary files during 'make'. These will be
686 copied to INSTALLBIN during 'make install'
687 INST_LIB
689 Directory where we put library files of this extension while building
690 it.
691 INST_MAN1DIR
693 Directory to hold the man pages at 'make' time
694 INST_MAN3DIR
696 Directory to hold the man pages at 'make' time
697 INST_SCRIPT
699 Directory where executable files should be installed during 'make'.
700 Defaults to "./blib/script", just to have a dummy location during
701 testing. make install will copy the files in INST_SCRIPT to
702 INSTALLSCRIPT.
703 LD
705 Program to be used to link libraries for dynamic loading.
706 Defaults to $Config{ld}.
708 LDDLFLAGS
710 Any special flags that might need to be passed to ld to create a
711 shared library suitable for dynamic loading. It is up to the
712 makefile to use it. (See "lddlflags" in Config)
713 Defaults to $Config{lddlflags}.
715 LDFROM
717 Defaults to "$(OBJECT)" and is used in the ld command to specify what
718 files to link/load from (also see dynamic_lib below for how to
719 specify ld flags)
720 LIB
722 LIB should only be set at "perl Makefile.PL" time but is allowed as a
723 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
724 and INSTALLSITELIB to that value regardless any explicit setting of
725 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
726 are set to the corresponding architecture subdirectory.
727 LIBPERL_A
729 The filename of the perllibrary that will be used together with this
730 extension. Defaults to libperl.a.
731 LIBS
733 An anonymous array of alternative library specifications to be
734 searched for (in order) until at least one library is found. E.g.
735 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
737 Mind, that any element of the array contains a complete set of
739 arguments for the ld command. So do not specify
740 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
742 See ODBM_File/Makefile.PL for an example, where an array is needed.
744 If you specify a scalar as in
745 'LIBS' => "-ltcl -ltk -lX11"
747 MakeMaker will turn it into an array with one element.
749 LICENSE
751 Available in version 6.31 and above.
752 The licensing terms of your distribution. Generally it's "perl_5"
754 for the same license as Perl itself.
755 See CPAN::Meta::Spec for the list of options.
757 Defaults to "unknown".
759 LINKTYPE
761 'static' or 'dynamic' (default unless usedl=undef in config.sh).
762 Should only be used to force static linking (also see linkext below).
763 MAGICXS
765 Available in version 6.8305 and above.
766 When this is set to 1, "OBJECT" will be automagically derived from
768 "O_FILES".
769 MAKE
771 Available in version 6.30_01 and above.
772 Variant of make you intend to run the generated Makefile with. This
774 parameter lets Makefile.PL know what make quirks to account for when
775 generating the Makefile.
776 MakeMaker also honors the MAKE environment variable. This parameter
778 takes precedence.
779 Currently the only significant values are 'dmake' and 'nmake' for
781 Windows users, instructing MakeMaker to generate a Makefile in the
782 flavour of DMake ("Dennis Vadura's Make") or Microsoft NMake
783 respectively.
784 Defaults to $Config{make}, which may go looking for a Make program in
786 your environment.
787 How are you supposed to know what flavour of Make a Makefile has been
789 generated for if you didn't specify a value explicitly? Search the
790 generated Makefile for the definition of the MAKE variable, which is
791 used to recursively invoke the Make utility. That will tell you what
792 Make you're supposed to invoke the Makefile with.
793 MAKEAPERL
795 Boolean which tells MakeMaker that it should include the rules to
796 make a perl. This is handled automatically as a switch by MakeMaker.
797 The user normally does not need it.
798 MAKEFILE_OLD
800 When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
801 backed up at this location.
802 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
804 MAN1PODS
806 Hashref of pod-containing files. MakeMaker will default this to all
807 EXE_FILES files that include POD directives. The files listed here
808 will be converted to man pages and installed as was requested at
809 Configure time.
810 This hash should map POD files (or scripts containing POD) to the man
812 file names under the "blib/man1/" directory, as in the following
813 example:
814 MAN1PODS => {
816 'doc/command.pod' => 'blib/man1/command.1',
817 'scripts/script.pl' => 'blib/man1/script.1',
818 }
819 MAN3PODS
821 Hashref that assigns to *.pm and *.pod files the files into which the
822 manpages are to be written. MakeMaker parses all *.pod and *.pm files
823 for POD directives. Files that contain POD will be the default keys
824 of the MAN3PODS hashref. These will then be converted to man pages
825 during "make" and will be installed during "make install".
826 Example similar to MAN1PODS.
828 MAP_TARGET
830 If it is intended that a new perl binary be produced, this variable
831 may hold a name for that binary. Defaults to perl
832 META_ADD
834 META_MERGE
835 Available in version 6.46 and above.
836 A hashref of items to add to the CPAN Meta file (META.yml or
838 META.json).
839 They differ in how they behave if they have the same key as the
841 default metadata. META_ADD will override the default value with its
842 own. META_MERGE will merge its value with the default.
843 Unless you want to override the defaults, prefer META_MERGE so as to
845 get the advantage of any future defaults.
846 Where prereqs are concerned, if META_MERGE is used, prerequisites are
848 merged with their counterpart "WriteMakefile()" argument (PREREQ_PM
849 is merged into {prereqs}{runtime}{requires}, BUILD_REQUIRES into
850 "{prereqs}{build}{requires}", CONFIGURE_REQUIRES into
851 "{prereqs}{configure}{requires}", and TEST_REQUIRES into
852 "{prereqs}{test}{requires})". When prereqs are specified with
853 META_ADD, the only prerequisites added to the file come from the
854 metadata, not "WriteMakefile()" arguments.
855 Note that these configuration options are only used for generating
857 META.yml and META.json -- they are NOT used for MYMETA.yml and
858 MYMETA.json. Therefore data in these fields should NOT be used for
859 dynamic (user-side) configuration.
860 By default CPAN Meta specification 1.4 is used. In order to use CPAN
862 Meta specification 2.0, indicate with "meta-spec" the version you
863 want to use.
864 META_MERGE => {
866 "meta-spec" => { version => 2 },
868 resources => {
870 repository => {
872 type => 'git',
873 url => 'git://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker.git',
874 web => 'https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker',
875 },
876 },
878 },
880 MIN_PERL_VERSION
882 Available in version 6.48 and above.
883 The minimum required version of Perl for this distribution.
885 Either the 5.006001 or the 5.6.1 format is acceptable.
887 MYEXTLIB
889 If the extension links to a library that it builds, set this to the
890 name of the library (see SDBM_File)
891 NAME
893 The package representing the distribution. For example, "Test::More"
894 or "ExtUtils::MakeMaker". It will be used to derive information about
895 the distribution such as the "DISTNAME", installation locations
896 within the Perl library and where XS files will be looked for by
897 default (see "XS").
898 "NAME" must be a valid Perl package name and it must have an
900 associated ".pm" file. For example, "Foo::Bar" is a valid "NAME" and
901 there must exist Foo/Bar.pm. Any XS code should be in Bar.xs unless
902 stated otherwise.
903 Your distribution must have a "NAME".
905 NEEDS_LINKING
907 MakeMaker will figure out if an extension contains linkable code
908 anywhere down the directory tree, and will set this variable
909 accordingly, but you can speed it up a very little bit if you define
910 this boolean variable yourself.
911 NOECHO
913 Command so make does not print the literal commands it's running.
914 By setting it to an empty string you can generate a Makefile that
916 prints all commands. Mainly used in debugging MakeMaker itself.
917 Defaults to "@".
919 NORECURS
921 Boolean. Attribute to inhibit descending into subdirectories.
922 NO_META
924 When true, suppresses the generation and addition to the MANIFEST of
925 the META.yml and META.json module meta-data files during 'make
926 distdir'.
927 Defaults to false.
929 NO_MYMETA
931 Available in version 6.57_02 and above.
932 When true, suppresses the generation of MYMETA.yml and MYMETA.json
934 module meta-data files during 'perl Makefile.PL'.
935 Defaults to false.
937 NO_PACKLIST
939 Available in version 6.7501 and above.
940 When true, suppresses the writing of "packlist" files for installs.
942 Defaults to false.
944 NO_PERLLOCAL
946 Available in version 6.7501 and above.
947 When true, suppresses the appending of installations to "perllocal".
949 Defaults to false.
951 NO_VC
953 In general, any generated Makefile checks for the current version of
954 MakeMaker and the version the Makefile was built under. If NO_VC is
955 set, the version check is neglected. Do not write this into your
956 Makefile.PL, use it interactively instead.
957 OBJECT
959 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be
960 a long string or an array containing all object files, e.g.
961 "tkpBind.o tkpButton.o tkpCanvas.o" or ["tkpBind.o", "tkpButton.o",
962 "tkpCanvas.o"]
963 (Where BASEEXT is the last component of NAME, and OBJ_EXT is
965 $Config{obj_ext}.)
966 OPTIMIZE
968 Defaults to "-O". Set it to "-g" to turn debugging on. The flag is
969 passed to subdirectory makes.
970 PERL
972 Perl binary for tasks that can be done by miniperl. If it contains
973 spaces or other shell metacharacters, it needs to be quoted in a way
974 that protects them, since this value is intended to be inserted in a
975 shell command line in the Makefile. E.g.:
976 # Perl executable lives in "C:/Program Files/Perl/bin"
978 # Normally you don't need to set this yourself!
979 $ perl Makefile.PL PERL='"C:/Program Files/Perl/bin/perl.exe" -w'
980 PERL_CORE
982 Set only when MakeMaker is building the extensions of the Perl core
983 distribution.
984 PERLMAINCC
986 The call to the program that is able to compile perlmain.c. Defaults
987 to $(CC).
988 PERL_ARCHLIB
990 Same as for PERL_LIB, but for architecture dependent files.
991 Used only when MakeMaker is building the extensions of the Perl core
993 distribution (because normally $(PERL_ARCHLIB) is automatically in
994 @INC, and adding it would get in the way of PERL5LIB).
995 PERL_LIB
997 Directory containing the Perl library to use.
998 Used only when MakeMaker is building the extensions of the Perl core
1000 distribution (because normally $(PERL_LIB) is automatically in @INC,
1001 and adding it would get in the way of PERL5LIB).
1002 PERL_MALLOC_OK
1004 defaults to 0. Should be set to TRUE if the extension can work with
1005 the memory allocation routines substituted by the Perl malloc()
1006 subsystem. This should be applicable to most extensions with
1007 exceptions of those
1008 · with bugs in memory allocations which are caught by Perl's
1010 malloc();
1011 · which interact with the memory allocator in other ways than via
1013 malloc(), realloc(), free(), calloc(), sbrk() and brk();
1014 · which rely on special alignment which is not provided by Perl's
1016 malloc().
1017 NOTE. Neglecting to set this flag in any one of the loaded extension
1019 nullifies many advantages of Perl's malloc(), such as better usage of
1020 system resources, error detection, memory usage reporting, catchable
1021 failure of memory allocations, etc.
1022 PERLPREFIX
1024 Directory under which core modules are to be installed.
1025 Defaults to $Config{installprefixexp}, falling back to
1027 $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1028 $Config{installprefixexp} not exist.
1029 Overridden by PREFIX.
1031 PERLRUN
1033 Use this instead of $(PERL) when you wish to run perl. It will set
1034 up extra necessary flags for you.
1035 PERLRUNINST
1037 Use this instead of $(PERL) when you wish to run perl to work with
1038 modules. It will add things like -I$(INST_ARCH) and other necessary
1039 flags so perl can see the modules you're about to install.
1040 PERL_SRC
1042 Directory containing the Perl source code (use of this should be
1043 avoided, it may be undefined)
1044 PERM_DIR
1046 Available in version 6.51_01 and above.
1047 Desired permission for directories. Defaults to 755.
1049 PERM_RW
1051 Desired permission for read/writable files. Defaults to 644.
1052 PERM_RWX
1054 Desired permission for executable files. Defaults to 755.
1055 PL_FILES
1057 MakeMaker can run programs to generate files for you at build time.
1058 By default any file named *.PL (except Makefile.PL and Build.PL) in
1059 the top level directory will be assumed to be a Perl program and run
1060 passing its own basename in as an argument. This basename is
1061 actually a build target, and there is an intention, but not a
1062 requirement, that the *.PL file make the file passed to to as an
1063 argument. For example...
1064 perl foo.PL foo
1066 This behavior can be overridden by supplying your own set of files to
1068 search. PL_FILES accepts a hash ref, the key being the file to run
1069 and the value is passed in as the first argument when the PL file is
1070 run.
1071 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
1073 PL_FILES => {'foo.PL' => 'foo.c'}
1075 Would run bin/foobar.PL like this:
1077 perl bin/foobar.PL bin/foobar
1079 If multiple files from one program are desired an array ref can be
1081 used.
1082 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
1084 In this case the program will be run multiple times using each target
1086 file.
1087 perl bin/foobar.PL bin/foobar1
1089 perl bin/foobar.PL bin/foobar2
1090 If an output file depends on extra input files beside the script
1092 itself, a hash ref can be used in version 7.36 and above:
1093 PL_FILES => { 'foo.PL' => {
1095 'foo.out' => 'foo.in',
1096 'bar.out' => [qw(bar1.in bar2.in)],
1097 }
1098 In this case the extra input files will be passed to the program
1100 after the target file:
1101 perl foo.PL foo.out foo.in
1103 perl foo.PL bar.out bar1.in bar2.in
1104 PL files are normally run after pm_to_blib and include INST_LIB and
1106 INST_ARCH in their @INC, so the just built modules can be accessed...
1107 unless the PL file is making a module (or anything else in PM) in
1108 which case it is run before pm_to_blib and does not include INST_LIB
1109 and INST_ARCH in its @INC. This apparently odd behavior is there for
1110 backwards compatibility (and it's somewhat DWIM). The argument
1111 passed to the .PL is set up as a target to build in the Makefile. In
1112 other sections such as "postamble" you can specify a dependency on
1113 the filename/argument that the .PL is supposed (or will have, now
1114 that that is is a dependency) to generate. Note the file to be
1115 generated will still be generated and the .PL will still run even
1116 without an explicit dependency created by you, since the "all" target
1117 still depends on running all eligible to run.PL files.
1118 PM
1120 Hashref of .pm files and *.pl files to be installed. e.g.
1121 {'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
1123 By default this will include *.pm and *.pl and the files found in the
1125 PMLIBDIRS directories. Defining PM in the Makefile.PL will override
1126 PMLIBDIRS.
1127 PMLIBDIRS
1129 Ref to array of subdirectories containing library files. Defaults to
1130 [ 'lib', $(BASEEXT) ]. The directories will be scanned and any files
1131 they contain will be installed in the corresponding location in the
1132 library. A libscan() method can be used to alter the behaviour.
1133 Defining PM in the Makefile.PL will override PMLIBDIRS.
1134 (Where BASEEXT is the last component of NAME.)
1136 PM_FILTER
1138 A filter program, in the traditional Unix sense (input from stdin,
1139 output to stdout) that is passed on each .pm file during the build
1140 (in the pm_to_blib() phase). It is empty by default, meaning no
1141 filtering is done. You could use:
1142 PM_FILTER => 'perl -ne "print unless /^\\#/"',
1144 to remove all the leading comments on the fly during the build. In
1146 order to be as portable as possible, please consider using a Perl
1147 one-liner rather than Unix (or other) utilities, as above. The # is
1148 escaped for the Makefile, since what is going to be generated will
1149 then be:
1150 PM_FILTER = perl -ne "print unless /^\#/"
1152 Without the \ before the #, we'd have the start of a Makefile
1154 comment, and the macro would be incorrectly defined.
1155 You will almost certainly be better off using the "PL_FILES" system,
1157 instead. See above, or the ExtUtils::MakeMaker::FAQ entry.
1158 POLLUTE
1160 Release 5.005 grandfathered old global symbol names by providing
1161 preprocessor macros for extension source compatibility. As of
1162 release 5.6, these preprocessor definitions are not available by
1163 default. The POLLUTE flag specifies that the old names should still
1164 be defined:
1165 perl Makefile.PL POLLUTE=1
1167 Please inform the module author if this is necessary to successfully
1169 install a module under 5.6 or later.
1170 PPM_INSTALL_EXEC
1172 Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
1173 perl)
1174 PPM_INSTALL_SCRIPT
1176 Name of the script that gets executed by the Perl Package Manager
1177 after the installation of a package.
1178 PPM_UNINSTALL_EXEC
1180 Available in version 6.8502 and above.
1181 Name of the executable used to run "PPM_UNINSTALL_SCRIPT" below.
1183 (e.g. perl)
1184 PPM_UNINSTALL_SCRIPT
1186 Available in version 6.8502 and above.
1187 Name of the script that gets executed by the Perl Package Manager
1189 before the removal of a package.
1190 PREFIX
1192 This overrides all the default install locations. Man pages,
1193 libraries, scripts, etc... MakeMaker will try to make an educated
1194 guess about where to place things under the new PREFIX based on your
1195 Config defaults. Failing that, it will fall back to a structure
1196 which should be sensible for your platform.
1197 If you specify LIB or any INSTALL* variables they will not be
1199 affected by the PREFIX.
1200 PREREQ_FATAL
1202 Bool. If this parameter is true, failing to have the required modules
1203 (or the right versions thereof) will be fatal. "perl Makefile.PL"
1204 will "die" instead of simply informing the user of the missing
1205 dependencies.
1206 It is extremely rare to have to use "PREREQ_FATAL". Its use by module
1208 authors is strongly discouraged and should never be used lightly.
1209 For dependencies that are required in order to run "Makefile.PL", see
1211 "CONFIGURE_REQUIRES".
1212 Module installation tools have ways of resolving unmet dependencies
1214 but to do that they need a Makefile. Using "PREREQ_FATAL" breaks
1215 this. That's bad.
1216 Assuming you have good test coverage, your tests should fail with
1218 missing dependencies informing the user more strongly that something
1219 is wrong. You can write a t/00compile.t test which will simply check
1220 that your code compiles and stop "make test" prematurely if it
1221 doesn't. See "BAIL_OUT" in Test::More for more details.
1222 PREREQ_PM
1224 A hash of modules that are needed to run your module. The keys are
1225 the module names ie. Test::More, and the minimum version is the
1226 value. If the required version number is 0 any version will do. The
1227 versions given may be a Perl v-string (see version) or a range (see
1228 CPAN::Meta::Requirements).
1229 This will go into the "requires" field of your META.yml and the
1231 "runtime" of the "prereqs" field of your META.json.
1232 PREREQ_PM => {
1234 # Require Test::More at least 0.47
1235 "Test::More" => "0.47",
1236 # Require any version of Acme::Buffy
1238 "Acme::Buffy" => 0,
1239 }
1240 PREREQ_PRINT
1242 Bool. If this parameter is true, the prerequisites will be printed
1243 to stdout and MakeMaker will exit. The output format is an evalable
1244 hash ref.
1245 $PREREQ_PM = {
1247 'A::B' => Vers1,
1248 'C::D' => Vers2,
1249 ...
1250 };
1251 If a distribution defines a minimal required perl version, this is
1253 added to the output as an additional line of the form:
1254 $MIN_PERL_VERSION = '5.008001';
1256 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1258 hashref.
1259 PRINT_PREREQ
1261 RedHatism for "PREREQ_PRINT". The output format is different,
1262 though:
1263 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1265 A minimal required perl version, if present, will look like this:
1267 perl(perl)>=5.008001
1269 SITEPREFIX
1271 Like PERLPREFIX, but only for the site install locations.
1272 Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
1274 an explicit siteprefix in the Config. In those cases
1275 $Config{installprefix} will be used.
1276 Overridable by PREFIX
1278 SIGN
1280 Available in version 6.18 and above.
1281 When true, perform the generation and addition to the MANIFEST of the
1283 SIGNATURE file in the distdir during 'make distdir', via 'cpansign
1284 -s'.
1285 Note that you need to install the Module::Signature module to perform
1287 this operation.
1288 Defaults to false.
1290 SKIP
1292 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1293 Makefile. Caution! Do not use the SKIP attribute for the negligible
1294 speedup. It may seriously damage the resulting Makefile. Only use it
1295 if you really need it.
1296 TEST_REQUIRES
1298 Available in version 6.64 and above.
1299 A hash of modules that are needed to test your module but not run or
1301 build it.
1302 This will go into the "build_requires" field of your META.yml and the
1304 "test" of the "prereqs" field of your META.json.
1305 The format is the same as PREREQ_PM.
1307 TYPEMAPS
1309 Ref to array of typemap file names. Use this when the typemaps are
1310 in some directory other than the current directory or when they are
1311 not named typemap. The last typemap in the list takes precedence. A
1312 typemap in the current directory has highest precedence, even if it
1313 isn't listed in TYPEMAPS. The default system typemap has lowest
1314 precedence.
1315 USE_MM_LD_RUN_PATH
1317 boolean The Fedora perl MakeMaker distribution differs from the
1318 standard upstream release in that it disables use of the MakeMaker
1319 generated LD_RUN_PATH by default, UNLESS this attribute is specified
1320 , or the USE_MM_LD_RUN_PATH environment variable is set during the
1321 MakeMaker run.
1322 The upstream MakeMaker will set the ld(1) environment variable
1324 LD_RUN_PATH to the concatenation of every -L ld(1) option directory
1325 in which a -l ld(1) option library is found, which is used as the
1326 ld(1) -rpath option if none is specified. This means that, if your
1327 application builds shared libraries and your MakeMaker application
1328 links to them, that the absolute paths of the libraries in the build
1329 tree will be inserted into the RPATH header of all MakeMaker
1330 generated binaries, and that such binaries will be unable to link to
1331 these libraries if they do not still reside in the build tree
1332 directories (unlikely) or in the system library directories (/lib or
1333 /usr/lib), regardless of any LD_LIBRARY_PATH setting. So if you
1334 specified -L../mylib -lmylib , and
1335 your 'libmylib.so' gets installed into
1336 /some_directory_other_than_usr_lib,
1337 your MakeMaker application will be unable to link to it, even if
1338 LD_LIBRARY_PATH is set to include /some_directory_other_than_usr_lib,
1339 because RPATH overrides LD_LIBRARY_PATH.
1340 So for Fedora MakeMaker builds LD_RUN_PATH is NOT generated by
1342 default for every link. You can still use explicit -rpath ld options
1343 or the LD_RUN_PATH environment variable during the build to generate
1344 an RPATH for the binaries.
1345 You can set the USE_MM_LD_RUN_PATH attribute to 1 on the MakeMaker
1347 command line or in the WriteMakefile arguments to enable generation
1348 of LD_RUN_PATH for every link command.
1349 USE_MM_LD_RUN_PATH will default to 1 (LD_RUN_PATH will be used) IF
1351 the $USE_MM_LD_RUN_PATH environment variable is set during a
1352 MakeMaker run.
1353 VENDORPREFIX
1355 Like PERLPREFIX, but only for the vendor install locations.
1356 Defaults to $Config{vendorprefixexp}.
1358 Overridable by PREFIX
1360 VERBINST
1362 If true, make install will be verbose
1363 VERSION
1365 Your version number for distributing the package. This defaults to
1366 0.1.
1367 VERSION_FROM
1369 Instead of specifying the VERSION in the Makefile.PL you can let
1370 MakeMaker parse a file to determine the version number. The parsing
1371 routine requires that the file named by VERSION_FROM contains one
1372 single line to compute the version number. The first line in the file
1373 that contains something like a $VERSION assignment or "package Name
1374 VERSION" will be used. The following lines will be parsed o.k.:
1375 # Good
1377 package Foo::Bar 1.23; # 1.23
1378 $VERSION = '1.00'; # 1.00
1379 *VERSION = \'1.01'; # 1.01
1380 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
1381 $FOO::VERSION = '1.10'; # 1.10
1382 *FOO::VERSION = \'1.11'; # 1.11
1383 but these will fail:
1385 # Bad
1387 my $VERSION = '1.01';
1388 local $VERSION = '1.02';
1389 local $FOO::VERSION = '1.30';
1390 (Putting "my" or "local" on the preceding line will work o.k.)
1392 "Version strings" are incompatible and should not be used.
1394 # Bad
1396 $VERSION = 1.2.3;
1397 $VERSION = v1.2.3;
1398 version objects are fine. As of MakeMaker 6.35 version.pm will be
1400 automatically loaded, but you must declare the dependency on
1401 version.pm. For compatibility with older MakeMaker you should load
1402 on the same line as $VERSION is declared.
1403 # All on one line
1405 use version; our $VERSION = qv(1.2.3);
1406 The file named in VERSION_FROM is not added as a dependency to
1408 Makefile. This is not really correct, but it would be a major pain
1409 during development to have to rewrite the Makefile for any smallish
1410 change in that file. If you want to make sure that the Makefile
1411 contains the correct VERSION macro after any change of the file, you
1412 would have to do something like
1413 depend => { Makefile => '$(VERSION_FROM)' }
1415 See attribute "depend" below.
1417 VERSION_SYM
1419 A sanitized VERSION with . replaced by _. For places where . has
1420 special meaning (some filesystems, RCS labels, etc...)
1421 XS
1423 Hashref of .xs files. MakeMaker will default this. e.g.
1424 {'name_of_file.xs' => 'name_of_file.c'}
1426 The .c files will automatically be included in the list of files
1428 deleted by a make clean.
1429 XSBUILD
1431 Available in version 7.12 and above.
1432 Hashref with options controlling the operation of "XSMULTI":
1434 {
1436 xs => {
1437 all => {
1438 # options applying to all .xs files for this distribution
1439 },
1440 'lib/Class/Name/File' => { # specifically for this file
1441 DEFINE => '-Dfunktastic', # defines for only this file
1442 INC => "-I$funkyliblocation", # include flags for only this file
1443 # OBJECT => 'lib/Class/Name/File$(OBJ_EXT)', # default
1444 LDFROM => "lib/Class/Name/File\$(OBJ_EXT) $otherfile\$(OBJ_EXT)", # what's linked
1445 },
1446 },
1447 }
1448 Note "xs" is the file-extension. More possibilities may arise in the
1450 future. Note that object names are specified without their XS
1451 extension.
1452 "LDFROM" defaults to the same as "OBJECT". "OBJECT" defaults to, for
1454 "XSMULTI", just the XS filename with the extension replaced with the
1455 compiler-specific object-file extension.
1456 The distinction between "OBJECT" and "LDFROM": "OBJECT" is the make
1458 target, so make will try to build it. However, "LDFROM" is what will
1459 actually be linked together to make the shared object or static
1460 library (SO/SL), so if you override it, make sure it includes what
1461 you want to make the final SO/SL, almost certainly including the XS
1462 basename with "$(OBJ_EXT)" appended.
1463 XSMULTI
1465 Available in version 7.12 and above.
1466 When this is set to 1, multiple XS files may be placed under lib/
1468 next to their corresponding "*.pm" files (this is essential for
1469 compiling with the correct "VERSION" values). This feature should be
1470 considered experimental, and details of it may change.
1471 This feature was inspired by, and small portions of code copied from,
1473 ExtUtils::MakeMaker::BigHelper. Hopefully this feature will render
1474 that module mainly obsolete.
1475 XSOPT
1477 String of options to pass to xsubpp. This might include "-C++" or
1478 "-extern". Do not include typemaps here; the TYPEMAP parameter
1479 exists for that purpose.
1480 XSPROTOARG
1482 May be set to "-protoypes", "-noprototypes" or the empty string. The
1483 empty string is equivalent to the xsubpp default, or "-noprototypes".
1484 See the xsubpp documentation for details. MakeMaker defaults to the
1485 empty string.
1486 XS_VERSION
1488 Your version number for the .xs file of this package. This defaults
1489 to the value of the VERSION attribute.
1490 Additional lowercase attributes
1492 can be used to pass parameters to the methods which implement that part
1493 of the Makefile. Parameters are specified as a hash ref but are passed
1494 to the method as a hash.
1495 clean
1497 {FILES => "*.xyz foo"}
1498 depend
1500 {ANY_TARGET => ANY_DEPENDENCY, ...}
1501 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1503 dist
1505 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1506 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1507 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1508 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1510 needed to tell make the target file of the compression. Setting
1511 DIST_CP to ln can be useful, if you need to preserve the timestamps
1512 on your files. DIST_CP can take the values 'cp', which copies the
1513 file, 'ln', which links the file, and 'best' which copies symbolic
1514 links and links the rest. Default is 'best'.
1515 dynamic_lib
1517 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1518 linkext
1520 {LINKTYPE => 'static', 'dynamic' or ''}
1521 NB: Extensions that have nothing but *.pm files had to say
1523 {LINKTYPE => ''}
1525 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1527 can be deleted safely. MakeMaker recognizes when there's nothing to
1528 be linked.
1529 macro
1531 {ANY_MACRO => ANY_VALUE, ...}
1532 postamble
1534 Anything put here will be passed to MY::postamble() if you have one.
1535 realclean
1537 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1538 test
1540 Specify the targets for testing.
1541 {TESTS => 't/*.t'}
1543 "RECURSIVE_TEST_FILES" can be used to include all directories
1545 recursively under "t" that contain ".t" files. It will be ignored if
1546 you provide your own "TESTS" attribute, defaults to false.
1547 {RECURSIVE_TEST_FILES=>1}
1549 This is supported since 6.76
1551 tool_autosplit
1553 {MAXLEN => 8}
1554 Overriding MakeMaker Methods
1556 If you cannot achieve the desired Makefile behaviour by specifying
1557 attributes you may define private subroutines in the Makefile.PL. Each
1558 subroutine returns the text it wishes to have written to the Makefile.
1559 To override a section of the Makefile you can either say:
1560 sub MY::c_o { "new literal text" }
1562 or you can edit the default by saying something like:
1564 package MY; # so that "SUPER" works right
1566 sub c_o {
1567 my $inherited = shift->SUPER::c_o(@_);
1568 $inherited =~ s/old text/new text/;
1569 $inherited;
1570 }
1571 If you are running experiments with embedding perl as a library into
1573 other applications, you might find MakeMaker is not sufficient. You'd
1574 better have a look at ExtUtils::Embed which is a collection of
1575 utilities for embedding.
1576 If you still need a different solution, try to develop another
1578 subroutine that fits your needs and submit the diffs to
1579 "makemaker@perl.org"
1580 For a complete description of all MakeMaker methods see
1582 ExtUtils::MM_Unix.
1583 Here is a simple example of how to add a new target to the generated
1585 Makefile:
1586 sub MY::postamble {
1588 return <<'MAKE_FRAG';
1589 $(MYEXTLIB): sdbm/Makefile
1590 cd sdbm && $(MAKE) all
1591 MAKE_FRAG
1593 }
1594 The End Of Cargo Cult Programming
1596 WriteMakefile() now does some basic sanity checks on its parameters to
1597 protect against typos and malformatted values. This means some things
1598 which happened to work in the past will now throw warnings and possibly
1599 produce internal errors.
1600 Some of the most common mistakes:
1602 "MAN3PODS => ' '"
1604 This is commonly used to suppress the creation of man pages.
1605 MAN3PODS takes a hash ref not a string, but the above worked by
1606 accident in old versions of MakeMaker.
1607 The correct code is "MAN3PODS => { }".
1609 Hintsfile support
1611 MakeMaker.pm uses the architecture-specific information from Config.pm.
1612 In addition it evaluates architecture specific hints files in a
1613 "hints/" directory. The hints files are expected to be named like their
1614 counterparts in "PERL_SRC/hints", but with an ".pl" file name extension
1615 (eg. "next_3_2.pl"). They are simply "eval"ed by MakeMaker within the
1616 WriteMakefile() subroutine, and can be used to execute commands as well
1617 as to include special variables. The rules which hintsfile is chosen
1618 are the same as in Configure.
1619 The hintsfile is eval()ed immediately after the arguments given to
1621 WriteMakefile are stuffed into a hash reference $self but before this
1622 reference becomes blessed. So if you want to do the equivalent to
1623 override or create an attribute you would say something like
1624 $self->{LIBS} = ['-ldbm -lucb -lc'];
1626 Distribution Support
1628 For authors of extensions MakeMaker provides several Makefile targets.
1629 Most of the support comes from the ExtUtils::Manifest module, where
1630 additional documentation can be found.
1631 make distcheck
1633 reports which files are below the build directory but not in the
1634 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck()
1635 for details)
1636 make skipcheck
1638 reports which files are skipped due to the entries in the
1639 "MANIFEST.SKIP" file (See ExtUtils::Manifest::skipcheck() for
1640 details)
1641 make distclean
1643 does a realclean first and then the distcheck. Note that this is
1644 not needed to build a new distribution as long as you are sure that
1645 the MANIFEST file is ok.
1646 make veryclean
1648 does a realclean first and then removes backup files such as "*~",
1649 "*.bak", "*.old" and "*.orig"
1650 make manifest
1652 rewrites the MANIFEST file, adding all remaining files found (See
1653 ExtUtils::Manifest::mkmanifest() for details)
1654 make distdir
1656 Copies all the files that are in the MANIFEST file to a newly
1657 created directory with the name "$(DISTNAME)-$(VERSION)". If that
1658 directory exists, it will be removed first.
1659 Additionally, it will create META.yml and META.json module meta-
1661 data file in the distdir and add this to the distdir's MANIFEST.
1662 You can shut this behavior off with the NO_META flag.
1663 make disttest
1665 Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1666 make test in that directory.
1667 make tardist
1669 First does a distdir. Then a command $(PREOP) which defaults to a
1670 null command, followed by $(TO_UNIX), which defaults to a null
1671 command under UNIX, and will convert files in distribution
1672 directory to UNIX format otherwise. Next it runs "tar" on that
1673 directory into a tarfile and deletes the directory. Finishes with a
1674 command $(POSTOP) which defaults to a null command.
1675 make dist
1677 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1678 make uutardist
1680 Runs a tardist first and uuencodes the tarfile.
1681 make shdist
1683 First does a distdir. Then a command $(PREOP) which defaults to a
1684 null command. Next it runs "shar" on that directory into a sharfile
1685 and deletes the intermediate directory again. Finishes with a
1686 command $(POSTOP) which defaults to a null command. Note: For
1687 shdist to work properly a "shar" program that can handle
1688 directories is mandatory.
1689 make zipdist
1691 First does a distdir. Then a command $(PREOP) which defaults to a
1692 null command. Runs "$(ZIP) $(ZIPFLAGS)" on that directory into a
1693 zipfile. Then deletes that directory. Finishes with a command
1694 $(POSTOP) which defaults to a null command.
1695 make ci
1697 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1698 Customization of the dist targets can be done by specifying a hash
1700 reference to the dist attribute of the WriteMakefile call. The
1701 following parameters are recognized:
1702 CI ('ci -u')
1704 COMPRESS ('gzip --best')
1705 POSTOP ('@ :')
1706 PREOP ('@ :')
1707 TO_UNIX (depends on the system)
1708 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1709 SHAR ('shar')
1710 SUFFIX ('.gz')
1711 TAR ('tar')
1712 TARFLAGS ('cvf')
1713 ZIP ('zip')
1714 ZIPFLAGS ('-r')
1715 An example:
1717 WriteMakefile(
1719 ...other options...
1720 dist => {
1721 COMPRESS => "bzip2",
1722 SUFFIX => ".bz2"
1723 }
1724 );
1725 Module Meta-Data (META and MYMETA)
1727 Long plaguing users of MakeMaker based modules has been the problem of
1728 getting basic information about the module out of the sources without
1729 running the Makefile.PL and doing a bunch of messy heuristics on the
1730 resulting Makefile. Over the years, it has become standard to keep
1731 this information in one or more CPAN Meta files distributed with each
1732 distribution.
1733 The original format of CPAN Meta files was YAML and the corresponding
1735 file was called META.yml. In 2010, version 2 of the CPAN::Meta::Spec
1736 was released, which mandates JSON format for the metadata in order to
1737 overcome certain compatibility issues between YAML serializers and to
1738 avoid breaking older clients unable to handle a new version of the
1739 spec. The CPAN::Meta library is now standard for accessing old and
1740 new-style Meta files.
1741 If CPAN::Meta is installed, MakeMaker will automatically generate
1743 META.json and META.yml files for you and add them to your MANIFEST as
1744 part of the 'distdir' target (and thus the 'dist' target). This is
1745 intended to seamlessly and rapidly populate CPAN with module meta-data.
1746 If you wish to shut this feature off, set the "NO_META"
1747 "WriteMakefile()" flag to true.
1748 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers
1750 agreed to use the CPAN Meta format to communicate post-configuration
1751 requirements between toolchain components. These files, MYMETA.json
1752 and MYMETA.yml, are generated when Makefile.PL generates a Makefile (if
1753 CPAN::Meta is installed). Clients like CPAN or CPANPLUS will read
1754 these files to see what prerequisites must be fulfilled before building
1755 or testing the distribution. If you wish to shut this feature off, set
1756 the "NO_MYMETA" "WriteMakeFile()" flag to true.
1757 Disabling an extension
1759 If some events detected in Makefile.PL imply that there is no way to
1760 create the Module, but this is a normal state of things, then you can
1761 create a Makefile which does nothing, but succeeds on all the "usual"
1762 build targets. To do so, use
1763 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1765 WriteEmptyMakefile();
1766 instead of WriteMakefile().
1768 This may be useful if other modules expect this module to be built OK,
1770 as opposed to work OK (say, this system-dependent module builds in a
1771 subdirectory of some other distribution, or is listed as a dependency
1772 in a CPAN::Bundle, but the functionality is supported by different
1773 means on the current architecture).
1774 Other Handy Functions
1776 prompt
1777 my $value = prompt($message);
1778 my $value = prompt($message, $default);
1779 The "prompt()" function provides an easy way to request user input
1781 used to write a makefile. It displays the $message as a prompt for
1782 input. If a $default is provided it will be used as a default.
1783 The function returns the $value selected by the user.
1784 If "prompt()" detects that it is not running interactively and
1786 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1787 variable is set to true, the $default will be used without
1788 prompting. This prevents automated processes from blocking on user
1789 input.
1790 If no $default is provided an empty string will be used instead.
1792 os_unsupported
1794 os_unsupported();
1795 os_unsupported if $^O eq 'MSWin32';
1796 The "os_unsupported()" function provides a way to correctly exit
1798 your "Makefile.PL" before calling "WriteMakefile". It is
1799 essentially a "die" with the message "OS unsupported".
1800 This is supported since 7.26
1802 Supported versions of Perl
1804 Please note that while this module works on Perl 5.6, it is no longer
1805 being routinely tested on 5.6 - the earliest Perl version being
1806 routinely tested, and expressly supported, is 5.8.1. However, patches
1807 to repair any breakage on 5.6 are still being accepted.
1808
1810 PERL_MM_OPT
1811 Command line options used by "MakeMaker->new()", and thus by
1812 "WriteMakefile()". The string is split as the shell would, and the
1813 result is processed before any actual command line arguments are
1814 processed.
1815 PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1817 PERL_MM_USE_DEFAULT
1819 If set to a true value then MakeMaker's prompt function will always
1820 return the default without waiting for user input.
1821 PERL_CORE
1823 Same as the PERL_CORE parameter. The parameter overrides this.
1824
1826 Module::Build is a pure-Perl alternative to MakeMaker which does not
1827 rely on make or any other external utility. It is easier to extend to
1828 suit your needs.
1829 Module::Install is a wrapper around MakeMaker which adds features not
1831 normally available.
1832 ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1834 setup your distribution.
1835 CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1837 File::ShareDir::Install makes it easy to install static, sometimes also
1839 referred to as 'shared' files. File::ShareDir helps accessing the
1840 shared files after installation.
1841 Dist::Zilla makes it easy for the module author to create MakeMaker-
1843 based distributions with lots of bells and whistles.
1844
1846 Andy Dougherty "doughera@lafayette.edu", Andreas König
1847 "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org". VMS support by
1848 Charles Bailey "bailey@newman.upenn.edu". OS/2 support by Ilya
1849 Zakharevich "ilya@math.ohio-state.edu".
1850 Currently maintained by Michael G Schwern "schwern@pobox.com"
1852 Send patches and ideas to "makemaker@perl.org".
1854 Send bug reports via http://rt.cpan.org/. Please send your generated
1856 Makefile along with your report.
1857 For more up-to-date information, see
1859 <https://metacpan.org/release/ExtUtils-MakeMaker>.
1860 Repository available at
1862 <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1863
1865 This program is free software; you can redistribute it and/or modify it
1866 under the same terms as Perl itself.
1867 See <http://www.perl.com/perl/misc/Artistic.html>
1869perl v5.30.0 2019-09-11 ExtUtils::MakeMaker(3)