1ExtUtils::MakeMaker(3pm)Perl Programmers Reference GuideExtUtils::MakeMaker(3pm)
2
3
4

NAME

6       ExtUtils::MakeMaker - Create a module Makefile
7

SYNOPSIS

9         use ExtUtils::MakeMaker;
10
11         WriteMakefile( ATTRIBUTE => VALUE [, ...] );
12

DESCRIPTION

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

ENVIRONMENT

1489       PERL_MM_OPT
1490           Command line options used by "MakeMaker->new()", and thus by
1491           "WriteMakefile()".  The string is split on whitespace, and the
1492           result is processed before any actual command line arguments are
1493           processed.
1494
1495       PERL_MM_USE_DEFAULT
1496           If set to a true value then MakeMaker's prompt function will always
1497           return the default without waiting for user input.
1498
1499       PERL_CORE
1500           Same as the PERL_CORE parameter.  The parameter overrides this.
1501

SEE ALSO

1503       Module::Build is a pure-Perl alternative to MakeMaker which does not
1504       rely on make or any other external utility.  It is easier to extend to
1505       suit your needs.
1506
1507       Module::Install is a wrapper around MakeMaker which adds features not
1508       normally available.
1509
1510       ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1511       setup your distribution.
1512

AUTHORS

1514       Andy Dougherty "doughera@lafayette.edu", Andreas Koenig
1515       "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org".  VMS support by
1516       Charles Bailey "bailey@newman.upenn.edu".  OS/2 support by Ilya
1517       Zakharevich "ilya@math.ohio-state.edu".
1518
1519       Currently maintained by Michael G Schwern "schwern@pobox.com"
1520
1521       Send patches and ideas to "makemaker@perl.org".
1522
1523       Send bug reports via http://rt.cpan.org/.  Please send your generated
1524       Makefile along with your report.
1525
1526       For more up-to-date information, see <http://www.makemaker.org>.
1527

LICENSE

1529       This program is free software; you can redistribute it and/or modify it
1530       under the same terms as Perl itself.
1531
1532       See <http://www.perl.com/perl/misc/Artistic.html>
1533
1534
1535
1536perl v5.10.1                      2017-03-22          ExtUtils::MakeMaker(3pm)
Impressum