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. Note that setting this will
433 overwrite its default value ($Config::Config{ccflags}); to preserve
434 that, include the default value directly, e.g.:
435 CCFLAGS => "$Config::Config{ccflags} ..."
437 CONFIG
439 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
440 config.sh. MakeMaker will add to CONFIG the following values anyway:
441 ar cc cccdlflags ccdlflags cpprun dlext dlsrc ld lddlflags ldflags
442 libc lib_ext obj_ext ranlib sitelibexp sitearchexp so
443 CONFIGURE
445 CODE reference. The subroutine should return a hash reference. The
446 hash may contain further attributes, e.g. {LIBS => ...}, that have to
447 be determined by some evaluation method.
448 CONFIGURE_REQUIRES
450 Available in version 6.52 and above.
451 A hash of modules that are required to run Makefile.PL itself, but
453 not to run your distribution.
454 This will go into the "configure_requires" field of your META.yml and
456 the "configure" of the "prereqs" field of your META.json.
457 Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
459 specified.
460 The format is the same as PREREQ_PM.
462 DEFINE
464 Something like "-DHAVE_UNISTD_H"
465 DESTDIR
467 This is the root directory into which the code will be installed. It
468 prepends itself to the normal prefix. For example, if your code
469 would normally go into /usr/local/lib/perl you could set
470 DESTDIR=~/tmp/ and installation would go into
471 ~/tmp/usr/local/lib/perl.
472 This is primarily of use for people who repackage Perl modules.
474 NOTE: Due to the nature of make, it is important that you put the
476 trailing slash on your DESTDIR. ~/tmp/ not ~/tmp.
477 DIR
479 Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
480 in ext/SDBM_File
481 DISTNAME
483 A safe filename for the package.
484 Defaults to NAME below but with :: replaced with -.
486 For example, Foo::Bar becomes Foo-Bar.
488 DISTVNAME
490 Your name for distributing the package with the version number
491 included. This is used by 'make dist' to name the resulting archive
492 file.
493 Defaults to DISTNAME-VERSION.
495 For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
497 On some OS's where . has special meaning VERSION_SYM may be used in
499 place of VERSION.
500 DLEXT
502 Specifies the extension of the module's loadable object. For example:
503 DLEXT => 'unusual_ext', # Default value is $Config{so}
505 NOTE: When using this option to alter the extension of a module's
507 loadable object, it is also necessary that the module's pm file
508 specifies the same change:
509 local $DynaLoader::dl_dlext = 'unusual_ext';
511 DL_FUNCS
513 Hashref of symbol names for routines to be made available as
514 universal symbols. Each key/value pair consists of the package name
515 and an array of routine names in that package. Used only under AIX,
516 OS/2, VMS and Win32 at present. The routine names supplied will be
517 expanded in the same way as XSUB names are expanded by the XS()
518 macro. Defaults to
519 {"$(NAME)" => ["boot_$(NAME)" ] }
521 e.g.
523 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
525 "NetconfigPtr" => [ 'DESTROY'] }
526 Please see the ExtUtils::Mksymlists documentation for more
528 information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
529 DL_VARS
531 Array of symbol names for variables to be made available as universal
532 symbols. Used only under AIX, OS/2, VMS and Win32 at present.
533 Defaults to []. (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
534 EXCLUDE_EXT
536 Array of extension names to exclude when doing a static build. This
537 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
538 details. (e.g. [ qw( Socket POSIX ) ] )
539 This attribute may be most useful when specified as a string on the
541 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
542 EXE_FILES
544 Ref to array of executable files. The files will be copied to the
545 INST_SCRIPT directory. Make realclean will delete them from there
546 again.
547 If your executables start with something like #!perl or
549 #!/usr/bin/perl MakeMaker will change this to the path of the perl
550 'Makefile.PL' was invoked with so the programs will be sure to run
551 properly even if perl is not in /usr/bin/perl.
552 FIRST_MAKEFILE
554 The name of the Makefile to be produced. This is used for the second
555 Makefile that will be produced for the MAP_TARGET.
556 Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
558 (Note: we couldn't use MAKEFILE because dmake uses this for something
560 else).
561 FULLPERL
563 Perl binary able to run this extension, load XS modules, etc...
564 FULLPERLRUN
566 Like PERLRUN, except it uses FULLPERL.
567 FULLPERLRUNINST
569 Like PERLRUNINST, except it uses FULLPERL.
570 FUNCLIST
572 This provides an alternate means to specify function names to be
573 exported from the extension. Its value is a reference to an array of
574 function names to be exported by the extension. These names are
575 passed through unaltered to the linker options file.
576 H Ref to array of *.h file names. Similar to C.
578 IMPORTS
580 This attribute is used to specify names to be imported into the
581 extension. Takes a hash ref.
582 It is only used on OS/2 and Win32.
584 INC
586 Include file dirs eg: "-I/usr/5include -I/path/to/inc"
587 INCLUDE_EXT
589 Array of extension names to be included when doing a static build.
590 MakeMaker will normally build with all of the installed extensions
591 when doing a static build, and that is usually the desired behavior.
592 If INCLUDE_EXT is present then MakeMaker will build only with those
593 extensions which are explicitly mentioned. (e.g. [ qw( Socket POSIX
594 ) ])
595 It is not necessary to mention DynaLoader or the current extension
597 when filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is
598 empty then only DynaLoader and the current extension will be included
599 in the build.
600 This attribute may be most useful when specified as a string on the
602 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket
603 Devel::Peek'
604 INSTALLARCHLIB
606 Used by 'make install', which copies files from INST_ARCHLIB to this
607 directory if INSTALLDIRS is set to perl.
608 INSTALLBIN
610 Directory to install binary files (e.g. tkperl) into if
611 INSTALLDIRS=perl.
612 INSTALLDIRS
614 Determines which of the sets of installation directories to choose:
615 perl, site or vendor. Defaults to site.
616 INSTALLMAN1DIR
618 INSTALLMAN3DIR
619 These directories get the man pages at 'make install' time if
620 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
621 If set to 'none', no man pages will be installed.
623 INSTALLPRIVLIB
625 Used by 'make install', which copies files from INST_LIB to this
626 directory if INSTALLDIRS is set to perl.
627 Defaults to $Config{installprivlib}.
629 INSTALLSCRIPT
631 Available in version 6.30_02 and above.
632 Used by 'make install' which copies files from INST_SCRIPT to this
634 directory if INSTALLDIRS=perl.
635 INSTALLSITEARCH
637 Used by 'make install', which copies files from INST_ARCHLIB to this
638 directory if INSTALLDIRS is set to site (default).
639 INSTALLSITEBIN
641 Used by 'make install', which copies files from INST_BIN to this
642 directory if INSTALLDIRS is set to site (default).
643 INSTALLSITELIB
645 Used by 'make install', which copies files from INST_LIB to this
646 directory if INSTALLDIRS is set to site (default).
647 INSTALLSITEMAN1DIR
649 INSTALLSITEMAN3DIR
650 These directories get the man pages at 'make install' time if
651 INSTALLDIRS=site (default). Defaults to
652 $(SITEPREFIX)/man/man$(MAN*EXT).
653 If set to 'none', no man pages will be installed.
655 INSTALLSITESCRIPT
657 Used by 'make install' which copies files from INST_SCRIPT to this
658 directory if INSTALLDIRS is set to site (default).
659 INSTALLVENDORARCH
661 Used by 'make install', which copies files from INST_ARCHLIB to this
662 directory if INSTALLDIRS is set to vendor. Note that if you do not
663 set this, the value of INSTALLVENDORLIB will be used, which is
664 probably not what you want.
665 INSTALLVENDORBIN
667 Used by 'make install', which copies files from INST_BIN to this
668 directory if INSTALLDIRS is set to vendor.
669 INSTALLVENDORLIB
671 Used by 'make install', which copies files from INST_LIB to this
672 directory if INSTALLDIRS is set to vendor.
673 INSTALLVENDORMAN1DIR
675 INSTALLVENDORMAN3DIR
676 These directories get the man pages at 'make install' time if
677 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
678 If set to 'none', no man pages will be installed.
680 INSTALLVENDORSCRIPT
682 Available in version 6.30_02 and above.
683 Used by 'make install' which copies files from INST_SCRIPT to this
685 directory if INSTALLDIRS is set to vendor.
686 INST_ARCHLIB
688 Same as INST_LIB for architecture dependent files.
689 INST_BIN
691 Directory to put real binary files during 'make'. These will be
692 copied to INSTALLBIN during 'make install'
693 INST_LIB
695 Directory where we put library files of this extension while building
696 it.
697 INST_MAN1DIR
699 Directory to hold the man pages at 'make' time
700 INST_MAN3DIR
702 Directory to hold the man pages at 'make' time
703 INST_SCRIPT
705 Directory where executable files should be installed during 'make'.
706 Defaults to "./blib/script", just to have a dummy location during
707 testing. make install will copy the files in INST_SCRIPT to
708 INSTALLSCRIPT.
709 LD
711 Program to be used to link libraries for dynamic loading.
712 Defaults to $Config{ld}.
714 LDDLFLAGS
716 Any special flags that might need to be passed to ld to create a
717 shared library suitable for dynamic loading. It is up to the
718 makefile to use it. (See "lddlflags" in Config)
719 Defaults to $Config{lddlflags}.
721 LDFROM
723 Defaults to "$(OBJECT)" and is used in the ld command to specify what
724 files to link/load from (also see dynamic_lib below for how to
725 specify ld flags)
726 LIB
728 LIB should only be set at "perl Makefile.PL" time but is allowed as a
729 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
730 and INSTALLSITELIB to that value regardless any explicit setting of
731 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
732 are set to the corresponding architecture subdirectory.
733 LIBPERL_A
735 The filename of the perllibrary that will be used together with this
736 extension. Defaults to libperl.a.
737 LIBS
739 An anonymous array of alternative library specifications to be
740 searched for (in order) until at least one library is found. E.g.
741 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
743 Mind, that any element of the array contains a complete set of
745 arguments for the ld command. So do not specify
746 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
748 See ODBM_File/Makefile.PL for an example, where an array is needed.
750 If you specify a scalar as in
751 'LIBS' => "-ltcl -ltk -lX11"
753 MakeMaker will turn it into an array with one element.
755 LICENSE
757 Available in version 6.31 and above.
758 The licensing terms of your distribution. Generally it's "perl_5"
760 for the same license as Perl itself.
761 See CPAN::Meta::Spec for the list of options.
763 Defaults to "unknown".
765 LINKTYPE
767 'static' or 'dynamic' (default unless usedl=undef in config.sh).
768 Should only be used to force static linking (also see linkext below).
769 MAGICXS
771 Available in version 6.8305 and above.
772 When this is set to 1, "OBJECT" will be automagically derived from
774 "O_FILES".
775 MAKE
777 Available in version 6.30_01 and above.
778 Variant of make you intend to run the generated Makefile with. This
780 parameter lets Makefile.PL know what make quirks to account for when
781 generating the Makefile.
782 MakeMaker also honors the MAKE environment variable. This parameter
784 takes precedence.
785 Currently the only significant values are 'dmake' and 'nmake' for
787 Windows users, instructing MakeMaker to generate a Makefile in the
788 flavour of DMake ("Dennis Vadura's Make") or Microsoft NMake
789 respectively.
790 Defaults to $Config{make}, which may go looking for a Make program in
792 your environment.
793 How are you supposed to know what flavour of Make a Makefile has been
795 generated for if you didn't specify a value explicitly? Search the
796 generated Makefile for the definition of the MAKE variable, which is
797 used to recursively invoke the Make utility. That will tell you what
798 Make you're supposed to invoke the Makefile with.
799 MAKEAPERL
801 Boolean which tells MakeMaker that it should include the rules to
802 make a perl. This is handled automatically as a switch by MakeMaker.
803 The user normally does not need it.
804 MAKEFILE_OLD
806 When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
807 backed up at this location.
808 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
810 MAN1PODS
812 Hashref of pod-containing files. MakeMaker will default this to all
813 EXE_FILES files that include POD directives. The files listed here
814 will be converted to man pages and installed as was requested at
815 Configure time.
816 This hash should map POD files (or scripts containing POD) to the man
818 file names under the "blib/man1/" directory, as in the following
819 example:
820 MAN1PODS => {
822 'doc/command.pod' => 'blib/man1/command.1',
823 'scripts/script.pl' => 'blib/man1/script.1',
824 }
825 MAN3PODS
827 Hashref that assigns to *.pm and *.pod files the files into which the
828 manpages are to be written. MakeMaker parses all *.pod and *.pm files
829 for POD directives. Files that contain POD will be the default keys
830 of the MAN3PODS hashref. These will then be converted to man pages
831 during "make" and will be installed during "make install".
832 Example similar to MAN1PODS.
834 MAP_TARGET
836 If it is intended that a new perl binary be produced, this variable
837 may hold a name for that binary. Defaults to perl
838 META_ADD
840 META_MERGE
841 Available in version 6.46 and above.
842 A hashref of items to add to the CPAN Meta file (META.yml or
844 META.json).
845 They differ in how they behave if they have the same key as the
847 default metadata. META_ADD will override the default value with its
848 own. META_MERGE will merge its value with the default.
849 Unless you want to override the defaults, prefer META_MERGE so as to
851 get the advantage of any future defaults.
852 Where prereqs are concerned, if META_MERGE is used, prerequisites are
854 merged with their counterpart WriteMakefile() argument (PREREQ_PM is
855 merged into {prereqs}{runtime}{requires}, BUILD_REQUIRES into
856 "{prereqs}{build}{requires}", CONFIGURE_REQUIRES into
857 "{prereqs}{configure}{requires}", and TEST_REQUIRES into
858 "{prereqs}{test}{requires})". When prereqs are specified with
859 META_ADD, the only prerequisites added to the file come from the
860 metadata, not WriteMakefile() arguments.
861 Note that these configuration options are only used for generating
863 META.yml and META.json -- they are NOT used for MYMETA.yml and
864 MYMETA.json. Therefore data in these fields should NOT be used for
865 dynamic (user-side) configuration.
866 By default CPAN Meta specification 1.4 is used. In order to use CPAN
868 Meta specification 2.0, indicate with "meta-spec" the version you
869 want to use.
870 META_MERGE => {
872 "meta-spec" => { version => 2 },
874 resources => {
876 repository => {
878 type => 'git',
879 url => 'git://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker.git',
880 web => 'https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker',
881 },
882 },
884 },
886 MIN_PERL_VERSION
888 Available in version 6.48 and above.
889 The minimum required version of Perl for this distribution.
891 Either the 5.006001 or the 5.6.1 format is acceptable.
893 MYEXTLIB
895 If the extension links to a library that it builds, set this to the
896 name of the library (see SDBM_File)
897 NAME
899 The package representing the distribution. For example, "Test::More"
900 or "ExtUtils::MakeMaker". It will be used to derive information about
901 the distribution such as the "DISTNAME", installation locations
902 within the Perl library and where XS files will be looked for by
903 default (see "XS").
904 "NAME" must be a valid Perl package name and it must have an
906 associated ".pm" file. For example, "Foo::Bar" is a valid "NAME" and
907 there must exist Foo/Bar.pm. Any XS code should be in Bar.xs unless
908 stated otherwise.
909 Your distribution must have a "NAME".
911 NEEDS_LINKING
913 MakeMaker will figure out if an extension contains linkable code
914 anywhere down the directory tree, and will set this variable
915 accordingly, but you can speed it up a very little bit if you define
916 this boolean variable yourself.
917 NOECHO
919 Command so make does not print the literal commands it's running.
920 By setting it to an empty string you can generate a Makefile that
922 prints all commands. Mainly used in debugging MakeMaker itself.
923 Defaults to "@".
925 NORECURS
927 Boolean. Attribute to inhibit descending into subdirectories.
928 NO_META
930 When true, suppresses the generation and addition to the MANIFEST of
931 the META.yml and META.json module meta-data files during 'make
932 distdir'.
933 Defaults to false.
935 NO_MYMETA
937 Available in version 6.57_02 and above.
938 When true, suppresses the generation of MYMETA.yml and MYMETA.json
940 module meta-data files during 'perl Makefile.PL'.
941 Defaults to false.
943 NO_PACKLIST
945 Available in version 6.7501 and above.
946 When true, suppresses the writing of "packlist" files for installs.
948 Defaults to false.
950 NO_PERLLOCAL
952 Available in version 6.7501 and above.
953 When true, suppresses the appending of installations to "perllocal".
955 Defaults to false.
957 NO_VC
959 In general, any generated Makefile checks for the current version of
960 MakeMaker and the version the Makefile was built under. If NO_VC is
961 set, the version check is neglected. Do not write this into your
962 Makefile.PL, use it interactively instead.
963 OBJECT
965 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be
966 a long string or an array containing all object files, e.g.
967 "tkpBind.o tkpButton.o tkpCanvas.o" or ["tkpBind.o", "tkpButton.o",
968 "tkpCanvas.o"]
969 (Where BASEEXT is the last component of NAME, and OBJ_EXT is
971 $Config{obj_ext}.)
972 OPTIMIZE
974 Defaults to "-O". Set it to "-g" to turn debugging on. The flag is
975 passed to subdirectory makes.
976 PERL
978 Perl binary for tasks that can be done by miniperl. If it contains
979 spaces or other shell metacharacters, it needs to be quoted in a way
980 that protects them, since this value is intended to be inserted in a
981 shell command line in the Makefile. E.g.:
982 # Perl executable lives in "C:/Program Files/Perl/bin"
984 # Normally you don't need to set this yourself!
985 $ perl Makefile.PL PERL='"C:/Program Files/Perl/bin/perl.exe" -w'
986 PERL_CORE
988 Set only when MakeMaker is building the extensions of the Perl core
989 distribution.
990 PERLMAINCC
992 The call to the program that is able to compile perlmain.c. Defaults
993 to $(CC).
994 PERL_ARCHLIB
996 Same as for PERL_LIB, but for architecture dependent files.
997 Used only when MakeMaker is building the extensions of the Perl core
999 distribution (because normally $(PERL_ARCHLIB) is automatically in
1000 @INC, and adding it would get in the way of PERL5LIB).
1001 PERL_LIB
1003 Directory containing the Perl library to use.
1004 Used only when MakeMaker is building the extensions of the Perl core
1006 distribution (because normally $(PERL_LIB) is automatically in @INC,
1007 and adding it would get in the way of PERL5LIB).
1008 PERL_MALLOC_OK
1010 defaults to 0. Should be set to TRUE if the extension can work with
1011 the memory allocation routines substituted by the Perl malloc()
1012 subsystem. This should be applicable to most extensions with
1013 exceptions of those
1014 • with bugs in memory allocations which are caught by Perl's
1016 malloc();
1017 • which interact with the memory allocator in other ways than via
1019 malloc(), realloc(), free(), calloc(), sbrk() and brk();
1020 • which rely on special alignment which is not provided by Perl's
1022 malloc().
1023 NOTE. Neglecting to set this flag in any one of the loaded extension
1025 nullifies many advantages of Perl's malloc(), such as better usage of
1026 system resources, error detection, memory usage reporting, catchable
1027 failure of memory allocations, etc.
1028 PERLPREFIX
1030 Directory under which core modules are to be installed.
1031 Defaults to $Config{installprefixexp}, falling back to
1033 $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1034 $Config{installprefixexp} not exist.
1035 Overridden by PREFIX.
1037 PERLRUN
1039 Use this instead of $(PERL) when you wish to run perl. It will set
1040 up extra necessary flags for you.
1041 PERLRUNINST
1043 Use this instead of $(PERL) when you wish to run perl to work with
1044 modules. It will add things like -I$(INST_ARCH) and other necessary
1045 flags so perl can see the modules you're about to install.
1046 PERL_SRC
1048 Directory containing the Perl source code (use of this should be
1049 avoided, it may be undefined)
1050 PERM_DIR
1052 Available in version 6.51_01 and above.
1053 Desired permission for directories. Defaults to 755.
1055 PERM_RW
1057 Desired permission for read/writable files. Defaults to 644.
1058 PERM_RWX
1060 Desired permission for executable files. Defaults to 755.
1061 PL_FILES
1063 MakeMaker can run programs to generate files for you at build time.
1064 By default any file named *.PL (except Makefile.PL and Build.PL) in
1065 the top level directory will be assumed to be a Perl program and run
1066 passing its own basename in as an argument. This basename is
1067 actually a build target, and there is an intention, but not a
1068 requirement, that the *.PL file make the file passed to to as an
1069 argument. For example...
1070 perl foo.PL foo
1072 This behavior can be overridden by supplying your own set of files to
1074 search. PL_FILES accepts a hash ref, the key being the file to run
1075 and the value is passed in as the first argument when the PL file is
1076 run.
1077 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
1079 PL_FILES => {'foo.PL' => 'foo.c'}
1081 Would run bin/foobar.PL like this:
1083 perl bin/foobar.PL bin/foobar
1085 If multiple files from one program are desired an array ref can be
1087 used.
1088 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
1090 In this case the program will be run multiple times using each target
1092 file.
1093 perl bin/foobar.PL bin/foobar1
1095 perl bin/foobar.PL bin/foobar2
1096 If an output file depends on extra input files beside the script
1098 itself, a hash ref can be used in version 7.36 and above:
1099 PL_FILES => { 'foo.PL' => {
1101 'foo.out' => 'foo.in',
1102 'bar.out' => [qw(bar1.in bar2.in)],
1103 }
1104 In this case the extra input files will be passed to the program
1106 after the target file:
1107 perl foo.PL foo.out foo.in
1109 perl foo.PL bar.out bar1.in bar2.in
1110 PL files are normally run after pm_to_blib and include INST_LIB and
1112 INST_ARCH in their @INC, so the just built modules can be accessed...
1113 unless the PL file is making a module (or anything else in PM) in
1114 which case it is run before pm_to_blib and does not include INST_LIB
1115 and INST_ARCH in its @INC. This apparently odd behavior is there for
1116 backwards compatibility (and it's somewhat DWIM). The argument
1117 passed to the .PL is set up as a target to build in the Makefile. In
1118 other sections such as "postamble" you can specify a dependency on
1119 the filename/argument that the .PL is supposed (or will have, now
1120 that that is is a dependency) to generate. Note the file to be
1121 generated will still be generated and the .PL will still run even
1122 without an explicit dependency created by you, since the "all" target
1123 still depends on running all eligible to run.PL files.
1124 PM
1126 Hashref of .pm files and *.pl files to be installed. e.g.
1127 {'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
1129 By default this will include *.pm and *.pl and the files found in the
1131 PMLIBDIRS directories. Defining PM in the Makefile.PL will override
1132 PMLIBDIRS.
1133 PMLIBDIRS
1135 Ref to array of subdirectories containing library files. Defaults to
1136 [ 'lib', $(BASEEXT) ]. The directories will be scanned and any files
1137 they contain will be installed in the corresponding location in the
1138 library. A libscan() method can be used to alter the behaviour.
1139 Defining PM in the Makefile.PL will override PMLIBDIRS.
1140 (Where BASEEXT is the last component of NAME.)
1142 PM_FILTER
1144 A filter program, in the traditional Unix sense (input from stdin,
1145 output to stdout) that is passed on each .pm file during the build
1146 (in the pm_to_blib() phase). It is empty by default, meaning no
1147 filtering is done. You could use:
1148 PM_FILTER => 'perl -ne "print unless /^\\#/"',
1150 to remove all the leading comments on the fly during the build. In
1152 order to be as portable as possible, please consider using a Perl
1153 one-liner rather than Unix (or other) utilities, as above. The # is
1154 escaped for the Makefile, since what is going to be generated will
1155 then be:
1156 PM_FILTER = perl -ne "print unless /^\#/"
1158 Without the \ before the #, we'd have the start of a Makefile
1160 comment, and the macro would be incorrectly defined.
1161 You will almost certainly be better off using the "PL_FILES" system,
1163 instead. See above, or the ExtUtils::MakeMaker::FAQ entry.
1164 POLLUTE
1166 Prior to 5.6 various interpreter variables were available without a
1167 "PL_" prefix, eg. "PL_undef" was available as "undef". As of release
1168 5.6, these are only defined if the POLLUTE flag is enabled:
1169 perl Makefile.PL POLLUTE=1
1171 Please inform the module author if this is necessary to successfully
1173 install a module under 5.6 or later.
1174 PPM_INSTALL_EXEC
1176 Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
1177 perl)
1178 PPM_INSTALL_SCRIPT
1180 Name of the script that gets executed by the Perl Package Manager
1181 after the installation of a package.
1182 PPM_UNINSTALL_EXEC
1184 Available in version 6.8502 and above.
1185 Name of the executable used to run "PPM_UNINSTALL_SCRIPT" below.
1187 (e.g. perl)
1188 PPM_UNINSTALL_SCRIPT
1190 Available in version 6.8502 and above.
1191 Name of the script that gets executed by the Perl Package Manager
1193 before the removal of a package.
1194 PREFIX
1196 This overrides all the default install locations. Man pages,
1197 libraries, scripts, etc... MakeMaker will try to make an educated
1198 guess about where to place things under the new PREFIX based on your
1199 Config defaults. Failing that, it will fall back to a structure
1200 which should be sensible for your platform.
1201 If you specify LIB or any INSTALL* variables they will not be
1203 affected by the PREFIX.
1204 PREREQ_FATAL
1206 Bool. If this parameter is true, failing to have the required modules
1207 (or the right versions thereof) will be fatal. "perl Makefile.PL"
1208 will "die" instead of simply informing the user of the missing
1209 dependencies.
1210 It is extremely rare to have to use "PREREQ_FATAL". Its use by module
1212 authors is strongly discouraged and should never be used lightly.
1213 For dependencies that are required in order to run "Makefile.PL", see
1215 "CONFIGURE_REQUIRES".
1216 Module installation tools have ways of resolving unmet dependencies
1218 but to do that they need a Makefile. Using "PREREQ_FATAL" breaks
1219 this. That's bad.
1220 Assuming you have good test coverage, your tests should fail with
1222 missing dependencies informing the user more strongly that something
1223 is wrong. You can write a t/00compile.t test which will simply check
1224 that your code compiles and stop "make test" prematurely if it
1225 doesn't. See "BAIL_OUT" in Test::More for more details.
1226 PREREQ_PM
1228 A hash of modules that are needed to run your module. The keys are
1229 the module names ie. Test::More, and the minimum version is the
1230 value. If the required version number is 0 any version will do. The
1231 versions given may be a Perl v-string (see version) or a range (see
1232 CPAN::Meta::Requirements).
1233 This will go into the "requires" field of your META.yml and the
1235 "runtime" of the "prereqs" field of your META.json.
1236 PREREQ_PM => {
1238 # Require Test::More at least 0.47
1239 "Test::More" => "0.47",
1240 # Require any version of Acme::Buffy
1242 "Acme::Buffy" => 0,
1243 }
1244 PREREQ_PRINT
1246 Bool. If this parameter is true, the prerequisites will be printed
1247 to stdout and MakeMaker will exit. The output format is an evalable
1248 hash ref.
1249 $PREREQ_PM = {
1251 'A::B' => Vers1,
1252 'C::D' => Vers2,
1253 ...
1254 };
1255 If a distribution defines a minimal required perl version, this is
1257 added to the output as an additional line of the form:
1258 $MIN_PERL_VERSION = '5.008001';
1260 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1262 hashref.
1263 PRINT_PREREQ
1265 RedHatism for "PREREQ_PRINT". The output format is different,
1266 though:
1267 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1269 A minimal required perl version, if present, will look like this:
1271 perl(perl)>=5.008001
1273 SITEPREFIX
1275 Like PERLPREFIX, but only for the site install locations.
1276 Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
1278 an explicit siteprefix in the Config. In those cases
1279 $Config{installprefix} will be used.
1280 Overridable by PREFIX
1282 SIGN
1284 Available in version 6.18 and above.
1285 When true, perform the generation and addition to the MANIFEST of the
1287 SIGNATURE file in the distdir during 'make distdir', via 'cpansign
1288 -s'.
1289 Note that you need to install the Module::Signature module to perform
1291 this operation.
1292 Defaults to false.
1294 SKIP
1296 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1297 Makefile. Caution! Do not use the SKIP attribute for the negligible
1298 speedup. It may seriously damage the resulting Makefile. Only use it
1299 if you really need it.
1300 TEST_REQUIRES
1302 Available in version 6.64 and above.
1303 A hash of modules that are needed to test your module but not run or
1305 build it.
1306 This will go into the "build_requires" field of your META.yml and the
1308 "test" of the "prereqs" field of your META.json.
1309 The format is the same as PREREQ_PM.
1311 TYPEMAPS
1313 Ref to array of typemap file names. Use this when the typemaps are
1314 in some directory other than the current directory or when they are
1315 not named typemap. The last typemap in the list takes precedence. A
1316 typemap in the current directory has highest precedence, even if it
1317 isn't listed in TYPEMAPS. The default system typemap has lowest
1318 precedence.
1319 USE_MM_LD_RUN_PATH
1321 boolean The Fedora perl MakeMaker distribution differs from the
1322 standard upstream release in that it disables use of the MakeMaker
1323 generated LD_RUN_PATH by default, UNLESS this attribute is specified
1324 , or the USE_MM_LD_RUN_PATH environment variable is set during the
1325 MakeMaker run.
1326 The upstream MakeMaker will set the ld(1) environment variable
1328 LD_RUN_PATH to the concatenation of every -L ld(1) option directory
1329 in which a -l ld(1) option library is found, which is used as the
1330 ld(1) -rpath option if none is specified. This means that, if your
1331 application builds shared libraries and your MakeMaker application
1332 links to them, that the absolute paths of the libraries in the build
1333 tree will be inserted into the RPATH header of all MakeMaker
1334 generated binaries, and that such binaries will be unable to link to
1335 these libraries if they do not still reside in the build tree
1336 directories (unlikely) or in the system library directories (/lib or
1337 /usr/lib), regardless of any LD_LIBRARY_PATH setting. So if you
1338 specified -L../mylib -lmylib , and
1339 your 'libmylib.so' gets installed into
1340 /some_directory_other_than_usr_lib,
1341 your MakeMaker application will be unable to link to it, even if
1342 LD_LIBRARY_PATH is set to include /some_directory_other_than_usr_lib,
1343 because RPATH overrides LD_LIBRARY_PATH.
1344 So for Fedora MakeMaker builds LD_RUN_PATH is NOT generated by
1346 default for every link. You can still use explicit -rpath ld options
1347 or the LD_RUN_PATH environment variable during the build to generate
1348 an RPATH for the binaries.
1349 You can set the USE_MM_LD_RUN_PATH attribute to 1 on the MakeMaker
1351 command line or in the WriteMakefile arguments to enable generation
1352 of LD_RUN_PATH for every link command.
1353 USE_MM_LD_RUN_PATH will default to 1 (LD_RUN_PATH will be used) IF
1355 the $USE_MM_LD_RUN_PATH environment variable is set during a
1356 MakeMaker run.
1357 VENDORPREFIX
1359 Like PERLPREFIX, but only for the vendor install locations.
1360 Defaults to $Config{vendorprefixexp}.
1362 Overridable by PREFIX
1364 VERBINST
1366 If true, make install will be verbose
1367 VERSION
1369 Your version number for distributing the package. This defaults to
1370 0.1.
1371 VERSION_FROM
1373 Instead of specifying the VERSION in the Makefile.PL you can let
1374 MakeMaker parse a file to determine the version number. The parsing
1375 routine requires that the file named by VERSION_FROM contains one
1376 single line to compute the version number. The first line in the file
1377 that contains something like a $VERSION assignment or "package Name
1378 VERSION" will be used. The following lines will be parsed o.k.:
1379 # Good
1381 package Foo::Bar 1.23; # 1.23
1382 $VERSION = '1.00'; # 1.00
1383 *VERSION = \'1.01'; # 1.01
1384 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
1385 $FOO::VERSION = '1.10'; # 1.10
1386 *FOO::VERSION = \'1.11'; # 1.11
1387 but these will fail:
1389 # Bad
1391 my $VERSION = '1.01';
1392 local $VERSION = '1.02';
1393 local $FOO::VERSION = '1.30';
1394 (Putting "my" or "local" on the preceding line will work o.k.)
1396 "Version strings" are incompatible and should not be used.
1398 # Bad
1400 $VERSION = 1.2.3;
1401 $VERSION = v1.2.3;
1402 version objects are fine. As of MakeMaker 6.35 version.pm will be
1404 automatically loaded, but you must declare the dependency on
1405 version.pm. For compatibility with older MakeMaker you should load
1406 on the same line as $VERSION is declared.
1407 # All on one line
1409 use version; our $VERSION = qv(1.2.3);
1410 The file named in VERSION_FROM is not added as a dependency to
1412 Makefile. This is not really correct, but it would be a major pain
1413 during development to have to rewrite the Makefile for any smallish
1414 change in that file. If you want to make sure that the Makefile
1415 contains the correct VERSION macro after any change of the file, you
1416 would have to do something like
1417 depend => { Makefile => '$(VERSION_FROM)' }
1419 See attribute "depend" below.
1421 VERSION_SYM
1423 A sanitized VERSION with . replaced by _. For places where . has
1424 special meaning (some filesystems, RCS labels, etc...)
1425 XS
1427 Hashref of .xs files. MakeMaker will default this. e.g.
1428 {'name_of_file.xs' => 'name_of_file.c'}
1430 The .c files will automatically be included in the list of files
1432 deleted by a make clean.
1433 XSBUILD
1435 Available in version 7.12 and above.
1436 Hashref with options controlling the operation of "XSMULTI":
1438 {
1440 xs => {
1441 all => {
1442 # options applying to all .xs files for this distribution
1443 },
1444 'lib/Class/Name/File' => { # specifically for this file
1445 DEFINE => '-Dfunktastic', # defines for only this file
1446 INC => "-I$funkyliblocation", # include flags for only this file
1447 # OBJECT => 'lib/Class/Name/File$(OBJ_EXT)', # default
1448 LDFROM => "lib/Class/Name/File\$(OBJ_EXT) $otherfile\$(OBJ_EXT)", # what's linked
1449 },
1450 },
1451 }
1452 Note "xs" is the file-extension. More possibilities may arise in the
1454 future. Note that object names are specified without their XS
1455 extension.
1456 "LDFROM" defaults to the same as "OBJECT". "OBJECT" defaults to, for
1458 "XSMULTI", just the XS filename with the extension replaced with the
1459 compiler-specific object-file extension.
1460 The distinction between "OBJECT" and "LDFROM": "OBJECT" is the make
1462 target, so make will try to build it. However, "LDFROM" is what will
1463 actually be linked together to make the shared object or static
1464 library (SO/SL), so if you override it, make sure it includes what
1465 you want to make the final SO/SL, almost certainly including the XS
1466 basename with "$(OBJ_EXT)" appended.
1467 XSMULTI
1469 Available in version 7.12 and above.
1470 When this is set to 1, multiple XS files may be placed under lib/
1472 next to their corresponding "*.pm" files (this is essential for
1473 compiling with the correct "VERSION" values). This feature should be
1474 considered experimental, and details of it may change.
1475 This feature was inspired by, and small portions of code copied from,
1477 ExtUtils::MakeMaker::BigHelper. Hopefully this feature will render
1478 that module mainly obsolete.
1479 XSOPT
1481 String of options to pass to xsubpp. This might include "-C++" or
1482 "-extern". Do not include typemaps here; the TYPEMAP parameter
1483 exists for that purpose.
1484 XSPROTOARG
1486 May be set to "-prototypes", "-noprototypes" or the empty string.
1487 The empty string is equivalent to the xsubpp default, or
1488 "-noprototypes". See the xsubpp documentation for details.
1489 MakeMaker defaults to the empty string.
1490 XS_VERSION
1492 Your version number for the .xs file of this package. This defaults
1493 to the value of the VERSION attribute.
1494 Additional lowercase attributes
1496 can be used to pass parameters to the methods which implement that part
1497 of the Makefile. Parameters are specified as a hash ref but are passed
1498 to the method as a hash.
1499 clean
1501 {FILES => "*.xyz foo"}
1502 depend
1504 {ANY_TARGET => ANY_DEPENDENCY, ...}
1505 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1507 dist
1509 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1510 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1511 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1512 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1514 needed to tell make the target file of the compression. Setting
1515 DIST_CP to ln can be useful, if you need to preserve the timestamps
1516 on your files. DIST_CP can take the values 'cp', which copies the
1517 file, 'ln', which links the file, and 'best' which copies symbolic
1518 links and links the rest. Default is 'best'.
1519 dynamic_lib
1521 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1522 linkext
1524 {LINKTYPE => 'static', 'dynamic' or ''}
1525 NB: Extensions that have nothing but *.pm files had to say
1527 {LINKTYPE => ''}
1529 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1531 can be deleted safely. MakeMaker recognizes when there's nothing to
1532 be linked.
1533 macro
1535 {ANY_MACRO => ANY_VALUE, ...}
1536 postamble
1538 Anything put here will be passed to MY::postamble() if you have one.
1539 realclean
1541 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1542 test
1544 Specify the targets for testing.
1545 {TESTS => 't/*.t'}
1547 "RECURSIVE_TEST_FILES" can be used to include all directories
1549 recursively under "t" that contain ".t" files. It will be ignored if
1550 you provide your own "TESTS" attribute, defaults to false.
1551 {RECURSIVE_TEST_FILES=>1}
1553 This is supported since 6.76
1555 tool_autosplit
1557 {MAXLEN => 8}
1558 Overriding MakeMaker Methods
1560 If you cannot achieve the desired Makefile behaviour by specifying
1561 attributes you may define private subroutines in the Makefile.PL. Each
1562 subroutine returns the text it wishes to have written to the Makefile.
1563 To override a section of the Makefile you can either say:
1564 sub MY::c_o { "new literal text" }
1566 or you can edit the default by saying something like:
1568 package MY; # so that "SUPER" works right
1570 sub c_o {
1571 my $inherited = shift->SUPER::c_o(@_);
1572 $inherited =~ s/old text/new text/;
1573 $inherited;
1574 }
1575 If you are running experiments with embedding perl as a library into
1577 other applications, you might find MakeMaker is not sufficient. You'd
1578 better have a look at ExtUtils::Embed which is a collection of
1579 utilities for embedding.
1580 If you still need a different solution, try to develop another
1582 subroutine that fits your needs and submit the diffs to
1583 "makemaker@perl.org"
1584 For a complete description of all MakeMaker methods see
1586 ExtUtils::MM_Unix.
1587 Here is a simple example of how to add a new target to the generated
1589 Makefile:
1590 sub MY::postamble {
1592 return <<'MAKE_FRAG';
1593 $(MYEXTLIB): sdbm/Makefile
1594 cd sdbm && $(MAKE) all
1595 MAKE_FRAG
1597 }
1598 The End Of Cargo Cult Programming
1600 WriteMakefile() now does some basic sanity checks on its parameters to
1601 protect against typos and malformatted values. This means some things
1602 which happened to work in the past will now throw warnings and possibly
1603 produce internal errors.
1604 Some of the most common mistakes:
1606 "MAN3PODS => ' '"
1608 This is commonly used to suppress the creation of man pages.
1609 MAN3PODS takes a hash ref not a string, but the above worked by
1610 accident in old versions of MakeMaker.
1611 The correct code is "MAN3PODS => { }".
1613 Hintsfile support
1615 MakeMaker.pm uses the architecture-specific information from Config.pm.
1616 In addition it evaluates architecture specific hints files in a
1617 "hints/" directory. The hints files are expected to be named like their
1618 counterparts in "PERL_SRC/hints", but with an ".pl" file name extension
1619 (eg. "next_3_2.pl"). They are simply "eval"ed by MakeMaker within the
1620 WriteMakefile() subroutine, and can be used to execute commands as well
1621 as to include special variables. The rules which hintsfile is chosen
1622 are the same as in Configure.
1623 The hintsfile is eval()ed immediately after the arguments given to
1625 WriteMakefile are stuffed into a hash reference $self but before this
1626 reference becomes blessed. So if you want to do the equivalent to
1627 override or create an attribute you would say something like
1628 $self->{LIBS} = ['-ldbm -lucb -lc'];
1630 Distribution Support
1632 For authors of extensions MakeMaker provides several Makefile targets.
1633 Most of the support comes from the ExtUtils::Manifest module, where
1634 additional documentation can be found.
1635 make distcheck
1637 reports which files are below the build directory but not in the
1638 MANIFEST file and vice versa. (See "fullcheck" in
1639 ExtUtils::Manifest for details)
1640 make skipcheck
1642 reports which files are skipped due to the entries in the
1643 "MANIFEST.SKIP" file (See "skipcheck" in ExtUtils::Manifest for
1644 details)
1645 make distclean
1647 does a realclean first and then the distcheck. Note that this is
1648 not needed to build a new distribution as long as you are sure that
1649 the MANIFEST file is ok.
1650 make veryclean
1652 does a realclean first and then removes backup files such as "*~",
1653 "*.bak", "*.old" and "*.orig"
1654 make manifest
1656 rewrites the MANIFEST file, adding all remaining files found (See
1657 "mkmanifest" in ExtUtils::Manifest for details)
1658 make distdir
1660 Copies all the files that are in the MANIFEST file to a newly
1661 created directory with the name "$(DISTNAME)-$(VERSION)". If that
1662 directory exists, it will be removed first.
1663 Additionally, it will create META.yml and META.json module meta-
1665 data file in the distdir and add this to the distdir's MANIFEST.
1666 You can shut this behavior off with the NO_META flag.
1667 make disttest
1669 Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1670 make test in that directory.
1671 make tardist
1673 First does a distdir. Then a command $(PREOP) which defaults to a
1674 null command, followed by $(TO_UNIX), which defaults to a null
1675 command under UNIX, and will convert files in distribution
1676 directory to UNIX format otherwise. Next it runs "tar" on that
1677 directory into a tarfile and deletes the directory. Finishes with a
1678 command $(POSTOP) which defaults to a null command.
1679 make dist
1681 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1682 make uutardist
1684 Runs a tardist first and uuencodes the tarfile.
1685 make shdist
1687 First does a distdir. Then a command $(PREOP) which defaults to a
1688 null command. Next it runs "shar" on that directory into a sharfile
1689 and deletes the intermediate directory again. Finishes with a
1690 command $(POSTOP) which defaults to a null command. Note: For
1691 shdist to work properly a "shar" program that can handle
1692 directories is mandatory.
1693 make zipdist
1695 First does a distdir. Then a command $(PREOP) which defaults to a
1696 null command. Runs "$(ZIP) $(ZIPFLAGS)" on that directory into a
1697 zipfile. Then deletes that directory. Finishes with a command
1698 $(POSTOP) which defaults to a null command.
1699 make ci
1701 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1702 Customization of the dist targets can be done by specifying a hash
1704 reference to the dist attribute of the WriteMakefile call. The
1705 following parameters are recognized:
1706 CI ('ci -u')
1708 COMPRESS ('gzip --best')
1709 POSTOP ('@ :')
1710 PREOP ('@ :')
1711 TO_UNIX (depends on the system)
1712 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1713 SHAR ('shar')
1714 SUFFIX ('.gz')
1715 TAR ('tar')
1716 TARFLAGS ('cvf')
1717 ZIP ('zip')
1718 ZIPFLAGS ('-r')
1719 An example:
1721 WriteMakefile(
1723 ...other options...
1724 dist => {
1725 COMPRESS => "bzip2",
1726 SUFFIX => ".bz2"
1727 }
1728 );
1729 Module Meta-Data (META and MYMETA)
1731 Long plaguing users of MakeMaker based modules has been the problem of
1732 getting basic information about the module out of the sources without
1733 running the Makefile.PL and doing a bunch of messy heuristics on the
1734 resulting Makefile. Over the years, it has become standard to keep
1735 this information in one or more CPAN Meta files distributed with each
1736 distribution.
1737 The original format of CPAN Meta files was YAML and the corresponding
1739 file was called META.yml. In 2010, version 2 of the CPAN::Meta::Spec
1740 was released, which mandates JSON format for the metadata in order to
1741 overcome certain compatibility issues between YAML serializers and to
1742 avoid breaking older clients unable to handle a new version of the
1743 spec. The CPAN::Meta library is now standard for accessing old and
1744 new-style Meta files.
1745 If CPAN::Meta is installed, MakeMaker will automatically generate
1747 META.json and META.yml files for you and add them to your MANIFEST as
1748 part of the 'distdir' target (and thus the 'dist' target). This is
1749 intended to seamlessly and rapidly populate CPAN with module meta-data.
1750 If you wish to shut this feature off, set the "NO_META" WriteMakefile()
1751 flag to true.
1752 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers
1754 agreed to use the CPAN Meta format to communicate post-configuration
1755 requirements between toolchain components. These files, MYMETA.json
1756 and MYMETA.yml, are generated when Makefile.PL generates a Makefile (if
1757 CPAN::Meta is installed). Clients like CPAN or CPANPLUS will read
1758 these files to see what prerequisites must be fulfilled before building
1759 or testing the distribution. If you wish to shut this feature off, set
1760 the "NO_MYMETA" WriteMakefile() flag to true.
1761 Disabling an extension
1763 If some events detected in Makefile.PL imply that there is no way to
1764 create the Module, but this is a normal state of things, then you can
1765 create a Makefile which does nothing, but succeeds on all the "usual"
1766 build targets. To do so, use
1767 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1769 WriteEmptyMakefile();
1770 instead of WriteMakefile().
1772 This may be useful if other modules expect this module to be built OK,
1774 as opposed to work OK (say, this system-dependent module builds in a
1775 subdirectory of some other distribution, or is listed as a dependency
1776 in a CPAN::Bundle, but the functionality is supported by different
1777 means on the current architecture).
1778 Other Handy Functions
1780 prompt
1781 my $value = prompt($message);
1782 my $value = prompt($message, $default);
1783 The prompt() function provides an easy way to request user input
1785 used to write a makefile. It displays the $message as a prompt for
1786 input. If a $default is provided it will be used as a default.
1787 The function returns the $value selected by the user.
1788 If prompt() detects that it is not running interactively and there
1790 is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1791 variable is set to true, the $default will be used without
1792 prompting. This prevents automated processes from blocking on user
1793 input.
1794 If no $default is provided an empty string will be used instead.
1796 os_unsupported
1798 os_unsupported();
1799 os_unsupported if $^O eq 'MSWin32';
1800 The os_unsupported() function provides a way to correctly exit your
1802 "Makefile.PL" before calling "WriteMakefile". It is essentially a
1803 "die" with the message "OS unsupported".
1804 This is supported since 7.26
1806 Supported versions of Perl
1808 Please note that while this module works on Perl 5.6, it is no longer
1809 being routinely tested on 5.6 - the earliest Perl version being
1810 routinely tested, and expressly supported, is 5.8.1. However, patches
1811 to repair any breakage on 5.6 are still being accepted.
1812
1814 PERL_MM_OPT
1815 Command line options used by "MakeMaker->new()", and thus by
1816 WriteMakefile(). The string is split as the shell would, and the
1817 result is processed before any actual command line arguments are
1818 processed.
1819 PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1821 PERL_MM_USE_DEFAULT
1823 If set to a true value then MakeMaker's prompt function will always
1824 return the default without waiting for user input.
1825 PERL_CORE
1827 Same as the PERL_CORE parameter. The parameter overrides this.
1828
1830 Module::Build is a pure-Perl alternative to MakeMaker which does not
1831 rely on make or any other external utility. It may be easier to extend
1832 to suit your needs.
1833 Module::Build::Tiny is a minimal pure-Perl alternative to MakeMaker
1835 that follows the Build.PL protocol of Module::Build but without its
1836 complexity and cruft, implementing only the installation of the module
1837 and leaving authoring to mbtiny or other authoring tools.
1838 Module::Install is a (now discouraged) wrapper around MakeMaker which
1840 adds features not normally available.
1841 ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1843 setup your distribution.
1844 CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1846 File::ShareDir::Install makes it easy to install static, sometimes also
1848 referred to as 'shared' files. File::ShareDir helps accessing the
1849 shared files after installation. Test::File::ShareDir helps when
1850 writing tests to use the shared files both before and after
1851 installation.
1852 Dist::Zilla is an authoring tool which allows great customization and
1854 extensibility of the author experience, relying on the existing install
1855 tools like ExtUtils::MakeMaker only for installation.
1856 Dist::Milla is a Dist::Zilla bundle that greatly simplifies common
1858 usage.
1859 Minilla is a minimal authoring tool that does the same things as
1861 Dist::Milla without the overhead of Dist::Zilla.
1862
1864 Andy Dougherty "doughera@lafayette.edu", Andreas König
1865 "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org". VMS support by
1866 Charles Bailey "bailey@newman.upenn.edu". OS/2 support by Ilya
1867 Zakharevich "ilya@math.ohio-state.edu".
1868 Currently maintained by Michael G Schwern "schwern@pobox.com"
1870 Send patches and ideas to "makemaker@perl.org".
1872 Send bug reports via http://rt.cpan.org/. Please send your generated
1874 Makefile along with your report.
1875 For more up-to-date information, see
1877 <https://metacpan.org/release/ExtUtils-MakeMaker>.
1878 Repository available at
1880 <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1881
1883 This program is free software; you can redistribute it and/or modify it
1884 under the same terms as Perl itself.
1885 See <http://www.perl.com/perl/misc/Artistic.html>
1887perl v5.36.0 2023-03-27 ExtUtils::MakeMaker(3)