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 PL files are normally run after pm_to_blib and include INST_LIB and
1092 INST_ARCH in their @INC, so the just built modules can be accessed...
1093 unless the PL file is making a module (or anything else in PM) in
1094 which case it is run before pm_to_blib and does not include INST_LIB
1095 and INST_ARCH in its @INC. This apparently odd behavior is there for
1096 backwards compatibility (and it's somewhat DWIM). The argument
1097 passed to the .PL is set up as a target to build in the Makefile. In
1098 other sections such as "postamble" you can specify a dependency on
1099 the filename/argument that the .PL is supposed (or will have, now
1100 that that is is a dependency) to generate. Note the file to be
1101 generated will still be generated and the .PL will still run even
1102 without an explicit dependency created by you, since the "all" target
1103 still depends on running all eligible to run.PL files.
1104 PM
1106 Hashref of .pm files and *.pl files to be installed. e.g.
1107 {'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
1109 By default this will include *.pm and *.pl and the files found in the
1111 PMLIBDIRS directories. Defining PM in the Makefile.PL will override
1112 PMLIBDIRS.
1113 PMLIBDIRS
1115 Ref to array of subdirectories containing library files. Defaults to
1116 [ 'lib', $(BASEEXT) ]. The directories will be scanned and any files
1117 they contain will be installed in the corresponding location in the
1118 library. A libscan() method can be used to alter the behaviour.
1119 Defining PM in the Makefile.PL will override PMLIBDIRS.
1120 (Where BASEEXT is the last component of NAME.)
1122 PM_FILTER
1124 A filter program, in the traditional Unix sense (input from stdin,
1125 output to stdout) that is passed on each .pm file during the build
1126 (in the pm_to_blib() phase). It is empty by default, meaning no
1127 filtering is done. You could use:
1128 PM_FILTER => 'perl -ne "print unless /^\\#/"',
1130 to remove all the leading comments on the fly during the build. In
1132 order to be as portable as possible, please consider using a Perl
1133 one-liner rather than Unix (or other) utilities, as above. The # is
1134 escaped for the Makefile, since what is going to be generated will
1135 then be:
1136 PM_FILTER = perl -ne "print unless /^\#/"
1138 Without the \ before the #, we'd have the start of a Makefile
1140 comment, and the macro would be incorrectly defined.
1141 You will almost certainly be better off using the "PL_FILES" system,
1143 instead. See above, or the ExtUtils::MakeMaker::FAQ entry.
1144 POLLUTE
1146 Release 5.005 grandfathered old global symbol names by providing
1147 preprocessor macros for extension source compatibility. As of
1148 release 5.6, these preprocessor definitions are not available by
1149 default. The POLLUTE flag specifies that the old names should still
1150 be defined:
1151 perl Makefile.PL POLLUTE=1
1153 Please inform the module author if this is necessary to successfully
1155 install a module under 5.6 or later.
1156 PPM_INSTALL_EXEC
1158 Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
1159 perl)
1160 PPM_INSTALL_SCRIPT
1162 Name of the script that gets executed by the Perl Package Manager
1163 after the installation of a package.
1164 PPM_UNINSTALL_EXEC
1166 Available in version 6.8502 and above.
1167 Name of the executable used to run "PPM_UNINSTALL_SCRIPT" below.
1169 (e.g. perl)
1170 PPM_UNINSTALL_SCRIPT
1172 Available in version 6.8502 and above.
1173 Name of the script that gets executed by the Perl Package Manager
1175 before the removal of a package.
1176 PREFIX
1178 This overrides all the default install locations. Man pages,
1179 libraries, scripts, etc... MakeMaker will try to make an educated
1180 guess about where to place things under the new PREFIX based on your
1181 Config defaults. Failing that, it will fall back to a structure
1182 which should be sensible for your platform.
1183 If you specify LIB or any INSTALL* variables they will not be
1185 affected by the PREFIX.
1186 PREREQ_FATAL
1188 Bool. If this parameter is true, failing to have the required modules
1189 (or the right versions thereof) will be fatal. "perl Makefile.PL"
1190 will "die" instead of simply informing the user of the missing
1191 dependencies.
1192 It is extremely rare to have to use "PREREQ_FATAL". Its use by module
1194 authors is strongly discouraged and should never be used lightly.
1195 For dependencies that are required in order to run "Makefile.PL", see
1197 "CONFIGURE_REQUIRES".
1198 Module installation tools have ways of resolving unmet dependencies
1200 but to do that they need a Makefile. Using "PREREQ_FATAL" breaks
1201 this. That's bad.
1202 Assuming you have good test coverage, your tests should fail with
1204 missing dependencies informing the user more strongly that something
1205 is wrong. You can write a t/00compile.t test which will simply check
1206 that your code compiles and stop "make test" prematurely if it
1207 doesn't. See "BAIL_OUT" in Test::More for more details.
1208 PREREQ_PM
1210 A hash of modules that are needed to run your module. The keys are
1211 the module names ie. Test::More, and the minimum version is the
1212 value. If the required version number is 0 any version will do. The
1213 versions given may be a Perl v-string (see version) or a range (see
1214 CPAN::Meta::Requirements).
1215 This will go into the "requires" field of your META.yml and the
1217 "runtime" of the "prereqs" field of your META.json.
1218 PREREQ_PM => {
1220 # Require Test::More at least 0.47
1221 "Test::More" => "0.47",
1222 # Require any version of Acme::Buffy
1224 "Acme::Buffy" => 0,
1225 }
1226 PREREQ_PRINT
1228 Bool. If this parameter is true, the prerequisites will be printed
1229 to stdout and MakeMaker will exit. The output format is an evalable
1230 hash ref.
1231 $PREREQ_PM = {
1233 'A::B' => Vers1,
1234 'C::D' => Vers2,
1235 ...
1236 };
1237 If a distribution defines a minimal required perl version, this is
1239 added to the output as an additional line of the form:
1240 $MIN_PERL_VERSION = '5.008001';
1242 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1244 hashref.
1245 PRINT_PREREQ
1247 RedHatism for "PREREQ_PRINT". The output format is different,
1248 though:
1249 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1251 A minimal required perl version, if present, will look like this:
1253 perl(perl)>=5.008001
1255 SITEPREFIX
1257 Like PERLPREFIX, but only for the site install locations.
1258 Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
1260 an explicit siteprefix in the Config. In those cases
1261 $Config{installprefix} will be used.
1262 Overridable by PREFIX
1264 SIGN
1266 Available in version 6.18 and above.
1267 When true, perform the generation and addition to the MANIFEST of the
1269 SIGNATURE file in the distdir during 'make distdir', via 'cpansign
1270 -s'.
1271 Note that you need to install the Module::Signature module to perform
1273 this operation.
1274 Defaults to false.
1276 SKIP
1278 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1279 Makefile. Caution! Do not use the SKIP attribute for the negligible
1280 speedup. It may seriously damage the resulting Makefile. Only use it
1281 if you really need it.
1282 TEST_REQUIRES
1284 Available in version 6.64 and above.
1285 A hash of modules that are needed to test your module but not run or
1287 build it.
1288 This will go into the "build_requires" field of your META.yml and the
1290 "test" of the "prereqs" field of your META.json.
1291 The format is the same as PREREQ_PM.
1293 TYPEMAPS
1295 Ref to array of typemap file names. Use this when the typemaps are
1296 in some directory other than the current directory or when they are
1297 not named typemap. The last typemap in the list takes precedence. A
1298 typemap in the current directory has highest precedence, even if it
1299 isn't listed in TYPEMAPS. The default system typemap has lowest
1300 precedence.
1301 USE_MM_LD_RUN_PATH
1303 boolean The Fedora perl MakeMaker distribution differs from the
1304 standard upstream release in that it disables use of the MakeMaker
1305 generated LD_RUN_PATH by default, UNLESS this attribute is specified
1306 , or the USE_MM_LD_RUN_PATH environment variable is set during the
1307 MakeMaker run.
1308 The upstream MakeMaker will set the ld(1) environment variable
1310 LD_RUN_PATH to the concatenation of every -L ld(1) option directory
1311 in which a -l ld(1) option library is found, which is used as the
1312 ld(1) -rpath option if none is specified. This means that, if your
1313 application builds shared libraries and your MakeMaker application
1314 links to them, that the absolute paths of the libraries in the build
1315 tree will be inserted into the RPATH header of all MakeMaker
1316 generated binaries, and that such binaries will be unable to link to
1317 these libraries if they do not still reside in the build tree
1318 directories (unlikely) or in the system library directories (/lib or
1319 /usr/lib), regardless of any LD_LIBRARY_PATH setting. So if you
1320 specified -L../mylib -lmylib , and
1321 your 'libmylib.so' gets installed into
1322 /some_directory_other_than_usr_lib,
1323 your MakeMaker application will be unable to link to it, even if
1324 LD_LIBRARY_PATH is set to include /some_directory_other_than_usr_lib,
1325 because RPATH overrides LD_LIBRARY_PATH.
1326 So for Fedora MakeMaker builds LD_RUN_PATH is NOT generated by
1328 default for every link. You can still use explicit -rpath ld options
1329 or the LD_RUN_PATH environment variable during the build to generate
1330 an RPATH for the binaries.
1331 You can set the USE_MM_LD_RUN_PATH attribute to 1 on the MakeMaker
1333 command line or in the WriteMakefile arguments to enable generation
1334 of LD_RUN_PATH for every link command.
1335 USE_MM_LD_RUN_PATH will default to 1 (LD_RUN_PATH will be used) IF
1337 the $USE_MM_LD_RUN_PATH environment variable is set during a
1338 MakeMaker run.
1339 VENDORPREFIX
1341 Like PERLPREFIX, but only for the vendor install locations.
1342 Defaults to $Config{vendorprefixexp}.
1344 Overridable by PREFIX
1346 VERBINST
1348 If true, make install will be verbose
1349 VERSION
1351 Your version number for distributing the package. This defaults to
1352 0.1.
1353 VERSION_FROM
1355 Instead of specifying the VERSION in the Makefile.PL you can let
1356 MakeMaker parse a file to determine the version number. The parsing
1357 routine requires that the file named by VERSION_FROM contains one
1358 single line to compute the version number. The first line in the file
1359 that contains something like a $VERSION assignment or "package Name
1360 VERSION" will be used. The following lines will be parsed o.k.:
1361 # Good
1363 package Foo::Bar 1.23; # 1.23
1364 $VERSION = '1.00'; # 1.00
1365 *VERSION = \'1.01'; # 1.01
1366 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
1367 $FOO::VERSION = '1.10'; # 1.10
1368 *FOO::VERSION = \'1.11'; # 1.11
1369 but these will fail:
1371 # Bad
1373 my $VERSION = '1.01';
1374 local $VERSION = '1.02';
1375 local $FOO::VERSION = '1.30';
1376 (Putting "my" or "local" on the preceding line will work o.k.)
1378 "Version strings" are incompatible and should not be used.
1380 # Bad
1382 $VERSION = 1.2.3;
1383 $VERSION = v1.2.3;
1384 version objects are fine. As of MakeMaker 6.35 version.pm will be
1386 automatically loaded, but you must declare the dependency on
1387 version.pm. For compatibility with older MakeMaker you should load
1388 on the same line as $VERSION is declared.
1389 # All on one line
1391 use version; our $VERSION = qv(1.2.3);
1392 The file named in VERSION_FROM is not added as a dependency to
1394 Makefile. This is not really correct, but it would be a major pain
1395 during development to have to rewrite the Makefile for any smallish
1396 change in that file. If you want to make sure that the Makefile
1397 contains the correct VERSION macro after any change of the file, you
1398 would have to do something like
1399 depend => { Makefile => '$(VERSION_FROM)' }
1401 See attribute "depend" below.
1403 VERSION_SYM
1405 A sanitized VERSION with . replaced by _. For places where . has
1406 special meaning (some filesystems, RCS labels, etc...)
1407 XS
1409 Hashref of .xs files. MakeMaker will default this. e.g.
1410 {'name_of_file.xs' => 'name_of_file.c'}
1412 The .c files will automatically be included in the list of files
1414 deleted by a make clean.
1415 XSBUILD
1417 Available in version 7.12 and above.
1418 Hashref with options controlling the operation of "XSMULTI":
1420 {
1422 xs => {
1423 all => {
1424 # options applying to all .xs files for this distribution
1425 },
1426 'lib/Class/Name/File' => { # specifically for this file
1427 DEFINE => '-Dfunktastic', # defines for only this file
1428 INC => "-I$funkyliblocation", # include flags for only this file
1429 # OBJECT => 'lib/Class/Name/File$(OBJ_EXT)', # default
1430 LDFROM => "lib/Class/Name/File\$(OBJ_EXT) $otherfile\$(OBJ_EXT)", # what's linked
1431 },
1432 },
1433 }
1434 Note "xs" is the file-extension. More possibilities may arise in the
1436 future. Note that object names are specified without their XS
1437 extension.
1438 "LDFROM" defaults to the same as "OBJECT". "OBJECT" defaults to, for
1440 "XSMULTI", just the XS filename with the extension replaced with the
1441 compiler-specific object-file extension.
1442 The distinction between "OBJECT" and "LDFROM": "OBJECT" is the make
1444 target, so make will try to build it. However, "LDFROM" is what will
1445 actually be linked together to make the shared object or static
1446 library (SO/SL), so if you override it, make sure it includes what
1447 you want to make the final SO/SL, almost certainly including the XS
1448 basename with "$(OBJ_EXT)" appended.
1449 XSMULTI
1451 Available in version 7.12 and above.
1452 When this is set to 1, multiple XS files may be placed under lib/
1454 next to their corresponding "*.pm" files (this is essential for
1455 compiling with the correct "VERSION" values). This feature should be
1456 considered experimental, and details of it may change.
1457 This feature was inspired by, and small portions of code copied from,
1459 ExtUtils::MakeMaker::BigHelper. Hopefully this feature will render
1460 that module mainly obsolete.
1461 XSOPT
1463 String of options to pass to xsubpp. This might include "-C++" or
1464 "-extern". Do not include typemaps here; the TYPEMAP parameter
1465 exists for that purpose.
1466 XSPROTOARG
1468 May be set to "-protoypes", "-noprototypes" or the empty string. The
1469 empty string is equivalent to the xsubpp default, or "-noprototypes".
1470 See the xsubpp documentation for details. MakeMaker defaults to the
1471 empty string.
1472 XS_VERSION
1474 Your version number for the .xs file of this package. This defaults
1475 to the value of the VERSION attribute.
1476 Additional lowercase attributes
1478 can be used to pass parameters to the methods which implement that part
1479 of the Makefile. Parameters are specified as a hash ref but are passed
1480 to the method as a hash.
1481 clean
1483 {FILES => "*.xyz foo"}
1484 depend
1486 {ANY_TARGET => ANY_DEPENDENCY, ...}
1487 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1489 dist
1491 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1492 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1493 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1494 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1496 needed to tell make the target file of the compression. Setting
1497 DIST_CP to ln can be useful, if you need to preserve the timestamps
1498 on your files. DIST_CP can take the values 'cp', which copies the
1499 file, 'ln', which links the file, and 'best' which copies symbolic
1500 links and links the rest. Default is 'best'.
1501 dynamic_lib
1503 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1504 linkext
1506 {LINKTYPE => 'static', 'dynamic' or ''}
1507 NB: Extensions that have nothing but *.pm files had to say
1509 {LINKTYPE => ''}
1511 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1513 can be deleted safely. MakeMaker recognizes when there's nothing to
1514 be linked.
1515 macro
1517 {ANY_MACRO => ANY_VALUE, ...}
1518 postamble
1520 Anything put here will be passed to MY::postamble() if you have one.
1521 realclean
1523 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1524 test
1526 Specify the targets for testing.
1527 {TESTS => 't/*.t'}
1529 "RECURSIVE_TEST_FILES" can be used to include all directories
1531 recursively under "t" that contain ".t" files. It will be ignored if
1532 you provide your own "TESTS" attribute, defaults to false.
1533 {RECURSIVE_TEST_FILES=>1}
1535 This is supported since 6.76
1537 tool_autosplit
1539 {MAXLEN => 8}
1540 Overriding MakeMaker Methods
1542 If you cannot achieve the desired Makefile behaviour by specifying
1543 attributes you may define private subroutines in the Makefile.PL. Each
1544 subroutine returns the text it wishes to have written to the Makefile.
1545 To override a section of the Makefile you can either say:
1546 sub MY::c_o { "new literal text" }
1548 or you can edit the default by saying something like:
1550 package MY; # so that "SUPER" works right
1552 sub c_o {
1553 my $inherited = shift->SUPER::c_o(@_);
1554 $inherited =~ s/old text/new text/;
1555 $inherited;
1556 }
1557 If you are running experiments with embedding perl as a library into
1559 other applications, you might find MakeMaker is not sufficient. You'd
1560 better have a look at ExtUtils::Embed which is a collection of
1561 utilities for embedding.
1562 If you still need a different solution, try to develop another
1564 subroutine that fits your needs and submit the diffs to
1565 "makemaker@perl.org"
1566 For a complete description of all MakeMaker methods see
1568 ExtUtils::MM_Unix.
1569 Here is a simple example of how to add a new target to the generated
1571 Makefile:
1572 sub MY::postamble {
1574 return <<'MAKE_FRAG';
1575 $(MYEXTLIB): sdbm/Makefile
1576 cd sdbm && $(MAKE) all
1577 MAKE_FRAG
1579 }
1580 The End Of Cargo Cult Programming
1582 WriteMakefile() now does some basic sanity checks on its parameters to
1583 protect against typos and malformatted values. This means some things
1584 which happened to work in the past will now throw warnings and possibly
1585 produce internal errors.
1586 Some of the most common mistakes:
1588 "MAN3PODS => ' '"
1590 This is commonly used to suppress the creation of man pages.
1591 MAN3PODS takes a hash ref not a string, but the above worked by
1592 accident in old versions of MakeMaker.
1593 The correct code is "MAN3PODS => { }".
1595 Hintsfile support
1597 MakeMaker.pm uses the architecture-specific information from Config.pm.
1598 In addition it evaluates architecture specific hints files in a
1599 "hints/" directory. The hints files are expected to be named like their
1600 counterparts in "PERL_SRC/hints", but with an ".pl" file name extension
1601 (eg. "next_3_2.pl"). They are simply "eval"ed by MakeMaker within the
1602 WriteMakefile() subroutine, and can be used to execute commands as well
1603 as to include special variables. The rules which hintsfile is chosen
1604 are the same as in Configure.
1605 The hintsfile is eval()ed immediately after the arguments given to
1607 WriteMakefile are stuffed into a hash reference $self but before this
1608 reference becomes blessed. So if you want to do the equivalent to
1609 override or create an attribute you would say something like
1610 $self->{LIBS} = ['-ldbm -lucb -lc'];
1612 Distribution Support
1614 For authors of extensions MakeMaker provides several Makefile targets.
1615 Most of the support comes from the ExtUtils::Manifest module, where
1616 additional documentation can be found.
1617 make distcheck
1619 reports which files are below the build directory but not in the
1620 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck()
1621 for details)
1622 make skipcheck
1624 reports which files are skipped due to the entries in the
1625 "MANIFEST.SKIP" file (See ExtUtils::Manifest::skipcheck() for
1626 details)
1627 make distclean
1629 does a realclean first and then the distcheck. Note that this is
1630 not needed to build a new distribution as long as you are sure that
1631 the MANIFEST file is ok.
1632 make veryclean
1634 does a realclean first and then removes backup files such as "*~",
1635 "*.bak", "*.old" and "*.orig"
1636 make manifest
1638 rewrites the MANIFEST file, adding all remaining files found (See
1639 ExtUtils::Manifest::mkmanifest() for details)
1640 make distdir
1642 Copies all the files that are in the MANIFEST file to a newly
1643 created directory with the name "$(DISTNAME)-$(VERSION)". If that
1644 directory exists, it will be removed first.
1645 Additionally, it will create META.yml and META.json module meta-
1647 data file in the distdir and add this to the distdir's MANIFEST.
1648 You can shut this behavior off with the NO_META flag.
1649 make disttest
1651 Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1652 make test in that directory.
1653 make tardist
1655 First does a distdir. Then a command $(PREOP) which defaults to a
1656 null command, followed by $(TO_UNIX), which defaults to a null
1657 command under UNIX, and will convert files in distribution
1658 directory to UNIX format otherwise. Next it runs "tar" on that
1659 directory into a tarfile and deletes the directory. Finishes with a
1660 command $(POSTOP) which defaults to a null command.
1661 make dist
1663 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1664 make uutardist
1666 Runs a tardist first and uuencodes the tarfile.
1667 make shdist
1669 First does a distdir. Then a command $(PREOP) which defaults to a
1670 null command. Next it runs "shar" on that directory into a sharfile
1671 and deletes the intermediate directory again. Finishes with a
1672 command $(POSTOP) which defaults to a null command. Note: For
1673 shdist to work properly a "shar" program that can handle
1674 directories is mandatory.
1675 make zipdist
1677 First does a distdir. Then a command $(PREOP) which defaults to a
1678 null command. Runs "$(ZIP) $(ZIPFLAGS)" on that directory into a
1679 zipfile. Then deletes that directory. Finishes with a command
1680 $(POSTOP) which defaults to a null command.
1681 make ci
1683 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1684 Customization of the dist targets can be done by specifying a hash
1686 reference to the dist attribute of the WriteMakefile call. The
1687 following parameters are recognized:
1688 CI ('ci -u')
1690 COMPRESS ('gzip --best')
1691 POSTOP ('@ :')
1692 PREOP ('@ :')
1693 TO_UNIX (depends on the system)
1694 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1695 SHAR ('shar')
1696 SUFFIX ('.gz')
1697 TAR ('tar')
1698 TARFLAGS ('cvf')
1699 ZIP ('zip')
1700 ZIPFLAGS ('-r')
1701 An example:
1703 WriteMakefile(
1705 ...other options...
1706 dist => {
1707 COMPRESS => "bzip2",
1708 SUFFIX => ".bz2"
1709 }
1710 );
1711 Module Meta-Data (META and MYMETA)
1713 Long plaguing users of MakeMaker based modules has been the problem of
1714 getting basic information about the module out of the sources without
1715 running the Makefile.PL and doing a bunch of messy heuristics on the
1716 resulting Makefile. Over the years, it has become standard to keep
1717 this information in one or more CPAN Meta files distributed with each
1718 distribution.
1719 The original format of CPAN Meta files was YAML and the corresponding
1721 file was called META.yml. In 2010, version 2 of the CPAN::Meta::Spec
1722 was released, which mandates JSON format for the metadata in order to
1723 overcome certain compatibility issues between YAML serializers and to
1724 avoid breaking older clients unable to handle a new version of the
1725 spec. The CPAN::Meta library is now standard for accessing old and
1726 new-style Meta files.
1727 If CPAN::Meta is installed, MakeMaker will automatically generate
1729 META.json and META.yml files for you and add them to your MANIFEST as
1730 part of the 'distdir' target (and thus the 'dist' target). This is
1731 intended to seamlessly and rapidly populate CPAN with module meta-data.
1732 If you wish to shut this feature off, set the "NO_META"
1733 "WriteMakefile()" flag to true.
1734 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers
1736 agreed to use the CPAN Meta format to communicate post-configuration
1737 requirements between toolchain components. These files, MYMETA.json
1738 and MYMETA.yml, are generated when Makefile.PL generates a Makefile (if
1739 CPAN::Meta is installed). Clients like CPAN or CPANPLUS will read
1740 these files to see what prerequisites must be fulfilled before building
1741 or testing the distribution. If you wish to shut this feature off, set
1742 the "NO_MYMETA" "WriteMakeFile()" flag to true.
1743 Disabling an extension
1745 If some events detected in Makefile.PL imply that there is no way to
1746 create the Module, but this is a normal state of things, then you can
1747 create a Makefile which does nothing, but succeeds on all the "usual"
1748 build targets. To do so, use
1749 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1751 WriteEmptyMakefile();
1752 instead of WriteMakefile().
1754 This may be useful if other modules expect this module to be built OK,
1756 as opposed to work OK (say, this system-dependent module builds in a
1757 subdirectory of some other distribution, or is listed as a dependency
1758 in a CPAN::Bundle, but the functionality is supported by different
1759 means on the current architecture).
1760 Other Handy Functions
1762 prompt
1763 my $value = prompt($message);
1764 my $value = prompt($message, $default);
1765 The "prompt()" function provides an easy way to request user input
1767 used to write a makefile. It displays the $message as a prompt for
1768 input. If a $default is provided it will be used as a default.
1769 The function returns the $value selected by the user.
1770 If "prompt()" detects that it is not running interactively and
1772 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1773 variable is set to true, the $default will be used without
1774 prompting. This prevents automated processes from blocking on user
1775 input.
1776 If no $default is provided an empty string will be used instead.
1778 os_unsupported
1780 os_unsupported();
1781 os_unsupported if $^O eq 'MSWin32';
1782 The "os_unsupported()" function provides a way to correctly exit
1784 your "Makefile.PL" before calling "WriteMakefile". It is
1785 essentially a "die" with the message "OS unsupported".
1786 This is supported since 7.26
1788 Supported versions of Perl
1790 Please note that while this module works on Perl 5.6, it is no longer
1791 being routinely tested on 5.6 - the earliest Perl version being
1792 routinely tested, and expressly supported, is 5.8.1. However, patches
1793 to repair any breakage on 5.6 are still being accepted.
1794
1796 PERL_MM_OPT
1797 Command line options used by "MakeMaker->new()", and thus by
1798 "WriteMakefile()". The string is split as the shell would, and the
1799 result is processed before any actual command line arguments are
1800 processed.
1801 PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1803 PERL_MM_USE_DEFAULT
1805 If set to a true value then MakeMaker's prompt function will always
1806 return the default without waiting for user input.
1807 PERL_CORE
1809 Same as the PERL_CORE parameter. The parameter overrides this.
1810
1812 Module::Build is a pure-Perl alternative to MakeMaker which does not
1813 rely on make or any other external utility. It is easier to extend to
1814 suit your needs.
1815 Module::Install is a wrapper around MakeMaker which adds features not
1817 normally available.
1818 ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1820 setup your distribution.
1821 CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1823 File::ShareDir::Install makes it easy to install static, sometimes also
1825 referred to as 'shared' files. File::ShareDir helps accessing the
1826 shared files after installation.
1827 Dist::Zilla makes it easy for the module author to create MakeMaker-
1829 based distributions with lots of bells and whistles.
1830
1832 Andy Dougherty "doughera@lafayette.edu", Andreas König
1833 "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org". VMS support by
1834 Charles Bailey "bailey@newman.upenn.edu". OS/2 support by Ilya
1835 Zakharevich "ilya@math.ohio-state.edu".
1836 Currently maintained by Michael G Schwern "schwern@pobox.com"
1838 Send patches and ideas to "makemaker@perl.org".
1840 Send bug reports via http://rt.cpan.org/. Please send your generated
1842 Makefile along with your report.
1843 For more up-to-date information, see
1845 <https://metacpan.org/release/ExtUtils-MakeMaker>.
1846 Repository available at
1848 <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1849
1851 This program is free software; you can redistribute it and/or modify it
1852 under the same terms as Perl itself.
1853 See <http://www.perl.com/perl/misc/Artistic.html>
1855perl v5.28.0 2018-07-14 ExtUtils::MakeMaker(3)