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

ENVIRONMENT

1796       PERL_MM_OPT
1797           Command line options used by "MakeMaker->new()", and thus by
1798           "WriteMakefile()".  The string is split as the shell would, and the
1799           result is processed before any actual command line arguments are
1800           processed.
1801
1802             PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
1803
1804       PERL_MM_USE_DEFAULT
1805           If set to a true value then MakeMaker's prompt function will always
1806           return the default without waiting for user input.
1807
1808       PERL_CORE
1809           Same as the PERL_CORE parameter.  The parameter overrides this.
1810

SEE ALSO

1812       Module::Build is a pure-Perl alternative to MakeMaker which does not
1813       rely on make or any other external utility.  It is easier to extend to
1814       suit your needs.
1815
1816       Module::Install is a wrapper around MakeMaker which adds features not
1817       normally available.
1818
1819       ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1820       setup your distribution.
1821
1822       CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1823
1824       File::ShareDir::Install makes it easy to install static, sometimes also
1825       referred to as 'shared' files. File::ShareDir helps accessing the
1826       shared files after installation.
1827
1828       Dist::Zilla makes it easy for the module author to create MakeMaker-
1829       based distributions with lots of bells and whistles.
1830

AUTHORS

1832       Andy Dougherty "doughera@lafayette.edu", Andreas König
1833       "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org".  VMS support by
1834       Charles Bailey "bailey@newman.upenn.edu".  OS/2 support by Ilya
1835       Zakharevich "ilya@math.ohio-state.edu".
1836
1837       Currently maintained by Michael G Schwern "schwern@pobox.com"
1838
1839       Send patches and ideas to "makemaker@perl.org".
1840
1841       Send bug reports via http://rt.cpan.org/.  Please send your generated
1842       Makefile along with your report.
1843
1844       For more up-to-date information, see
1845       <https://metacpan.org/release/ExtUtils-MakeMaker>.
1846
1847       Repository available at
1848       <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1849

LICENSE

1851       This program is free software; you can redistribute it and/or modify it
1852       under the same terms as Perl itself.
1853
1854       See <http://www.perl.com/perl/misc/Artistic.html>
1855
1856
1857
1858perl v5.28.0                      2018-07-14            ExtUtils::MakeMaker(3)
Impressum