1ExtUtils::MakeMaker(3)User Contributed Perl DocumentationExtUtils::MakeMaker(3)
2
3
4

NAME

6       ExtUtils::MakeMaker - Create a module Makefile
7

SYNOPSIS

9         use ExtUtils::MakeMaker;
10
11         WriteMakefile(
12             NAME              => "Foo::Bar",
13             VERSION_FROM      => "lib/Foo/Bar.pm",
14         );
15

DESCRIPTION

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
21       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
25       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
32       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
36       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
41       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
47       See ExtUtils::MakeMaker::FAQ for details of the design and usage.
48
49   How To Write A Makefile.PL
50       See ExtUtils::MakeMaker::Tutorial.
51
52       The long answer is the rest of the manpage :-)
53
54   Default Makefile Behaviour
55       The generated Makefile enables the user of the extension to invoke
56
57         perl Makefile.PL # optionally "perl Makefile.PL verbose"
58         make
59         make test        # optionally set TEST_VERBOSE=1
60         make install     # See below
61
62       The Makefile to be produced may be altered by adding arguments of the
63       form "KEY=VALUE". E.g.
64
65         perl Makefile.PL INSTALL_BASE=~
66
67       Other interesting targets in the generated Makefile are
68
69         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
75   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
80       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
84       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
88           t/foo
89           t/foo/bar
90
91       You could tell make to run tests in both of those directories with the
92       following directives:
93
94           test => {TESTS => 't/*/*.t t/*/*/*.t'}
95           test => {TESTS => 't/foo/*.t t/foo/bar/*.t'}
96
97       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
101       If you'd like to see the raw output of your tests, set the
102       "TEST_VERBOSE" variable to true.
103
104         make test TEST_VERBOSE=1
105
106       If you want to run particular test files, set the "TEST_FILES"
107       variable.  It is possible to use globbing with this mechanism.
108
109         make test TEST_FILES='t/foobar.t t/dagobah*.t'
110
111       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
115         nmake test TEST_FILES='t\foobar.t t\dagobah*.t'
116
117   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
122       If you want to debug some other testfile, set the "TEST_FILE" variable
123       thusly:
124
125         make testdb TEST_FILE=t/mytest.t
126
127       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
130         make testdb TESTDB_SW=-Dx
131
132   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
140       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
145                                        INSTALLDIRS set to
146                                  perl        site          vendor
147
148                        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
156       The INSTALL... macros in turn default to their %Config
157       ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
158
159       You can check the values of these variables on your system with
160
161           perl '-V:install.*'
162
163       And to check the sequence in which the library directories are searched
164       by perl, run
165
166           perl -le 'print join $/, @INC'
167
168       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
175           make install UNINST=1
176
177   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
182       To have everything installed in your home directory, do the following.
183
184           # Unix users, INSTALL_BASE=~ works fine
185           perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
186
187       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
191           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
198       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
203       INSTALL_BASE was added in 6.31.
204
205   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
209           # Unix users, PREFIX=~ works fine
210           perl Makefile.PL PREFIX=/path/to/your/home/dir
211
212       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
219       Another way to specify many INSTALL directories with a single parameter
220       is LIB.
221
222           perl Makefile.PL LIB=~/lib
223
224       This will install the module's architecture-independent files into
225       ~/lib, the architecture-dependent files into ~/lib/$archname.
226
227       Note, that in both cases the tilde expansion is done by MakeMaker, not
228       by perl by default, nor by make.
229
230       Conflicts between parameters LIB, PREFIX and the various INSTALL*
231       arguments are resolved so that:
232
233       •   setting LIB overrides any setting of INSTALLPRIVLIB,
234           INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not
235           affected by PREFIX);
236
237       •   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
241       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
246           perl Makefile.PL;
247           make;
248           make test
249           make install
250
251       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
255   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
260           perl Makefile.PL INSTALLSITELIB=/afs/here/today \
261               INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
262           make
263
264       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
268   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
276           make perl
277
278       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
286       The binary can be installed into the directory where perl normally
287       resides on your machine with
288
289           make inst_perl
290
291       To produce a perl binary with a different name than "perl", either say
292
293           perl Makefile.PL MAP_TARGET=myperl
294           make myperl
295           make inst_perl
296
297       or say
298
299           perl Makefile.PL
300           make myperl MAP_TARGET=myperl
301           make inst_perl MAP_TARGET=myperl
302
303       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
306       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
310       Warning: the inst_perl: target will most probably overwrite your
311       existing perl binary. Use with care!
312
313       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
317           perl Makefile.PL LINKTYPE=static    # recommended
318
319       or
320
321           make LINKTYPE=static                # works on most systems
322
323   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
329       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
337       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
342         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
348       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
352         PERL_INC     = $archlibexp/CORE
353         PERL_LIB     = $privlibexp
354         PERL_ARCHLIB = $archlibexp
355         INST_LIB     = ./blib/lib
356         INST_ARCHLIB = ./blib/arch
357
358       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
361   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
372       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
379   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
384       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
388       ABSTRACT
389         One line description of the module. Will be included in PPD file.
390
391       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
397       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
402       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
407                 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
408
409         builds a PPD package that references a binary of the "Agent" package,
410         located in the "x86" directory relative to the PPD itself.
411
412       BUILD_REQUIRES
413         Available in version 6.55_03 and above.
414
415         A hash of modules that are needed to build your module but not run
416         it.
417
418         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
421         Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
422         specified.
423
424         The format is the same as PREREQ_PM.
425
426       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
430       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
436             CCFLAGS => "$Config::Config{ccflags} ..."
437
438       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
444       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
449       CONFIGURE_REQUIRES
450         Available in version 6.52 and above.
451
452         A hash of modules that are required to run Makefile.PL itself, but
453         not to run your distribution.
454
455         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
458         Defaults to "{ "ExtUtils::MakeMaker" => 0 }" if this attribute is not
459         specified.
460
461         The format is the same as PREREQ_PM.
462
463       DEFINE
464         Something like "-DHAVE_UNISTD_H"
465
466       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
473         This is primarily of use for people who repackage Perl modules.
474
475         NOTE: Due to the nature of make, it is important that you put the
476         trailing slash on your DESTDIR.  ~/tmp/ not ~/tmp.
477
478       DIR
479         Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
480         in ext/SDBM_File
481
482       DISTNAME
483         A safe filename for the package.
484
485         Defaults to NAME below but with :: replaced with -.
486
487         For example, Foo::Bar becomes Foo-Bar.
488
489       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
494         Defaults to DISTNAME-VERSION.
495
496         For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
497
498         On some OS's where . has special meaning VERSION_SYM may be used in
499         place of VERSION.
500
501       DLEXT
502         Specifies the extension of the module's loadable object. For example:
503
504           DLEXT => 'unusual_ext', # Default value is $Config{so}
505
506         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
510           local $DynaLoader::dl_dlext = 'unusual_ext';
511
512       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
520           {"$(NAME)" => ["boot_$(NAME)" ] }
521
522         e.g.
523
524           {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
525            "NetconfigPtr" => [ 'DESTROY'] }
526
527         Please see the ExtUtils::Mksymlists documentation for more
528         information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
529
530       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
535       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
540         This attribute may be most useful when specified as a string on the
541         command line:  perl Makefile.PL EXCLUDE_EXT='Socket Safe'
542
543       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
548         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
553       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
557         Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
558
559         (Note: we couldn't use MAKEFILE because dmake uses this for something
560         else).
561
562       FULLPERL
563         Perl binary able to run this extension, load XS modules, etc...
564
565       FULLPERLRUN
566         Like PERLRUN, except it uses FULLPERL.
567
568       FULLPERLRUNINST
569         Like PERLRUNINST, except it uses FULLPERL.
570
571       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
577       H Ref to array of *.h file names. Similar to C.
578
579       IMPORTS
580         This attribute is used to specify names to be imported into the
581         extension. Takes a hash ref.
582
583         It is only used on OS/2 and Win32.
584
585       INC
586         Include file dirs eg: "-I/usr/5include -I/path/to/inc"
587
588       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
596         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
601         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
605       INSTALLARCHLIB
606         Used by 'make install', which copies files from INST_ARCHLIB to this
607         directory if INSTALLDIRS is set to perl.
608
609       INSTALLBIN
610         Directory to install binary files (e.g. tkperl) into if
611         INSTALLDIRS=perl.
612
613       INSTALLDIRS
614         Determines which of the sets of installation directories to choose:
615         perl, site or vendor.  Defaults to site.
616
617       INSTALLMAN1DIR
618       INSTALLMAN3DIR
619         These directories get the man pages at 'make install' time if
620         INSTALLDIRS=perl.  Defaults to $Config{installman*dir}.
621
622         If set to 'none', no man pages will be installed.
623
624       INSTALLPRIVLIB
625         Used by 'make install', which copies files from INST_LIB to this
626         directory if INSTALLDIRS is set to perl.
627
628         Defaults to $Config{installprivlib}.
629
630       INSTALLSCRIPT
631         Available in version 6.30_02 and above.
632
633         Used by 'make install' which copies files from INST_SCRIPT to this
634         directory if INSTALLDIRS=perl.
635
636       INSTALLSITEARCH
637         Used by 'make install', which copies files from INST_ARCHLIB to this
638         directory if INSTALLDIRS is set to site (default).
639
640       INSTALLSITEBIN
641         Used by 'make install', which copies files from INST_BIN to this
642         directory if INSTALLDIRS is set to site (default).
643
644       INSTALLSITELIB
645         Used by 'make install', which copies files from INST_LIB to this
646         directory if INSTALLDIRS is set to site (default).
647
648       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
654         If set to 'none', no man pages will be installed.
655
656       INSTALLSITESCRIPT
657         Used by 'make install' which copies files from INST_SCRIPT to this
658         directory if INSTALLDIRS is set to site (default).
659
660       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
666       INSTALLVENDORBIN
667         Used by 'make install', which copies files from INST_BIN to this
668         directory if INSTALLDIRS is set to vendor.
669
670       INSTALLVENDORLIB
671         Used by 'make install', which copies files from INST_LIB to this
672         directory if INSTALLDIRS is set to vendor.
673
674       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
679         If set to 'none', no man pages will be installed.
680
681       INSTALLVENDORSCRIPT
682         Available in version 6.30_02 and above.
683
684         Used by 'make install' which copies files from INST_SCRIPT to this
685         directory if INSTALLDIRS is set to vendor.
686
687       INST_ARCHLIB
688         Same as INST_LIB for architecture dependent files.
689
690       INST_BIN
691         Directory to put real binary files during 'make'. These will be
692         copied to INSTALLBIN during 'make install'
693
694       INST_LIB
695         Directory where we put library files of this extension while building
696         it.
697
698       INST_MAN1DIR
699         Directory to hold the man pages at 'make' time
700
701       INST_MAN3DIR
702         Directory to hold the man pages at 'make' time
703
704       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
710       LD
711         Program to be used to link libraries for dynamic loading.
712
713         Defaults to $Config{ld}.
714
715       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
720         Defaults to $Config{lddlflags}.
721
722       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
727       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
734       LIBPERL_A
735         The filename of the perllibrary that will be used together with this
736         extension. Defaults to libperl.a.
737
738       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
742           'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
743
744         Mind, that any element of the array contains a complete set of
745         arguments for the ld command. So do not specify
746
747           'LIBS' => ["-ltcl", "-ltk", "-lX11"]
748
749         See ODBM_File/Makefile.PL for an example, where an array is needed.
750         If you specify a scalar as in
751
752           'LIBS' => "-ltcl -ltk -lX11"
753
754         MakeMaker will turn it into an array with one element.
755
756       LICENSE
757         Available in version 6.31 and above.
758
759         The licensing terms of your distribution.  Generally it's "perl_5"
760         for the same license as Perl itself.
761
762         See CPAN::Meta::Spec for the list of options.
763
764         Defaults to "unknown".
765
766       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
770       MAGICXS
771         Available in version 6.8305 and above.
772
773         When this is set to 1, "OBJECT" will be automagically derived from
774         "O_FILES".
775
776       MAKE
777         Available in version 6.30_01 and above.
778
779         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
783         MakeMaker also honors the MAKE environment variable.  This parameter
784         takes precedence.
785
786         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
791         Defaults to $Config{make}, which may go looking for a Make program in
792         your environment.
793
794         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
800       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
805       MAKEFILE_OLD
806         When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
807         backed up at this location.
808
809         Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
810
811       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
817         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
821           MAN1PODS            => {
822             'doc/command.pod'    => 'blib/man1/command.1',
823             'scripts/script.pl'  => 'blib/man1/script.1',
824           }
825
826       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
833         Example similar to MAN1PODS.
834
835       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
839       META_ADD
840       META_MERGE
841         Available in version 6.46 and above.
842
843         A hashref of items to add to the CPAN Meta file (META.yml or
844         META.json).
845
846         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
850         Unless you want to override the defaults, prefer META_MERGE so as to
851         get the advantage of any future defaults.
852
853         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
862         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
867         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
871           META_MERGE        => {
872
873             "meta-spec" => { version => 2 },
874
875             resources => {
876
877               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
883             },
884
885           },
886
887       MIN_PERL_VERSION
888         Available in version 6.48 and above.
889
890         The minimum required version of Perl for this distribution.
891
892         Either the 5.006001 or the 5.6.1 format is acceptable.
893
894       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
898       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
905         "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
910         Your distribution must have a "NAME".
911
912       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
918       NOECHO
919         Command so make does not print the literal commands it's running.
920
921         By setting it to an empty string you can generate a Makefile that
922         prints all commands. Mainly used in debugging MakeMaker itself.
923
924         Defaults to "@".
925
926       NORECURS
927         Boolean.  Attribute to inhibit descending into subdirectories.
928
929       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
934         Defaults to false.
935
936       NO_MYMETA
937         Available in version 6.57_02 and above.
938
939         When true, suppresses the generation of MYMETA.yml and MYMETA.json
940         module meta-data files during 'perl Makefile.PL'.
941
942         Defaults to false.
943
944       NO_PACKLIST
945         Available in version 6.7501 and above.
946
947         When true, suppresses the writing of "packlist" files for installs.
948
949         Defaults to false.
950
951       NO_PERLLOCAL
952         Available in version 6.7501 and above.
953
954         When true, suppresses the appending of installations to "perllocal".
955
956         Defaults to false.
957
958       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
964       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
970         (Where BASEEXT is the last component of NAME, and OBJ_EXT is
971         $Config{obj_ext}.)
972
973       OPTIMIZE
974         Defaults to "-O". Set it to "-g" to turn debugging on. The flag is
975         passed to subdirectory makes.
976
977       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
983           # 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
987       PERL_CORE
988         Set only when MakeMaker is building the extensions of the Perl core
989         distribution.
990
991       PERLMAINCC
992         The call to the program that is able to compile perlmain.c. Defaults
993         to $(CC).
994
995       PERL_ARCHLIB
996         Same as for PERL_LIB, but for architecture dependent files.
997
998         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
1002       PERL_LIB
1003         Directory containing the Perl library to use.
1004
1005         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
1009       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
1015         •   with bugs in memory allocations which are caught by Perl's
1016             malloc();
1017
1018         •   which interact with the memory allocator in other ways than via
1019             malloc(), realloc(), free(), calloc(), sbrk() and brk();
1020
1021         •   which rely on special alignment which is not provided by Perl's
1022             malloc().
1023
1024         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
1029       PERLPREFIX
1030         Directory under which core modules are to be installed.
1031
1032         Defaults to $Config{installprefixexp}, falling back to
1033         $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1034         $Config{installprefixexp} not exist.
1035
1036         Overridden by PREFIX.
1037
1038       PERLRUN
1039         Use this instead of $(PERL) when you wish to run perl.  It will set
1040         up extra necessary flags for you.
1041
1042       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
1047       PERL_SRC
1048         Directory containing the Perl source code (use of this should be
1049         avoided, it may be undefined)
1050
1051       PERM_DIR
1052         Available in version 6.51_01 and above.
1053
1054         Desired permission for directories. Defaults to 755.
1055
1056       PERM_RW
1057         Desired permission for read/writable files. Defaults to 644.
1058
1059       PERM_RWX
1060         Desired permission for executable files. Defaults to 755.
1061
1062       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
1071             perl foo.PL foo
1072
1073         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
1078             PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
1079
1080             PL_FILES => {'foo.PL' => 'foo.c'}
1081
1082         Would run bin/foobar.PL like this:
1083
1084             perl bin/foobar.PL bin/foobar
1085
1086         If multiple files from one program are desired an array ref can be
1087         used.
1088
1089             PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
1090
1091         In this case the program will be run multiple times using each target
1092         file.
1093
1094             perl bin/foobar.PL bin/foobar1
1095             perl bin/foobar.PL bin/foobar2
1096
1097         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
1100             PL_FILES => { 'foo.PL' => {
1101                 'foo.out' => 'foo.in',
1102                 'bar.out' => [qw(bar1.in bar2.in)],
1103             }
1104
1105         In this case the extra input files will be passed to the program
1106         after the target file:
1107
1108            perl foo.PL foo.out foo.in
1109            perl foo.PL bar.out bar1.in bar2.in
1110
1111         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
1125       PM
1126         Hashref of .pm files and *.pl files to be installed.  e.g.
1127
1128           {'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
1129
1130         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
1134       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
1141         (Where BASEEXT is the last component of NAME.)
1142
1143       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
1149           PM_FILTER => 'perl -ne "print unless /^\\#/"',
1150
1151         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
1157           PM_FILTER = perl -ne "print unless /^\#/"
1158
1159         Without the \ before the #, we'd have the start of a Makefile
1160         comment, and the macro would be incorrectly defined.
1161
1162         You will almost certainly be better off using the "PL_FILES" system,
1163         instead. See above, or the ExtUtils::MakeMaker::FAQ entry.
1164
1165       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
1170           perl Makefile.PL POLLUTE=1
1171
1172         Please inform the module author if this is necessary to successfully
1173         install a module under 5.6 or later.
1174
1175       PPM_INSTALL_EXEC
1176         Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
1177         perl)
1178
1179       PPM_INSTALL_SCRIPT
1180         Name of the script that gets executed by the Perl Package Manager
1181         after the installation of a package.
1182
1183       PPM_UNINSTALL_EXEC
1184         Available in version 6.8502 and above.
1185
1186         Name of the executable used to run "PPM_UNINSTALL_SCRIPT" below.
1187         (e.g. perl)
1188
1189       PPM_UNINSTALL_SCRIPT
1190         Available in version 6.8502 and above.
1191
1192         Name of the script that gets executed by the Perl Package Manager
1193         before the removal of a package.
1194
1195       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
1202         If you specify LIB or any INSTALL* variables they will not be
1203         affected by the PREFIX.
1204
1205       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
1211         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
1214         For dependencies that are required in order to run "Makefile.PL", see
1215         "CONFIGURE_REQUIRES".
1216
1217         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
1221         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
1227       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
1234         This will go into the "requires" field of your META.yml and the
1235         "runtime" of the "prereqs" field of your META.json.
1236
1237             PREREQ_PM => {
1238                 # Require Test::More at least 0.47
1239                 "Test::More" => "0.47",
1240
1241                 # Require any version of Acme::Buffy
1242                 "Acme::Buffy" => 0,
1243             }
1244
1245       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
1250           $PREREQ_PM = {
1251                          'A::B' => Vers1,
1252                          'C::D' => Vers2,
1253                          ...
1254                        };
1255
1256         If a distribution defines a minimal required perl version, this is
1257         added to the output as an additional line of the form:
1258
1259           $MIN_PERL_VERSION = '5.008001';
1260
1261         If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1262         hashref.
1263
1264       PRINT_PREREQ
1265         RedHatism for "PREREQ_PRINT".  The output format is different,
1266         though:
1267
1268             perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1269
1270         A minimal required perl version, if present, will look like this:
1271
1272             perl(perl)>=5.008001
1273
1274       SITEPREFIX
1275         Like PERLPREFIX, but only for the site install locations.
1276
1277         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
1281         Overridable by PREFIX
1282
1283       SIGN
1284         Available in version 6.18 and above.
1285
1286         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
1290         Note that you need to install the Module::Signature module to perform
1291         this operation.
1292
1293         Defaults to false.
1294
1295       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
1301       TEST_REQUIRES
1302         Available in version 6.64 and above.
1303
1304         A hash of modules that are needed to test your module but not run or
1305         build it.
1306
1307         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
1310         The format is the same as PREREQ_PM.
1311
1312       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
1320       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
1327         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
1345         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
1350         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
1354         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
1358       VENDORPREFIX
1359         Like PERLPREFIX, but only for the vendor install locations.
1360
1361         Defaults to $Config{vendorprefixexp}.
1362
1363         Overridable by PREFIX
1364
1365       VERBINST
1366         If true, make install will be verbose
1367
1368       VERSION
1369         Your version number for distributing the package.  This defaults to
1370         0.1.
1371
1372       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
1380             # 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
1388         but these will fail:
1389
1390             # Bad
1391             my $VERSION         = '1.01';
1392             local $VERSION      = '1.02';
1393             local $FOO::VERSION = '1.30';
1394
1395         (Putting "my" or "local" on the preceding line will work o.k.)
1396
1397         "Version strings" are incompatible and should not be used.
1398
1399             # Bad
1400             $VERSION = 1.2.3;
1401             $VERSION = v1.2.3;
1402
1403         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
1408             # All on one line
1409             use version; our $VERSION = qv(1.2.3);
1410
1411         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
1418             depend => { Makefile => '$(VERSION_FROM)' }
1419
1420         See attribute "depend" below.
1421
1422       VERSION_SYM
1423         A sanitized VERSION with . replaced by _.  For places where . has
1424         special meaning (some filesystems, RCS labels, etc...)
1425
1426       XS
1427         Hashref of .xs files. MakeMaker will default this.  e.g.
1428
1429           {'name_of_file.xs' => 'name_of_file.c'}
1430
1431         The .c files will automatically be included in the list of files
1432         deleted by a make clean.
1433
1434       XSBUILD
1435         Available in version 7.12 and above.
1436
1437         Hashref with options controlling the operation of "XSMULTI":
1438
1439           {
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
1453         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
1457         "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
1461         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
1468       XSMULTI
1469         Available in version 7.12 and above.
1470
1471         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
1476         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
1480       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
1485       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
1491       XS_VERSION
1492         Your version number for the .xs file of this package.  This defaults
1493         to the value of the VERSION attribute.
1494
1495   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
1500       clean
1501           {FILES => "*.xyz foo"}
1502
1503       depend
1504           {ANY_TARGET => ANY_DEPENDENCY, ...}
1505
1506         (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1507
1508       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
1513         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
1520       dynamic_lib
1521           {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1522
1523       linkext
1524           {LINKTYPE => 'static', 'dynamic' or ''}
1525
1526         NB: Extensions that have nothing but *.pm files had to say
1527
1528           {LINKTYPE => ''}
1529
1530         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
1534       macro
1535           {ANY_MACRO => ANY_VALUE, ...}
1536
1537       postamble
1538         Anything put here will be passed to MY::postamble() if you have one.
1539
1540       realclean
1541           {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1542
1543       test
1544         Specify the targets for testing.
1545
1546           {TESTS => 't/*.t'}
1547
1548         "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
1552           {RECURSIVE_TEST_FILES=>1}
1553
1554         This is supported since 6.76
1555
1556       tool_autosplit
1557           {MAXLEN => 8}
1558
1559   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
1565               sub MY::c_o { "new literal text" }
1566
1567       or you can edit the default by saying something like:
1568
1569               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
1576       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
1581       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
1585       For a complete description of all MakeMaker methods see
1586       ExtUtils::MM_Unix.
1587
1588       Here is a simple example of how to add a new target to the generated
1589       Makefile:
1590
1591           sub MY::postamble {
1592               return <<'MAKE_FRAG';
1593           $(MYEXTLIB): sdbm/Makefile
1594                   cd sdbm && $(MAKE) all
1595
1596           MAKE_FRAG
1597           }
1598
1599   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
1605       Some of the most common mistakes:
1606
1607       "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
1612         The correct code is "MAN3PODS => { }".
1613
1614   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
1624       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
1629           $self->{LIBS} = ['-ldbm -lucb -lc'];
1630
1631   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
1636       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
1641       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
1646       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
1651       make veryclean
1652           does a realclean first and then removes backup files such as "*~",
1653           "*.bak", "*.old" and "*.orig"
1654
1655       make manifest
1656           rewrites the MANIFEST file, adding all remaining files found (See
1657           "mkmanifest" in ExtUtils::Manifest for details)
1658
1659       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
1664           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
1668       make disttest
1669           Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1670           make test in that directory.
1671
1672       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
1680       make dist
1681           Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1682
1683       make uutardist
1684           Runs a tardist first and uuencodes the tarfile.
1685
1686       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
1694       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
1700       make ci
1701           Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1702
1703       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
1707           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
1720       An example:
1721
1722           WriteMakefile(
1723               ...other options...
1724               dist => {
1725                   COMPRESS => "bzip2",
1726                   SUFFIX   => ".bz2"
1727               }
1728           );
1729
1730   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
1738       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
1746       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
1753       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
1762   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
1768           use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1769           WriteEmptyMakefile();
1770
1771       instead of WriteMakefile().
1772
1773       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
1779   Other Handy Functions
1780       prompt
1781               my $value = prompt($message);
1782               my $value = prompt($message, $default);
1783
1784           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
1789           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
1795           If no $default is provided an empty string will be used instead.
1796
1797       os_unsupported
1798             os_unsupported();
1799             os_unsupported if $^O eq 'MSWin32';
1800
1801           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
1805           This is supported since 7.26
1806
1807   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

ENVIRONMENT

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
1820             PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1821
1822       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
1826       PERL_CORE
1827           Same as the PERL_CORE parameter.  The parameter overrides this.
1828

SEE ALSO

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
1834       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
1839       Module::Install is a (now discouraged) wrapper around MakeMaker which
1840       adds features not normally available.
1841
1842       ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1843       setup your distribution.
1844
1845       CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1846
1847       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
1853       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
1857       Dist::Milla is a Dist::Zilla bundle that greatly simplifies common
1858       usage.
1859
1860       Minilla is a minimal authoring tool that does the same things as
1861       Dist::Milla without the overhead of Dist::Zilla.
1862

AUTHORS

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
1869       Currently maintained by Michael G Schwern "schwern@pobox.com"
1870
1871       Send patches and ideas to "makemaker@perl.org".
1872
1873       Send bug reports via http://rt.cpan.org/.  Please send your generated
1874       Makefile along with your report.
1875
1876       For more up-to-date information, see
1877       <https://metacpan.org/release/ExtUtils-MakeMaker>.
1878
1879       Repository available at
1880       <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1881

LICENSE

1883       This program is free software; you can redistribute it and/or modify it
1884       under the same terms as Perl itself.
1885
1886       See <http://www.perl.com/perl/misc/Artistic.html>
1887
1888
1889
1890perl v5.36.0                      2023-03-27            ExtUtils::MakeMaker(3)
Impressum