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

ENVIRONMENT

1810       PERL_MM_OPT
1811           Command line options used by "MakeMaker->new()", and thus by
1812           "WriteMakefile()".  The string is split as the shell would, and the
1813           result is processed before any actual command line arguments are
1814           processed.
1815
1816             PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1817
1818       PERL_MM_USE_DEFAULT
1819           If set to a true value then MakeMaker's prompt function will always
1820           return the default without waiting for user input.
1821
1822       PERL_CORE
1823           Same as the PERL_CORE parameter.  The parameter overrides this.
1824

SEE ALSO

1826       Module::Build is a pure-Perl alternative to MakeMaker which does not
1827       rely on make or any other external utility.  It is easier to extend to
1828       suit your needs.
1829
1830       Module::Install is a wrapper around MakeMaker which adds features not
1831       normally available.
1832
1833       ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1834       setup your distribution.
1835
1836       CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1837
1838       File::ShareDir::Install makes it easy to install static, sometimes also
1839       referred to as 'shared' files. File::ShareDir helps accessing the
1840       shared files after installation.
1841
1842       Dist::Zilla makes it easy for the module author to create MakeMaker-
1843       based distributions with lots of bells and whistles.
1844

AUTHORS

1846       Andy Dougherty "doughera@lafayette.edu", Andreas König
1847       "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org".  VMS support by
1848       Charles Bailey "bailey@newman.upenn.edu".  OS/2 support by Ilya
1849       Zakharevich "ilya@math.ohio-state.edu".
1850
1851       Currently maintained by Michael G Schwern "schwern@pobox.com"
1852
1853       Send patches and ideas to "makemaker@perl.org".
1854
1855       Send bug reports via http://rt.cpan.org/.  Please send your generated
1856       Makefile along with your report.
1857
1858       For more up-to-date information, see
1859       <https://metacpan.org/release/ExtUtils-MakeMaker>.
1860
1861       Repository available at
1862       <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1863

LICENSE

1865       This program is free software; you can redistribute it and/or modify it
1866       under the same terms as Perl itself.
1867
1868       See <http://www.perl.com/perl/misc/Artistic.html>
1869
1870
1871
1872perl v5.30.0                      2019-09-11            ExtUtils::MakeMaker(3)
Impressum