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 See ExtUtils::MakeMaker::FAQ for details of the design and usage.
48 How To Write A Makefile.PL
50 See ExtUtils::MakeMaker::Tutorial.
51 The long answer is the rest of the manpage :-)
53 Default Makefile Behaviour
55 The generated Makefile enables the user of the extension to invoke
56 perl Makefile.PL # optionally "perl Makefile.PL verbose"
58 make
59 make test # optionally set TEST_VERBOSE=1
60 make install # See below
61 The Makefile to be produced may be altered by adding arguments of the
63 form "KEY=VALUE". E.g.
64 perl Makefile.PL INSTALL_BASE=~
66 Other interesting targets in the generated Makefile are
68 make config # to check if the Makefile is up-to-date
70 make clean # delete local temp files (Makefile gets renamed)
71 make realclean # delete derived files (including ./blib)
72 make ci # check in all the files in the MANIFEST file
73 make dist # see below the Distribution Support section
74 make test
76 MakeMaker checks for the existence of a file named test.pl in the
77 current directory, and if it exists it executes the script with the
78 proper set of perl "-I" options.
79 MakeMaker also checks for any files matching glob("t/*.t"). It will
81 execute all matching files in alphabetical order via the Test::Harness
82 module with the "-I" switches set correctly.
83 You can also organize your tests within subdirectories in the t/
85 directory. To do so, use the test directive in your Makefile.PL. For
86 example, if you had tests in:
87 t/foo
89 t/foo/bar
90 You could tell make to run tests in both of those directories with the
92 following directives:
93 test => {TESTS => 't/*/*.t t/*/*/*.t'}
95 test => {TESTS => 't/foo/*.t t/foo/bar/*.t'}
96 The first will run all test files in all first-level subdirectories and
98 all subdirectories they contain. The second will run tests in only the
99 t/foo and t/foo/bar.
100 If you'd like to see the raw output of your tests, set the
102 "TEST_VERBOSE" variable to true.
103 make test TEST_VERBOSE=1
105 If you want to run particular test files, set the "TEST_FILES"
107 variable. It is possible to use globbing with this mechanism.
108 make test TEST_FILES='t/foobar.t t/dagobah*.t'
110 Windows users who are using "nmake" should note that due to a bug in
112 "nmake", when specifying "TEST_FILES" you must use back-slashes instead
113 of forward-slashes.
114 nmake test TEST_FILES='t\foobar.t t\dagobah*.t'
116 make testdb
118 A useful variation of the above is the target "testdb". It runs the
119 test under the Perl debugger (see perldebug). If the file test.pl
120 exists in the current directory, it is used for the test.
121 If you want to debug some other testfile, set the "TEST_FILE" variable
123 thusly:
124 make testdb TEST_FILE=t/mytest.t
126 By default the debugger is called using "-d" option to perl. If you
128 want to specify some other option, set the "TESTDB_SW" variable:
129 make testdb TESTDB_SW=-Dx
131 make install
133 make alone puts all relevant files into directories that are named by
134 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
135 INST_MAN3DIR. All these default to something below ./blib if you are
136 not building below the perl source directory. If you are building below
137 the perl source, INST_LIB and INST_ARCHLIB default to ../../lib, and
138 INST_SCRIPT is not defined.
139 The install target of the generated Makefile copies the files found
141 below each of the INST_* directories to their INSTALL* counterparts.
142 Which counterparts are chosen depends on the setting of INSTALLDIRS
143 according to the following table:
144 INSTALLDIRS set to
146 perl site vendor
147 PERLPREFIX SITEPREFIX VENDORPREFIX
149 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
150 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
151 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
152 INST_SCRIPT INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
153 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
154 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
155 The INSTALL... macros in turn default to their %Config
157 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
158 You can check the values of these variables on your system with
160 perl '-V:install.*'
162 And to check the sequence in which the library directories are searched
164 by perl, run
165 perl -le 'print join $/, @INC'
167 Sometimes older versions of the module you're installing live in other
169 directories in @INC. Because Perl loads the first version of a module
170 it finds, not the newest, you might accidentally get one of these older
171 versions even after installing a brand new version. To delete all
172 other versions of the module you're installing (not simply older ones)
173 set the "UNINST" variable.
174 make install UNINST=1
176 INSTALL_BASE
178 INSTALL_BASE can be passed into Makefile.PL to change where your module
179 will be installed. INSTALL_BASE is more like what everyone else calls
180 "prefix" than PREFIX is.
181 To have everything installed in your home directory, do the following.
183 # Unix users, INSTALL_BASE=~ works fine
185 perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
186 Like PREFIX, it sets several INSTALL* attributes at once. Unlike
188 PREFIX it is easy to predict where the module will end up. The
189 installation pattern looks like this:
190 INSTALLARCHLIB INSTALL_BASE/lib/perl5/$Config{archname}
192 INSTALLPRIVLIB INSTALL_BASE/lib/perl5
193 INSTALLBIN INSTALL_BASE/bin
194 INSTALLSCRIPT INSTALL_BASE/bin
195 INSTALLMAN1DIR INSTALL_BASE/man/man1
196 INSTALLMAN3DIR INSTALL_BASE/man/man3
197 INSTALL_BASE in MakeMaker and "--install_base" in Module::Build (as of
199 0.28) install to the same location. If you want MakeMaker and
200 Module::Build to install to the same location simply set INSTALL_BASE
201 and "--install_base" to the same location.
202 INSTALL_BASE was added in 6.31.
204 PREFIX and LIB attribute
206 PREFIX and LIB can be used to set several INSTALL* attributes in one
207 go. Here's an example for installing into your home directory.
208 # Unix users, PREFIX=~ works fine
210 perl Makefile.PL PREFIX=/path/to/your/home/dir
211 This will install all files in the module under your home directory,
213 with man pages and libraries going into an appropriate place (usually
214 ~/man and ~/lib). How the exact location is determined is complicated
215 and depends on how your Perl was configured. INSTALL_BASE works more
216 like what other build systems call "prefix" than PREFIX and we
217 recommend you use that instead.
218 Another way to specify many INSTALL directories with a single parameter
220 is LIB.
221 perl Makefile.PL LIB=~/lib
223 This will install the module's architecture-independent files into
225 ~/lib, the architecture-dependent files into ~/lib/$archname.
226 Note, that in both cases the tilde expansion is done by MakeMaker, not
228 by perl by default, nor by make.
229 Conflicts between parameters LIB, PREFIX and the various INSTALL*
231 arguments are resolved so that:
232 • setting LIB overrides any setting of INSTALLPRIVLIB,
234 INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not
235 affected by PREFIX);
236 • without LIB, setting PREFIX replaces the initial $Config{prefix}
238 part of those INSTALL* arguments, even if the latter are explicitly
239 set (but are set to still start with $Config{prefix}).
240 If the user has superuser privileges, and is not working on AFS or
242 relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
243 INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
244 the best:
245 perl Makefile.PL;
247 make;
248 make test
249 make install
250 make install by default writes some documentation of what has been done
252 into the file "$(INSTALLARCHLIB)/perllocal.pod". This feature can be
253 bypassed by calling make pure_install.
254 AFS users
256 will have to specify the installation directories as these most
257 probably have changed since perl itself has been installed. They will
258 have to do this by calling
259 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
261 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
262 make
263 Be careful to repeat this procedure every time you recompile an
265 extension, unless you are sure the AFS installation directories are
266 still valid.
267 Static Linking of a new Perl Binary
269 An extension that is built with the above steps is ready to use on
270 systems supporting dynamic loading. On systems that do not support
271 dynamic loading, any newly created extension has to be linked together
272 with the available resources. MakeMaker supports the linking process by
273 creating appropriate targets in the Makefile whenever an extension is
274 built. You can invoke the corresponding section of the makefile with
275 make perl
277 That produces a new perl binary in the current directory with all
279 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP, and
280 PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on UNIX,
281 this is called Makefile.aperl (may be system dependent). If you want to
282 force the creation of a new perl, it is recommended that you delete
283 this Makefile.aperl, so the directories are searched through for
284 linkable libraries again.
285 The binary can be installed into the directory where perl normally
287 resides on your machine with
288 make inst_perl
290 To produce a perl binary with a different name than "perl", either say
292 perl Makefile.PL MAP_TARGET=myperl
294 make myperl
295 make inst_perl
296 or say
298 perl Makefile.PL
300 make myperl MAP_TARGET=myperl
301 make inst_perl MAP_TARGET=myperl
302 In any case you will be prompted with the correct invocation of the
304 "inst_perl" target that installs the new binary into INSTALLBIN.
305 make inst_perl by default writes some documentation of what has been
307 done into the file "$(INSTALLARCHLIB)/perllocal.pod". This can be
308 bypassed by calling make pure_inst_perl.
309 Warning: the inst_perl: target will most probably overwrite your
311 existing perl binary. Use with care!
312 Sometimes you might want to build a statically linked perl although
314 your system supports dynamic loading. In this case you may explicitly
315 set the linktype with the invocation of the Makefile.PL or make:
316 perl Makefile.PL LINKTYPE=static # recommended
318 or
320 make LINKTYPE=static # works on most systems
322 Determination of Perl Library and Installation Locations
324 MakeMaker needs to know, or to guess, where certain things are located.
325 Especially INST_LIB and INST_ARCHLIB (where to put the files during the
326 make(1) run), PERL_LIB and PERL_ARCHLIB (where to read existing modules
327 from), and PERL_INC (header files and "libperl*.*").
328 Extensions may be built either using the contents of the perl source
330 directory tree or from the installed perl library. The recommended way
331 is to build extensions after you have run 'make install' on perl
332 itself. You can do that in any directory on your hard disk that is not
333 below the perl source tree. The support for extensions below the ext
334 directory of the perl distribution is only good for the standard
335 extensions that come with perl.
336 If an extension is being built below the "ext/" directory of the perl
338 source then MakeMaker will set PERL_SRC automatically (e.g., "../..").
339 If PERL_SRC is defined and the extension is recognized as a standard
340 extension, then other variables default to the following:
341 PERL_INC = PERL_SRC
343 PERL_LIB = PERL_SRC/lib
344 PERL_ARCHLIB = PERL_SRC/lib
345 INST_LIB = PERL_LIB
346 INST_ARCHLIB = PERL_ARCHLIB
347 If an extension is being built away from the perl source then MakeMaker
349 will leave PERL_SRC undefined and default to using the installed copy
350 of the perl library. The other variables default to the following:
351 PERL_INC = $archlibexp/CORE
353 PERL_LIB = $privlibexp
354 PERL_ARCHLIB = $archlibexp
355 INST_LIB = ./blib/lib
356 INST_ARCHLIB = ./blib/arch
357 If perl has not yet been installed then PERL_SRC can be defined on the
359 command line as shown in the previous section.
360 Which architecture dependent directory?
362 If you don't want to keep the defaults for the INSTALL* macros,
363 MakeMaker helps you to minimize the typing needed: the usual
364 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined by
365 Configure at perl compilation time. MakeMaker supports the user who
366 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
367 then MakeMaker defaults the latter to be the same subdirectory of
368 INSTALLPRIVLIB as Configure decided for the counterparts in %Config,
369 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
370 for INSTALLSITELIB and INSTALLSITEARCH.
371 MakeMaker gives you much more freedom than needed to configure internal
373 variables and get different results. It is worth mentioning that
374 make(1) also lets you configure most of the variables that are used in
375 the Makefile. But in the majority of situations this will not be
376 necessary, and should only be done if the author of a package
377 recommends it (or you know what you're doing).
378 Using Attributes and Parameters
380 The following attributes may be specified as arguments to
381 WriteMakefile() or as NAME=VALUE pairs on the command line. Attributes
382 that became available with later versions of MakeMaker are indicated.
383 In order to maintain portability of attributes with older versions of
385 MakeMaker you may want to use App::EUMM::Upgrade with your
386 "Makefile.PL".
387 ABSTRACT
389 One line description of the module. Will be included in PPD file.
390 ABSTRACT_FROM
392 Name of the file that contains the package description. MakeMaker
393 looks for a line in the POD matching /^($package\s-\s)(.*)/. This is
394 typically the first line in the "=head1 NAME" section. $2 becomes the
395 abstract.
396 AUTHOR
398 Array of strings containing name (and email address) of package
399 author(s). Is used in CPAN Meta files (META.yml or META.json) and
400 PPD (Perl Package Description) files for PPM (Perl Package Manager).
401 BINARY_LOCATION
403 Used when creating PPD files for binary packages. It can be set to a
404 full or relative path or URL to the binary archive for a particular
405 architecture. For example:
406 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
408 builds a PPD package that references a binary of the "Agent" package,
410 located in the "x86" directory relative to the PPD itself.
411 BUILD_REQUIRES
413 Available in version 6.55_03 and above.
414 A hash of modules that are needed to build your module but not run
416 it.
417 This will go into the "build_requires" field of your META.yml and the
419 "build" of the "prereqs" field of your META.json.
420 Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
422 specified.
423 The format is the same as PREREQ_PM.
425 C Ref to array of *.c file names. Initialised from a directory scan and
427 the values portion of the XS attribute hash. This is not currently
428 used by MakeMaker but may be handy in Makefile.PLs.
429 CCFLAGS
431 String that will be included in the compiler call command line
432 between the arguments INC and OPTIMIZE.
433 CONFIG
435 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
436 config.sh. MakeMaker will add to CONFIG the following values anyway:
437 ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
438 lib_ext obj_ext ranlib sitelibexp sitearchexp so
439 CONFIGURE
441 CODE reference. The subroutine should return a hash reference. The
442 hash may contain further attributes, e.g. {LIBS => ...}, that have to
443 be determined by some evaluation method.
444 CONFIGURE_REQUIRES
446 Available in version 6.52 and above.
447 A hash of modules that are required to run Makefile.PL itself, but
449 not to run your distribution.
450 This will go into the "configure_requires" field of your META.yml and
452 the "configure" of the "prereqs" field of your META.json.
453 Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
455 specified.
456 The format is the same as PREREQ_PM.
458 DEFINE
460 Something like "-DHAVE_UNISTD_H"
461 DESTDIR
463 This is the root directory into which the code will be installed. It
464 prepends itself to the normal prefix. For example, if your code
465 would normally go into /usr/local/lib/perl you could set
466 DESTDIR=~/tmp/ and installation would go into
467 ~/tmp/usr/local/lib/perl.
468 This is primarily of use for people who repackage Perl modules.
470 NOTE: Due to the nature of make, it is important that you put the
472 trailing slash on your DESTDIR. ~/tmp/ not ~/tmp.
473 DIR
475 Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
476 in ext/SDBM_File
477 DISTNAME
479 A safe filename for the package.
480 Defaults to NAME below but with :: replaced with -.
482 For example, Foo::Bar becomes Foo-Bar.
484 DISTVNAME
486 Your name for distributing the package with the version number
487 included. This is used by 'make dist' to name the resulting archive
488 file.
489 Defaults to DISTNAME-VERSION.
491 For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
493 On some OS's where . has special meaning VERSION_SYM may be used in
495 place of VERSION.
496 DLEXT
498 Specifies the extension of the module's loadable object. For example:
499 DLEXT => 'unusual_ext', # Default value is $Config{so}
501 NOTE: When using this option to alter the extension of a module's
503 loadable object, it is also necessary that the module's pm file
504 specifies the same change:
505 local $DynaLoader::dl_dlext = 'unusual_ext';
507 DL_FUNCS
509 Hashref of symbol names for routines to be made available as
510 universal symbols. Each key/value pair consists of the package name
511 and an array of routine names in that package. Used only under AIX,
512 OS/2, VMS and Win32 at present. The routine names supplied will be
513 expanded in the same way as XSUB names are expanded by the XS()
514 macro. Defaults to
515 {"$(NAME)" => ["boot_$(NAME)" ] }
517 e.g.
519 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
521 "NetconfigPtr" => [ 'DESTROY'] }
522 Please see the ExtUtils::Mksymlists documentation for more
524 information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
525 DL_VARS
527 Array of symbol names for variables to be made available as universal
528 symbols. Used only under AIX, OS/2, VMS and Win32 at present.
529 Defaults to []. (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
530 EXCLUDE_EXT
532 Array of extension names to exclude when doing a static build. This
533 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
534 details. (e.g. [ qw( Socket POSIX ) ] )
535 This attribute may be most useful when specified as a string on the
537 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
538 EXE_FILES
540 Ref to array of executable files. The files will be copied to the
541 INST_SCRIPT directory. Make realclean will delete them from there
542 again.
543 If your executables start with something like #!perl or
545 #!/usr/bin/perl MakeMaker will change this to the path of the perl
546 'Makefile.PL' was invoked with so the programs will be sure to run
547 properly even if perl is not in /usr/bin/perl.
548 FIRST_MAKEFILE
550 The name of the Makefile to be produced. This is used for the second
551 Makefile that will be produced for the MAP_TARGET.
552 Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
554 (Note: we couldn't use MAKEFILE because dmake uses this for something
556 else).
557 FULLPERL
559 Perl binary able to run this extension, load XS modules, etc...
560 FULLPERLRUN
562 Like PERLRUN, except it uses FULLPERL.
563 FULLPERLRUNINST
565 Like PERLRUNINST, except it uses FULLPERL.
566 FUNCLIST
568 This provides an alternate means to specify function names to be
569 exported from the extension. Its value is a reference to an array of
570 function names to be exported by the extension. These names are
571 passed through unaltered to the linker options file.
572 H Ref to array of *.h file names. Similar to C.
574 IMPORTS
576 This attribute is used to specify names to be imported into the
577 extension. Takes a hash ref.
578 It is only used on OS/2 and Win32.
580 INC
582 Include file dirs eg: "-I/usr/5include -I/path/to/inc"
583 INCLUDE_EXT
585 Array of extension names to be included when doing a static build.
586 MakeMaker will normally build with all of the installed extensions
587 when doing a static build, and that is usually the desired behavior.
588 If INCLUDE_EXT is present then MakeMaker will build only with those
589 extensions which are explicitly mentioned. (e.g. [ qw( Socket POSIX
590 ) ])
591 It is not necessary to mention DynaLoader or the current extension
593 when filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is
594 empty then only DynaLoader and the current extension will be included
595 in the build.
596 This attribute may be most useful when specified as a string on the
598 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket
599 Devel::Peek'
600 INSTALLARCHLIB
602 Used by 'make install', which copies files from INST_ARCHLIB to this
603 directory if INSTALLDIRS is set to perl.
604 INSTALLBIN
606 Directory to install binary files (e.g. tkperl) into if
607 INSTALLDIRS=perl.
608 INSTALLDIRS
610 Determines which of the sets of installation directories to choose:
611 perl, site or vendor. Defaults to site.
612 INSTALLMAN1DIR
614 INSTALLMAN3DIR
615 These directories get the man pages at 'make install' time if
616 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
617 If set to 'none', no man pages will be installed.
619 INSTALLPRIVLIB
621 Used by 'make install', which copies files from INST_LIB to this
622 directory if INSTALLDIRS is set to perl.
623 Defaults to $Config{installprivlib}.
625 INSTALLSCRIPT
627 Available in version 6.30_02 and above.
628 Used by 'make install' which copies files from INST_SCRIPT to this
630 directory if INSTALLDIRS=perl.
631 INSTALLSITEARCH
633 Used by 'make install', which copies files from INST_ARCHLIB to this
634 directory if INSTALLDIRS is set to site (default).
635 INSTALLSITEBIN
637 Used by 'make install', which copies files from INST_BIN to this
638 directory if INSTALLDIRS is set to site (default).
639 INSTALLSITELIB
641 Used by 'make install', which copies files from INST_LIB to this
642 directory if INSTALLDIRS is set to site (default).
643 INSTALLSITEMAN1DIR
645 INSTALLSITEMAN3DIR
646 These directories get the man pages at 'make install' time if
647 INSTALLDIRS=site (default). Defaults to
648 $(SITEPREFIX)/man/man$(MAN*EXT).
649 If set to 'none', no man pages will be installed.
651 INSTALLSITESCRIPT
653 Used by 'make install' which copies files from INST_SCRIPT to this
654 directory if INSTALLDIRS is set to site (default).
655 INSTALLVENDORARCH
657 Used by 'make install', which copies files from INST_ARCHLIB to this
658 directory if INSTALLDIRS is set to vendor. Note that if you do not
659 set this, the value of INSTALLVENDORLIB will be used, which is
660 probably not what you want.
661 INSTALLVENDORBIN
663 Used by 'make install', which copies files from INST_BIN to this
664 directory if INSTALLDIRS is set to vendor.
665 INSTALLVENDORLIB
667 Used by 'make install', which copies files from INST_LIB to this
668 directory if INSTALLDIRS is set to vendor.
669 INSTALLVENDORMAN1DIR
671 INSTALLVENDORMAN3DIR
672 These directories get the man pages at 'make install' time if
673 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
674 If set to 'none', no man pages will be installed.
676 INSTALLVENDORSCRIPT
678 Available in version 6.30_02 and above.
679 Used by 'make install' which copies files from INST_SCRIPT to this
681 directory if INSTALLDIRS is set to vendor.
682 INST_ARCHLIB
684 Same as INST_LIB for architecture dependent files.
685 INST_BIN
687 Directory to put real binary files during 'make'. These will be
688 copied to INSTALLBIN during 'make install'
689 INST_LIB
691 Directory where we put library files of this extension while building
692 it.
693 INST_MAN1DIR
695 Directory to hold the man pages at 'make' time
696 INST_MAN3DIR
698 Directory to hold the man pages at 'make' time
699 INST_SCRIPT
701 Directory where executable files should be installed during 'make'.
702 Defaults to "./blib/script", just to have a dummy location during
703 testing. make install will copy the files in INST_SCRIPT to
704 INSTALLSCRIPT.
705 LD
707 Program to be used to link libraries for dynamic loading.
708 Defaults to $Config{ld}.
710 LDDLFLAGS
712 Any special flags that might need to be passed to ld to create a
713 shared library suitable for dynamic loading. It is up to the
714 makefile to use it. (See "lddlflags" in Config)
715 Defaults to $Config{lddlflags}.
717 LDFROM
719 Defaults to "$(OBJECT)" and is used in the ld command to specify what
720 files to link/load from (also see dynamic_lib below for how to
721 specify ld flags)
722 LIB
724 LIB should only be set at "perl Makefile.PL" time but is allowed as a
725 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
726 and INSTALLSITELIB to that value regardless any explicit setting of
727 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
728 are set to the corresponding architecture subdirectory.
729 LIBPERL_A
731 The filename of the perllibrary that will be used together with this
732 extension. Defaults to libperl.a.
733 LIBS
735 An anonymous array of alternative library specifications to be
736 searched for (in order) until at least one library is found. E.g.
737 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
739 Mind, that any element of the array contains a complete set of
741 arguments for the ld command. So do not specify
742 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
744 See ODBM_File/Makefile.PL for an example, where an array is needed.
746 If you specify a scalar as in
747 'LIBS' => "-ltcl -ltk -lX11"
749 MakeMaker will turn it into an array with one element.
751 LICENSE
753 Available in version 6.31 and above.
754 The licensing terms of your distribution. Generally it's "perl_5"
756 for the same license as Perl itself.
757 See CPAN::Meta::Spec for the list of options.
759 Defaults to "unknown".
761 LINKTYPE
763 'static' or 'dynamic' (default unless usedl=undef in config.sh).
764 Should only be used to force static linking (also see linkext below).
765 MAGICXS
767 Available in version 6.8305 and above.
768 When this is set to 1, "OBJECT" will be automagically derived from
770 "O_FILES".
771 MAKE
773 Available in version 6.30_01 and above.
774 Variant of make you intend to run the generated Makefile with. This
776 parameter lets Makefile.PL know what make quirks to account for when
777 generating the Makefile.
778 MakeMaker also honors the MAKE environment variable. This parameter
780 takes precedence.
781 Currently the only significant values are 'dmake' and 'nmake' for
783 Windows users, instructing MakeMaker to generate a Makefile in the
784 flavour of DMake ("Dennis Vadura's Make") or Microsoft NMake
785 respectively.
786 Defaults to $Config{make}, which may go looking for a Make program in
788 your environment.
789 How are you supposed to know what flavour of Make a Makefile has been
791 generated for if you didn't specify a value explicitly? Search the
792 generated Makefile for the definition of the MAKE variable, which is
793 used to recursively invoke the Make utility. That will tell you what
794 Make you're supposed to invoke the Makefile with.
795 MAKEAPERL
797 Boolean which tells MakeMaker that it should include the rules to
798 make a perl. This is handled automatically as a switch by MakeMaker.
799 The user normally does not need it.
800 MAKEFILE_OLD
802 When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
803 backed up at this location.
804 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
806 MAN1PODS
808 Hashref of pod-containing files. MakeMaker will default this to all
809 EXE_FILES files that include POD directives. The files listed here
810 will be converted to man pages and installed as was requested at
811 Configure time.
812 This hash should map POD files (or scripts containing POD) to the man
814 file names under the "blib/man1/" directory, as in the following
815 example:
816 MAN1PODS => {
818 'doc/command.pod' => 'blib/man1/command.1',
819 'scripts/script.pl' => 'blib/man1/script.1',
820 }
821 MAN3PODS
823 Hashref that assigns to *.pm and *.pod files the files into which the
824 manpages are to be written. MakeMaker parses all *.pod and *.pm files
825 for POD directives. Files that contain POD will be the default keys
826 of the MAN3PODS hashref. These will then be converted to man pages
827 during "make" and will be installed during "make install".
828 Example similar to MAN1PODS.
830 MAP_TARGET
832 If it is intended that a new perl binary be produced, this variable
833 may hold a name for that binary. Defaults to perl
834 META_ADD
836 META_MERGE
837 Available in version 6.46 and above.
838 A hashref of items to add to the CPAN Meta file (META.yml or
840 META.json).
841 They differ in how they behave if they have the same key as the
843 default metadata. META_ADD will override the default value with its
844 own. META_MERGE will merge its value with the default.
845 Unless you want to override the defaults, prefer META_MERGE so as to
847 get the advantage of any future defaults.
848 Where prereqs are concerned, if META_MERGE is used, prerequisites are
850 merged with their counterpart "WriteMakefile()" argument (PREREQ_PM
851 is merged into {prereqs}{runtime}{requires}, BUILD_REQUIRES into
852 "{prereqs}{build}{requires}", CONFIGURE_REQUIRES into
853 "{prereqs}{configure}{requires}", and TEST_REQUIRES into
854 "{prereqs}{test}{requires})". When prereqs are specified with
855 META_ADD, the only prerequisites added to the file come from the
856 metadata, not "WriteMakefile()" arguments.
857 Note that these configuration options are only used for generating
859 META.yml and META.json -- they are NOT used for MYMETA.yml and
860 MYMETA.json. Therefore data in these fields should NOT be used for
861 dynamic (user-side) configuration.
862 By default CPAN Meta specification 1.4 is used. In order to use CPAN
864 Meta specification 2.0, indicate with "meta-spec" the version you
865 want to use.
866 META_MERGE => {
868 "meta-spec" => { version => 2 },
870 resources => {
872 repository => {
874 type => 'git',
875 url => 'git://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker.git',
876 web => 'https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker',
877 },
878 },
880 },
882 MIN_PERL_VERSION
884 Available in version 6.48 and above.
885 The minimum required version of Perl for this distribution.
887 Either the 5.006001 or the 5.6.1 format is acceptable.
889 MYEXTLIB
891 If the extension links to a library that it builds, set this to the
892 name of the library (see SDBM_File)
893 NAME
895 The package representing the distribution. For example, "Test::More"
896 or "ExtUtils::MakeMaker". It will be used to derive information about
897 the distribution such as the "DISTNAME", installation locations
898 within the Perl library and where XS files will be looked for by
899 default (see "XS").
900 "NAME" must be a valid Perl package name and it must have an
902 associated ".pm" file. For example, "Foo::Bar" is a valid "NAME" and
903 there must exist Foo/Bar.pm. Any XS code should be in Bar.xs unless
904 stated otherwise.
905 Your distribution must have a "NAME".
907 NEEDS_LINKING
909 MakeMaker will figure out if an extension contains linkable code
910 anywhere down the directory tree, and will set this variable
911 accordingly, but you can speed it up a very little bit if you define
912 this boolean variable yourself.
913 NOECHO
915 Command so make does not print the literal commands it's running.
916 By setting it to an empty string you can generate a Makefile that
918 prints all commands. Mainly used in debugging MakeMaker itself.
919 Defaults to "@".
921 NORECURS
923 Boolean. Attribute to inhibit descending into subdirectories.
924 NO_META
926 When true, suppresses the generation and addition to the MANIFEST of
927 the META.yml and META.json module meta-data files during 'make
928 distdir'.
929 Defaults to false.
931 NO_MYMETA
933 Available in version 6.57_02 and above.
934 When true, suppresses the generation of MYMETA.yml and MYMETA.json
936 module meta-data files during 'perl Makefile.PL'.
937 Defaults to false.
939 NO_PACKLIST
941 Available in version 6.7501 and above.
942 When true, suppresses the writing of "packlist" files for installs.
944 Defaults to false.
946 NO_PERLLOCAL
948 Available in version 6.7501 and above.
949 When true, suppresses the appending of installations to "perllocal".
951 Defaults to false.
953 NO_VC
955 In general, any generated Makefile checks for the current version of
956 MakeMaker and the version the Makefile was built under. If NO_VC is
957 set, the version check is neglected. Do not write this into your
958 Makefile.PL, use it interactively instead.
959 OBJECT
961 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be
962 a long string or an array containing all object files, e.g.
963 "tkpBind.o tkpButton.o tkpCanvas.o" or ["tkpBind.o", "tkpButton.o",
964 "tkpCanvas.o"]
965 (Where BASEEXT is the last component of NAME, and OBJ_EXT is
967 $Config{obj_ext}.)
968 OPTIMIZE
970 Defaults to "-O". Set it to "-g" to turn debugging on. The flag is
971 passed to subdirectory makes.
972 PERL
974 Perl binary for tasks that can be done by miniperl. If it contains
975 spaces or other shell metacharacters, it needs to be quoted in a way
976 that protects them, since this value is intended to be inserted in a
977 shell command line in the Makefile. E.g.:
978 # Perl executable lives in "C:/Program Files/Perl/bin"
980 # Normally you don't need to set this yourself!
981 $ perl Makefile.PL PERL='"C:/Program Files/Perl/bin/perl.exe" -w'
982 PERL_CORE
984 Set only when MakeMaker is building the extensions of the Perl core
985 distribution.
986 PERLMAINCC
988 The call to the program that is able to compile perlmain.c. Defaults
989 to $(CC).
990 PERL_ARCHLIB
992 Same as for PERL_LIB, but for architecture dependent files.
993 Used only when MakeMaker is building the extensions of the Perl core
995 distribution (because normally $(PERL_ARCHLIB) is automatically in
996 @INC, and adding it would get in the way of PERL5LIB).
997 PERL_LIB
999 Directory containing the Perl library to use.
1000 Used only when MakeMaker is building the extensions of the Perl core
1002 distribution (because normally $(PERL_LIB) is automatically in @INC,
1003 and adding it would get in the way of PERL5LIB).
1004 PERL_MALLOC_OK
1006 defaults to 0. Should be set to TRUE if the extension can work with
1007 the memory allocation routines substituted by the Perl malloc()
1008 subsystem. This should be applicable to most extensions with
1009 exceptions of those
1010 • with bugs in memory allocations which are caught by Perl's
1012 malloc();
1013 • which interact with the memory allocator in other ways than via
1015 malloc(), realloc(), free(), calloc(), sbrk() and brk();
1016 • which rely on special alignment which is not provided by Perl's
1018 malloc().
1019 NOTE. Neglecting to set this flag in any one of the loaded extension
1021 nullifies many advantages of Perl's malloc(), such as better usage of
1022 system resources, error detection, memory usage reporting, catchable
1023 failure of memory allocations, etc.
1024 PERLPREFIX
1026 Directory under which core modules are to be installed.
1027 Defaults to $Config{installprefixexp}, falling back to
1029 $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1030 $Config{installprefixexp} not exist.
1031 Overridden by PREFIX.
1033 PERLRUN
1035 Use this instead of $(PERL) when you wish to run perl. It will set
1036 up extra necessary flags for you.
1037 PERLRUNINST
1039 Use this instead of $(PERL) when you wish to run perl to work with
1040 modules. It will add things like -I$(INST_ARCH) and other necessary
1041 flags so perl can see the modules you're about to install.
1042 PERL_SRC
1044 Directory containing the Perl source code (use of this should be
1045 avoided, it may be undefined)
1046 PERM_DIR
1048 Available in version 6.51_01 and above.
1049 Desired permission for directories. Defaults to 755.
1051 PERM_RW
1053 Desired permission for read/writable files. Defaults to 644.
1054 PERM_RWX
1056 Desired permission for executable files. Defaults to 755.
1057 PL_FILES
1059 MakeMaker can run programs to generate files for you at build time.
1060 By default any file named *.PL (except Makefile.PL and Build.PL) in
1061 the top level directory will be assumed to be a Perl program and run
1062 passing its own basename in as an argument. This basename is
1063 actually a build target, and there is an intention, but not a
1064 requirement, that the *.PL file make the file passed to to as an
1065 argument. For example...
1066 perl foo.PL foo
1068 This behavior can be overridden by supplying your own set of files to
1070 search. PL_FILES accepts a hash ref, the key being the file to run
1071 and the value is passed in as the first argument when the PL file is
1072 run.
1073 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
1075 PL_FILES => {'foo.PL' => 'foo.c'}
1077 Would run bin/foobar.PL like this:
1079 perl bin/foobar.PL bin/foobar
1081 If multiple files from one program are desired an array ref can be
1083 used.
1084 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
1086 In this case the program will be run multiple times using each target
1088 file.
1089 perl bin/foobar.PL bin/foobar1
1091 perl bin/foobar.PL bin/foobar2
1092 If an output file depends on extra input files beside the script
1094 itself, a hash ref can be used in version 7.36 and above:
1095 PL_FILES => { 'foo.PL' => {
1097 'foo.out' => 'foo.in',
1098 'bar.out' => [qw(bar1.in bar2.in)],
1099 }
1100 In this case the extra input files will be passed to the program
1102 after the target file:
1103 perl foo.PL foo.out foo.in
1105 perl foo.PL bar.out bar1.in bar2.in
1106 PL files are normally run after pm_to_blib and include INST_LIB and
1108 INST_ARCH in their @INC, so the just built modules can be accessed...
1109 unless the PL file is making a module (or anything else in PM) in
1110 which case it is run before pm_to_blib and does not include INST_LIB
1111 and INST_ARCH in its @INC. This apparently odd behavior is there for
1112 backwards compatibility (and it's somewhat DWIM). The argument
1113 passed to the .PL is set up as a target to build in the Makefile. In
1114 other sections such as "postamble" you can specify a dependency on
1115 the filename/argument that the .PL is supposed (or will have, now
1116 that that is is a dependency) to generate. Note the file to be
1117 generated will still be generated and the .PL will still run even
1118 without an explicit dependency created by you, since the "all" target
1119 still depends on running all eligible to run.PL files.
1120 PM
1122 Hashref of .pm files and *.pl files to be installed. e.g.
1123 {'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
1125 By default this will include *.pm and *.pl and the files found in the
1127 PMLIBDIRS directories. Defining PM in the Makefile.PL will override
1128 PMLIBDIRS.
1129 PMLIBDIRS
1131 Ref to array of subdirectories containing library files. Defaults to
1132 [ 'lib', $(BASEEXT) ]. The directories will be scanned and any files
1133 they contain will be installed in the corresponding location in the
1134 library. A libscan() method can be used to alter the behaviour.
1135 Defining PM in the Makefile.PL will override PMLIBDIRS.
1136 (Where BASEEXT is the last component of NAME.)
1138 PM_FILTER
1140 A filter program, in the traditional Unix sense (input from stdin,
1141 output to stdout) that is passed on each .pm file during the build
1142 (in the pm_to_blib() phase). It is empty by default, meaning no
1143 filtering is done. You could use:
1144 PM_FILTER => 'perl -ne "print unless /^\\#/"',
1146 to remove all the leading comments on the fly during the build. In
1148 order to be as portable as possible, please consider using a Perl
1149 one-liner rather than Unix (or other) utilities, as above. The # is
1150 escaped for the Makefile, since what is going to be generated will
1151 then be:
1152 PM_FILTER = perl -ne "print unless /^\#/"
1154 Without the \ before the #, we'd have the start of a Makefile
1156 comment, and the macro would be incorrectly defined.
1157 You will almost certainly be better off using the "PL_FILES" system,
1159 instead. See above, or the ExtUtils::MakeMaker::FAQ entry.
1160 POLLUTE
1162 Release 5.005 grandfathered old global symbol names by providing
1163 preprocessor macros for extension source compatibility. As of
1164 release 5.6, these preprocessor definitions are not available by
1165 default. The POLLUTE flag specifies that the old names should still
1166 be defined:
1167 perl Makefile.PL POLLUTE=1
1169 Please inform the module author if this is necessary to successfully
1171 install a module under 5.6 or later.
1172 PPM_INSTALL_EXEC
1174 Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
1175 perl)
1176 PPM_INSTALL_SCRIPT
1178 Name of the script that gets executed by the Perl Package Manager
1179 after the installation of a package.
1180 PPM_UNINSTALL_EXEC
1182 Available in version 6.8502 and above.
1183 Name of the executable used to run "PPM_UNINSTALL_SCRIPT" below.
1185 (e.g. perl)
1186 PPM_UNINSTALL_SCRIPT
1188 Available in version 6.8502 and above.
1189 Name of the script that gets executed by the Perl Package Manager
1191 before the removal of a package.
1192 PREFIX
1194 This overrides all the default install locations. Man pages,
1195 libraries, scripts, etc... MakeMaker will try to make an educated
1196 guess about where to place things under the new PREFIX based on your
1197 Config defaults. Failing that, it will fall back to a structure
1198 which should be sensible for your platform.
1199 If you specify LIB or any INSTALL* variables they will not be
1201 affected by the PREFIX.
1202 PREREQ_FATAL
1204 Bool. If this parameter is true, failing to have the required modules
1205 (or the right versions thereof) will be fatal. "perl Makefile.PL"
1206 will "die" instead of simply informing the user of the missing
1207 dependencies.
1208 It is extremely rare to have to use "PREREQ_FATAL". Its use by module
1210 authors is strongly discouraged and should never be used lightly.
1211 For dependencies that are required in order to run "Makefile.PL", see
1213 "CONFIGURE_REQUIRES".
1214 Module installation tools have ways of resolving unmet dependencies
1216 but to do that they need a Makefile. Using "PREREQ_FATAL" breaks
1217 this. That's bad.
1218 Assuming you have good test coverage, your tests should fail with
1220 missing dependencies informing the user more strongly that something
1221 is wrong. You can write a t/00compile.t test which will simply check
1222 that your code compiles and stop "make test" prematurely if it
1223 doesn't. See "BAIL_OUT" in Test::More for more details.
1224 PREREQ_PM
1226 A hash of modules that are needed to run your module. The keys are
1227 the module names ie. Test::More, and the minimum version is the
1228 value. If the required version number is 0 any version will do. The
1229 versions given may be a Perl v-string (see version) or a range (see
1230 CPAN::Meta::Requirements).
1231 This will go into the "requires" field of your META.yml and the
1233 "runtime" of the "prereqs" field of your META.json.
1234 PREREQ_PM => {
1236 # Require Test::More at least 0.47
1237 "Test::More" => "0.47",
1238 # Require any version of Acme::Buffy
1240 "Acme::Buffy" => 0,
1241 }
1242 PREREQ_PRINT
1244 Bool. If this parameter is true, the prerequisites will be printed
1245 to stdout and MakeMaker will exit. The output format is an evalable
1246 hash ref.
1247 $PREREQ_PM = {
1249 'A::B' => Vers1,
1250 'C::D' => Vers2,
1251 ...
1252 };
1253 If a distribution defines a minimal required perl version, this is
1255 added to the output as an additional line of the form:
1256 $MIN_PERL_VERSION = '5.008001';
1258 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1260 hashref.
1261 PRINT_PREREQ
1263 RedHatism for "PREREQ_PRINT". The output format is different,
1264 though:
1265 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1267 A minimal required perl version, if present, will look like this:
1269 perl(perl)>=5.008001
1271 SITEPREFIX
1273 Like PERLPREFIX, but only for the site install locations.
1274 Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
1276 an explicit siteprefix in the Config. In those cases
1277 $Config{installprefix} will be used.
1278 Overridable by PREFIX
1280 SIGN
1282 Available in version 6.18 and above.
1283 When true, perform the generation and addition to the MANIFEST of the
1285 SIGNATURE file in the distdir during 'make distdir', via 'cpansign
1286 -s'.
1287 Note that you need to install the Module::Signature module to perform
1289 this operation.
1290 Defaults to false.
1292 SKIP
1294 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1295 Makefile. Caution! Do not use the SKIP attribute for the negligible
1296 speedup. It may seriously damage the resulting Makefile. Only use it
1297 if you really need it.
1298 TEST_REQUIRES
1300 Available in version 6.64 and above.
1301 A hash of modules that are needed to test your module but not run or
1303 build it.
1304 This will go into the "build_requires" field of your META.yml and the
1306 "test" of the "prereqs" field of your META.json.
1307 The format is the same as PREREQ_PM.
1309 TYPEMAPS
1311 Ref to array of typemap file names. Use this when the typemaps are
1312 in some directory other than the current directory or when they are
1313 not named typemap. The last typemap in the list takes precedence. A
1314 typemap in the current directory has highest precedence, even if it
1315 isn't listed in TYPEMAPS. The default system typemap has lowest
1316 precedence.
1317 USE_MM_LD_RUN_PATH
1319 boolean The Fedora perl MakeMaker distribution differs from the
1320 standard upstream release in that it disables use of the MakeMaker
1321 generated LD_RUN_PATH by default, UNLESS this attribute is specified
1322 , or the USE_MM_LD_RUN_PATH environment variable is set during the
1323 MakeMaker run.
1324 The upstream MakeMaker will set the ld(1) environment variable
1326 LD_RUN_PATH to the concatenation of every -L ld(1) option directory
1327 in which a -l ld(1) option library is found, which is used as the
1328 ld(1) -rpath option if none is specified. This means that, if your
1329 application builds shared libraries and your MakeMaker application
1330 links to them, that the absolute paths of the libraries in the build
1331 tree will be inserted into the RPATH header of all MakeMaker
1332 generated binaries, and that such binaries will be unable to link to
1333 these libraries if they do not still reside in the build tree
1334 directories (unlikely) or in the system library directories (/lib or
1335 /usr/lib), regardless of any LD_LIBRARY_PATH setting. So if you
1336 specified -L../mylib -lmylib , and
1337 your 'libmylib.so' gets installed into
1338 /some_directory_other_than_usr_lib,
1339 your MakeMaker application will be unable to link to it, even if
1340 LD_LIBRARY_PATH is set to include /some_directory_other_than_usr_lib,
1341 because RPATH overrides LD_LIBRARY_PATH.
1342 So for Fedora MakeMaker builds LD_RUN_PATH is NOT generated by
1344 default for every link. You can still use explicit -rpath ld options
1345 or the LD_RUN_PATH environment variable during the build to generate
1346 an RPATH for the binaries.
1347 You can set the USE_MM_LD_RUN_PATH attribute to 1 on the MakeMaker
1349 command line or in the WriteMakefile arguments to enable generation
1350 of LD_RUN_PATH for every link command.
1351 USE_MM_LD_RUN_PATH will default to 1 (LD_RUN_PATH will be used) IF
1353 the $USE_MM_LD_RUN_PATH environment variable is set during a
1354 MakeMaker run.
1355 VENDORPREFIX
1357 Like PERLPREFIX, but only for the vendor install locations.
1358 Defaults to $Config{vendorprefixexp}.
1360 Overridable by PREFIX
1362 VERBINST
1364 If true, make install will be verbose
1365 VERSION
1367 Your version number for distributing the package. This defaults to
1368 0.1.
1369 VERSION_FROM
1371 Instead of specifying the VERSION in the Makefile.PL you can let
1372 MakeMaker parse a file to determine the version number. The parsing
1373 routine requires that the file named by VERSION_FROM contains one
1374 single line to compute the version number. The first line in the file
1375 that contains something like a $VERSION assignment or "package Name
1376 VERSION" will be used. The following lines will be parsed o.k.:
1377 # Good
1379 package Foo::Bar 1.23; # 1.23
1380 $VERSION = '1.00'; # 1.00
1381 *VERSION = \'1.01'; # 1.01
1382 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
1383 $FOO::VERSION = '1.10'; # 1.10
1384 *FOO::VERSION = \'1.11'; # 1.11
1385 but these will fail:
1387 # Bad
1389 my $VERSION = '1.01';
1390 local $VERSION = '1.02';
1391 local $FOO::VERSION = '1.30';
1392 (Putting "my" or "local" on the preceding line will work o.k.)
1394 "Version strings" are incompatible and should not be used.
1396 # Bad
1398 $VERSION = 1.2.3;
1399 $VERSION = v1.2.3;
1400 version objects are fine. As of MakeMaker 6.35 version.pm will be
1402 automatically loaded, but you must declare the dependency on
1403 version.pm. For compatibility with older MakeMaker you should load
1404 on the same line as $VERSION is declared.
1405 # All on one line
1407 use version; our $VERSION = qv(1.2.3);
1408 The file named in VERSION_FROM is not added as a dependency to
1410 Makefile. This is not really correct, but it would be a major pain
1411 during development to have to rewrite the Makefile for any smallish
1412 change in that file. If you want to make sure that the Makefile
1413 contains the correct VERSION macro after any change of the file, you
1414 would have to do something like
1415 depend => { Makefile => '$(VERSION_FROM)' }
1417 See attribute "depend" below.
1419 VERSION_SYM
1421 A sanitized VERSION with . replaced by _. For places where . has
1422 special meaning (some filesystems, RCS labels, etc...)
1423 XS
1425 Hashref of .xs files. MakeMaker will default this. e.g.
1426 {'name_of_file.xs' => 'name_of_file.c'}
1428 The .c files will automatically be included in the list of files
1430 deleted by a make clean.
1431 XSBUILD
1433 Available in version 7.12 and above.
1434 Hashref with options controlling the operation of "XSMULTI":
1436 {
1438 xs => {
1439 all => {
1440 # options applying to all .xs files for this distribution
1441 },
1442 'lib/Class/Name/File' => { # specifically for this file
1443 DEFINE => '-Dfunktastic', # defines for only this file
1444 INC => "-I$funkyliblocation", # include flags for only this file
1445 # OBJECT => 'lib/Class/Name/File$(OBJ_EXT)', # default
1446 LDFROM => "lib/Class/Name/File\$(OBJ_EXT) $otherfile\$(OBJ_EXT)", # what's linked
1447 },
1448 },
1449 }
1450 Note "xs" is the file-extension. More possibilities may arise in the
1452 future. Note that object names are specified without their XS
1453 extension.
1454 "LDFROM" defaults to the same as "OBJECT". "OBJECT" defaults to, for
1456 "XSMULTI", just the XS filename with the extension replaced with the
1457 compiler-specific object-file extension.
1458 The distinction between "OBJECT" and "LDFROM": "OBJECT" is the make
1460 target, so make will try to build it. However, "LDFROM" is what will
1461 actually be linked together to make the shared object or static
1462 library (SO/SL), so if you override it, make sure it includes what
1463 you want to make the final SO/SL, almost certainly including the XS
1464 basename with "$(OBJ_EXT)" appended.
1465 XSMULTI
1467 Available in version 7.12 and above.
1468 When this is set to 1, multiple XS files may be placed under lib/
1470 next to their corresponding "*.pm" files (this is essential for
1471 compiling with the correct "VERSION" values). This feature should be
1472 considered experimental, and details of it may change.
1473 This feature was inspired by, and small portions of code copied from,
1475 ExtUtils::MakeMaker::BigHelper. Hopefully this feature will render
1476 that module mainly obsolete.
1477 XSOPT
1479 String of options to pass to xsubpp. This might include "-C++" or
1480 "-extern". Do not include typemaps here; the TYPEMAP parameter
1481 exists for that purpose.
1482 XSPROTOARG
1484 May be set to "-prototypes", "-noprototypes" or the empty string.
1485 The empty string is equivalent to the xsubpp default, or
1486 "-noprototypes". See the xsubpp documentation for details.
1487 MakeMaker defaults to the empty string.
1488 XS_VERSION
1490 Your version number for the .xs file of this package. This defaults
1491 to the value of the VERSION attribute.
1492 Additional lowercase attributes
1494 can be used to pass parameters to the methods which implement that part
1495 of the Makefile. Parameters are specified as a hash ref but are passed
1496 to the method as a hash.
1497 clean
1499 {FILES => "*.xyz foo"}
1500 depend
1502 {ANY_TARGET => ANY_DEPENDENCY, ...}
1503 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1505 dist
1507 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1508 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1509 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1510 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1512 needed to tell make the target file of the compression. Setting
1513 DIST_CP to ln can be useful, if you need to preserve the timestamps
1514 on your files. DIST_CP can take the values 'cp', which copies the
1515 file, 'ln', which links the file, and 'best' which copies symbolic
1516 links and links the rest. Default is 'best'.
1517 dynamic_lib
1519 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1520 linkext
1522 {LINKTYPE => 'static', 'dynamic' or ''}
1523 NB: Extensions that have nothing but *.pm files had to say
1525 {LINKTYPE => ''}
1527 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1529 can be deleted safely. MakeMaker recognizes when there's nothing to
1530 be linked.
1531 macro
1533 {ANY_MACRO => ANY_VALUE, ...}
1534 postamble
1536 Anything put here will be passed to MY::postamble() if you have one.
1537 realclean
1539 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1540 test
1542 Specify the targets for testing.
1543 {TESTS => 't/*.t'}
1545 "RECURSIVE_TEST_FILES" can be used to include all directories
1547 recursively under "t" that contain ".t" files. It will be ignored if
1548 you provide your own "TESTS" attribute, defaults to false.
1549 {RECURSIVE_TEST_FILES=>1}
1551 This is supported since 6.76
1553 tool_autosplit
1555 {MAXLEN => 8}
1556 Overriding MakeMaker Methods
1558 If you cannot achieve the desired Makefile behaviour by specifying
1559 attributes you may define private subroutines in the Makefile.PL. Each
1560 subroutine returns the text it wishes to have written to the Makefile.
1561 To override a section of the Makefile you can either say:
1562 sub MY::c_o { "new literal text" }
1564 or you can edit the default by saying something like:
1566 package MY; # so that "SUPER" works right
1568 sub c_o {
1569 my $inherited = shift->SUPER::c_o(@_);
1570 $inherited =~ s/old text/new text/;
1571 $inherited;
1572 }
1573 If you are running experiments with embedding perl as a library into
1575 other applications, you might find MakeMaker is not sufficient. You'd
1576 better have a look at ExtUtils::Embed which is a collection of
1577 utilities for embedding.
1578 If you still need a different solution, try to develop another
1580 subroutine that fits your needs and submit the diffs to
1581 "makemaker@perl.org"
1582 For a complete description of all MakeMaker methods see
1584 ExtUtils::MM_Unix.
1585 Here is a simple example of how to add a new target to the generated
1587 Makefile:
1588 sub MY::postamble {
1590 return <<'MAKE_FRAG';
1591 $(MYEXTLIB): sdbm/Makefile
1592 cd sdbm && $(MAKE) all
1593 MAKE_FRAG
1595 }
1596 The End Of Cargo Cult Programming
1598 WriteMakefile() now does some basic sanity checks on its parameters to
1599 protect against typos and malformatted values. This means some things
1600 which happened to work in the past will now throw warnings and possibly
1601 produce internal errors.
1602 Some of the most common mistakes:
1604 "MAN3PODS => ' '"
1606 This is commonly used to suppress the creation of man pages.
1607 MAN3PODS takes a hash ref not a string, but the above worked by
1608 accident in old versions of MakeMaker.
1609 The correct code is "MAN3PODS => { }".
1611 Hintsfile support
1613 MakeMaker.pm uses the architecture-specific information from Config.pm.
1614 In addition it evaluates architecture specific hints files in a
1615 "hints/" directory. The hints files are expected to be named like their
1616 counterparts in "PERL_SRC/hints", but with an ".pl" file name extension
1617 (eg. "next_3_2.pl"). They are simply "eval"ed by MakeMaker within the
1618 WriteMakefile() subroutine, and can be used to execute commands as well
1619 as to include special variables. The rules which hintsfile is chosen
1620 are the same as in Configure.
1621 The hintsfile is eval()ed immediately after the arguments given to
1623 WriteMakefile are stuffed into a hash reference $self but before this
1624 reference becomes blessed. So if you want to do the equivalent to
1625 override or create an attribute you would say something like
1626 $self->{LIBS} = ['-ldbm -lucb -lc'];
1628 Distribution Support
1630 For authors of extensions MakeMaker provides several Makefile targets.
1631 Most of the support comes from the ExtUtils::Manifest module, where
1632 additional documentation can be found.
1633 make distcheck
1635 reports which files are below the build directory but not in the
1636 MANIFEST file and vice versa. (See "fullcheck" in
1637 ExtUtils::Manifest for details)
1638 make skipcheck
1640 reports which files are skipped due to the entries in the
1641 "MANIFEST.SKIP" file (See "skipcheck" in ExtUtils::Manifest for
1642 details)
1643 make distclean
1645 does a realclean first and then the distcheck. Note that this is
1646 not needed to build a new distribution as long as you are sure that
1647 the MANIFEST file is ok.
1648 make veryclean
1650 does a realclean first and then removes backup files such as "*~",
1651 "*.bak", "*.old" and "*.orig"
1652 make manifest
1654 rewrites the MANIFEST file, adding all remaining files found (See
1655 "mkmanifest" in ExtUtils::Manifest for details)
1656 make distdir
1658 Copies all the files that are in the MANIFEST file to a newly
1659 created directory with the name "$(DISTNAME)-$(VERSION)". If that
1660 directory exists, it will be removed first.
1661 Additionally, it will create META.yml and META.json module meta-
1663 data file in the distdir and add this to the distdir's MANIFEST.
1664 You can shut this behavior off with the NO_META flag.
1665 make disttest
1667 Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1668 make test in that directory.
1669 make tardist
1671 First does a distdir. Then a command $(PREOP) which defaults to a
1672 null command, followed by $(TO_UNIX), which defaults to a null
1673 command under UNIX, and will convert files in distribution
1674 directory to UNIX format otherwise. Next it runs "tar" on that
1675 directory into a tarfile and deletes the directory. Finishes with a
1676 command $(POSTOP) which defaults to a null command.
1677 make dist
1679 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1680 make uutardist
1682 Runs a tardist first and uuencodes the tarfile.
1683 make shdist
1685 First does a distdir. Then a command $(PREOP) which defaults to a
1686 null command. Next it runs "shar" on that directory into a sharfile
1687 and deletes the intermediate directory again. Finishes with a
1688 command $(POSTOP) which defaults to a null command. Note: For
1689 shdist to work properly a "shar" program that can handle
1690 directories is mandatory.
1691 make zipdist
1693 First does a distdir. Then a command $(PREOP) which defaults to a
1694 null command. Runs "$(ZIP) $(ZIPFLAGS)" on that directory into a
1695 zipfile. Then deletes that directory. Finishes with a command
1696 $(POSTOP) which defaults to a null command.
1697 make ci
1699 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1700 Customization of the dist targets can be done by specifying a hash
1702 reference to the dist attribute of the WriteMakefile call. The
1703 following parameters are recognized:
1704 CI ('ci -u')
1706 COMPRESS ('gzip --best')
1707 POSTOP ('@ :')
1708 PREOP ('@ :')
1709 TO_UNIX (depends on the system)
1710 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1711 SHAR ('shar')
1712 SUFFIX ('.gz')
1713 TAR ('tar')
1714 TARFLAGS ('cvf')
1715 ZIP ('zip')
1716 ZIPFLAGS ('-r')
1717 An example:
1719 WriteMakefile(
1721 ...other options...
1722 dist => {
1723 COMPRESS => "bzip2",
1724 SUFFIX => ".bz2"
1725 }
1726 );
1727 Module Meta-Data (META and MYMETA)
1729 Long plaguing users of MakeMaker based modules has been the problem of
1730 getting basic information about the module out of the sources without
1731 running the Makefile.PL and doing a bunch of messy heuristics on the
1732 resulting Makefile. Over the years, it has become standard to keep
1733 this information in one or more CPAN Meta files distributed with each
1734 distribution.
1735 The original format of CPAN Meta files was YAML and the corresponding
1737 file was called META.yml. In 2010, version 2 of the CPAN::Meta::Spec
1738 was released, which mandates JSON format for the metadata in order to
1739 overcome certain compatibility issues between YAML serializers and to
1740 avoid breaking older clients unable to handle a new version of the
1741 spec. The CPAN::Meta library is now standard for accessing old and
1742 new-style Meta files.
1743 If CPAN::Meta is installed, MakeMaker will automatically generate
1745 META.json and META.yml files for you and add them to your MANIFEST as
1746 part of the 'distdir' target (and thus the 'dist' target). This is
1747 intended to seamlessly and rapidly populate CPAN with module meta-data.
1748 If you wish to shut this feature off, set the "NO_META"
1749 "WriteMakefile()" flag to true.
1750 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers
1752 agreed to use the CPAN Meta format to communicate post-configuration
1753 requirements between toolchain components. These files, MYMETA.json
1754 and MYMETA.yml, are generated when Makefile.PL generates a Makefile (if
1755 CPAN::Meta is installed). Clients like CPAN or CPANPLUS will read
1756 these files to see what prerequisites must be fulfilled before building
1757 or testing the distribution. If you wish to shut this feature off, set
1758 the "NO_MYMETA" "WriteMakeFile()" flag to true.
1759 Disabling an extension
1761 If some events detected in Makefile.PL imply that there is no way to
1762 create the Module, but this is a normal state of things, then you can
1763 create a Makefile which does nothing, but succeeds on all the "usual"
1764 build targets. To do so, use
1765 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1767 WriteEmptyMakefile();
1768 instead of WriteMakefile().
1770 This may be useful if other modules expect this module to be built OK,
1772 as opposed to work OK (say, this system-dependent module builds in a
1773 subdirectory of some other distribution, or is listed as a dependency
1774 in a CPAN::Bundle, but the functionality is supported by different
1775 means on the current architecture).
1776 Other Handy Functions
1778 prompt
1779 my $value = prompt($message);
1780 my $value = prompt($message, $default);
1781 The "prompt()" function provides an easy way to request user input
1783 used to write a makefile. It displays the $message as a prompt for
1784 input. If a $default is provided it will be used as a default.
1785 The function returns the $value selected by the user.
1786 If "prompt()" detects that it is not running interactively and
1788 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1789 variable is set to true, the $default will be used without
1790 prompting. This prevents automated processes from blocking on user
1791 input.
1792 If no $default is provided an empty string will be used instead.
1794 os_unsupported
1796 os_unsupported();
1797 os_unsupported if $^O eq 'MSWin32';
1798 The "os_unsupported()" function provides a way to correctly exit
1800 your "Makefile.PL" before calling "WriteMakefile". It is
1801 essentially a "die" with the message "OS unsupported".
1802 This is supported since 7.26
1804 Supported versions of Perl
1806 Please note that while this module works on Perl 5.6, it is no longer
1807 being routinely tested on 5.6 - the earliest Perl version being
1808 routinely tested, and expressly supported, is 5.8.1. However, patches
1809 to repair any breakage on 5.6 are still being accepted.
1810
1812 PERL_MM_OPT
1813 Command line options used by "MakeMaker->new()", and thus by
1814 "WriteMakefile()". The string is split as the shell would, and the
1815 result is processed before any actual command line arguments are
1816 processed.
1817 PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1819 PERL_MM_USE_DEFAULT
1821 If set to a true value then MakeMaker's prompt function will always
1822 return the default without waiting for user input.
1823 PERL_CORE
1825 Same as the PERL_CORE parameter. The parameter overrides this.
1826
1828 Module::Build is a pure-Perl alternative to MakeMaker which does not
1829 rely on make or any other external utility. It may be easier to extend
1830 to suit your needs.
1831 Module::Build::Tiny is a minimal pure-Perl alternative to MakeMaker
1833 that follows the Build.PL protocol of Module::Build but without its
1834 complexity and cruft, implementing only the installation of the module
1835 and leaving authoring to mbtiny or other authoring tools.
1836 Module::Install is a (now discouraged) wrapper around MakeMaker which
1838 adds features not normally available.
1839 ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1841 setup your distribution.
1842 CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1844 File::ShareDir::Install makes it easy to install static, sometimes also
1846 referred to as 'shared' files. File::ShareDir helps accessing the
1847 shared files after installation. Test::File::ShareDir helps when
1848 writing tests to use the shared files both before and after
1849 installation.
1850 Dist::Zilla is an authoring tool which allows great customization and
1852 extensibility of the author experience, relying on the existing install
1853 tools like ExtUtils::MakeMaker only for installation.
1854 Dist::Milla is a Dist::Zilla bundle that greatly simplifies common
1856 usage.
1857 Minilla is a minimal authoring tool that does the same things as
1859 Dist::Milla without the overhead of Dist::Zilla.
1860
1862 Andy Dougherty "doughera@lafayette.edu", Andreas König
1863 "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org". VMS support by
1864 Charles Bailey "bailey@newman.upenn.edu". OS/2 support by Ilya
1865 Zakharevich "ilya@math.ohio-state.edu".
1866 Currently maintained by Michael G Schwern "schwern@pobox.com"
1868 Send patches and ideas to "makemaker@perl.org".
1870 Send bug reports via http://rt.cpan.org/. Please send your generated
1872 Makefile along with your report.
1873 For more up-to-date information, see
1875 <https://metacpan.org/release/ExtUtils-MakeMaker>.
1876 Repository available at
1878 <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1879
1881 This program is free software; you can redistribute it and/or modify it
1882 under the same terms as Perl itself.
1883 See <http://www.perl.com/perl/misc/Artistic.html>
1885perl v5.32.1 2021-04-14 ExtUtils::MakeMaker(3)