1ExtUtils::MakeMaker(3)User Contributed Perl DocumentationExtUtils::MakeMaker(3)
2
6 ExtUtils::MakeMaker - Create a module Makefile
7
9 use ExtUtils::MakeMaker;
10 WriteMakefile(
12 NAME => "Foo::Bar",
13 VERSION_FROM => "lib/Foo/Bar.pm",
14 );
15
17 This utility is designed to write a Makefile for an extension module
18 from a Makefile.PL. It is based on the Makefile.SH model provided by
19 Andy Dougherty and the perl5-porters.
20 It splits the task of generating the Makefile into several subroutines
22 that can be individually overridden. Each subroutine returns the text
23 it wishes to have written to the Makefile.
24 As there are various Make programs with incompatible syntax, which use
26 operating system shells, again with incompatible syntax, it is
27 important for users of this module to know which flavour of Make a
28 Makefile has been written for so they'll use the correct one and won't
29 have to face the possibly bewildering errors resulting from using the
30 wrong one.
31 On POSIX systems, that program will likely be GNU Make; on Microsoft
33 Windows, it will be either Microsoft NMake or DMake. Note that this
34 module does not support generating Makefiles for GNU Make on Windows.
35 See the section on the "MAKE" parameter for details.
36 MakeMaker is object oriented. Each directory below the current
38 directory that contains a Makefile.PL is treated as a separate object.
39 This makes it possible to write an unlimited number of Makefiles with a
40 single invocation of WriteMakefile().
41 How To Write A Makefile.PL
43 See ExtUtils::MakeMaker::Tutorial.
44 The long answer is the rest of the manpage :-)
46 Default Makefile Behaviour
48 The generated Makefile enables the user of the extension to invoke
49 perl Makefile.PL # optionally "perl Makefile.PL verbose"
51 make
52 make test # optionally set TEST_VERBOSE=1
53 make install # See below
54 The Makefile to be produced may be altered by adding arguments of the
56 form "KEY=VALUE". E.g.
57 perl Makefile.PL INSTALL_BASE=~
59 Other interesting targets in the generated Makefile are
61 make config # to check if the Makefile is up-to-date
63 make clean # delete local temp files (Makefile gets renamed)
64 make realclean # delete derived files (including ./blib)
65 make ci # check in all the files in the MANIFEST file
66 make dist # see below the Distribution Support section
67 make test
69 MakeMaker checks for the existence of a file named test.pl in the
70 current directory, and if it exists it executes the script with the
71 proper set of perl "-I" options.
72 MakeMaker also checks for any files matching glob("t/*.t"). It will
74 execute all matching files in alphabetical order via the Test::Harness
75 module with the "-I" switches set correctly.
76 If you'd like to see the raw output of your tests, set the
78 "TEST_VERBOSE" variable to true.
79 make test TEST_VERBOSE=1
81 make testdb
83 A useful variation of the above is the target "testdb". It runs the
84 test under the Perl debugger (see perldebug). If the file test.pl
85 exists in the current directory, it is used for the test.
86 If you want to debug some other testfile, set the "TEST_FILE" variable
88 thusly:
89 make testdb TEST_FILE=t/mytest.t
91 By default the debugger is called using "-d" option to perl. If you
93 want to specify some other option, set the "TESTDB_SW" variable:
94 make testdb TESTDB_SW=-Dx
96 make install
98 make alone puts all relevant files into directories that are named by
99 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
100 INST_MAN3DIR. All these default to something below ./blib if you are
101 not building below the perl source directory. If you are building below
102 the perl source, INST_LIB and INST_ARCHLIB default to ../../lib, and
103 INST_SCRIPT is not defined.
104 The install target of the generated Makefile copies the files found
106 below each of the INST_* directories to their INSTALL* counterparts.
107 Which counterparts are chosen depends on the setting of INSTALLDIRS
108 according to the following table:
109 INSTALLDIRS set to
111 perl site vendor
112 PERLPREFIX SITEPREFIX VENDORPREFIX
114 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
115 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
116 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
117 INST_SCRIPT INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
118 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
119 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
120 The INSTALL... macros in turn default to their %Config
122 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
123 You can check the values of these variables on your system with
125 perl '-V:install.*'
127 And to check the sequence in which the library directories are searched
129 by perl, run
130 perl -le 'print join $/, @INC'
132 Sometimes older versions of the module you're installing live in other
134 directories in @INC. Because Perl loads the first version of a module
135 it finds, not the newest, you might accidentally get one of these older
136 versions even after installing a brand new version. To delete all
137 other versions of the module you're installing (not simply older ones)
138 set the "UNINST" variable.
139 make install UNINST=1
141 INSTALL_BASE
143 INSTALL_BASE can be passed into Makefile.PL to change where your module
144 will be installed. INSTALL_BASE is more like what everyone else calls
145 "prefix" than PREFIX is.
146 To have everything installed in your home directory, do the following.
148 # Unix users, INSTALL_BASE=~ works fine
150 perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
151 Like PREFIX, it sets several INSTALL* attributes at once. Unlike
153 PREFIX it is easy to predict where the module will end up. The
154 installation pattern looks like this:
155 INSTALLARCHLIB INSTALL_BASE/lib/perl5/$Config{archname}
157 INSTALLPRIVLIB INSTALL_BASE/lib/perl5
158 INSTALLBIN INSTALL_BASE/bin
159 INSTALLSCRIPT INSTALL_BASE/bin
160 INSTALLMAN1DIR INSTALL_BASE/man/man1
161 INSTALLMAN3DIR INSTALL_BASE/man/man3
162 INSTALL_BASE in MakeMaker and "--install_base" in Module::Build (as of
164 0.28) install to the same location. If you want MakeMaker and
165 Module::Build to install to the same location simply set INSTALL_BASE
166 and "--install_base" to the same location.
167 INSTALL_BASE was added in 6.31.
169 PREFIX and LIB attribute
171 PREFIX and LIB can be used to set several INSTALL* attributes in one
172 go. Here's an example for installing into your home directory.
173 # Unix users, PREFIX=~ works fine
175 perl Makefile.PL PREFIX=/path/to/your/home/dir
176 This will install all files in the module under your home directory,
178 with man pages and libraries going into an appropriate place (usually
179 ~/man and ~/lib). How the exact location is determined is complicated
180 and depends on how your Perl was configured. INSTALL_BASE works more
181 like what other build systems call "prefix" than PREFIX and we
182 recommend you use that instead.
183 Another way to specify many INSTALL directories with a single parameter
185 is LIB.
186 perl Makefile.PL LIB=~/lib
188 This will install the module's architecture-independent files into
190 ~/lib, the architecture-dependent files into ~/lib/$archname.
191 Note, that in both cases the tilde expansion is done by MakeMaker, not
193 by perl by default, nor by make.
194 Conflicts between parameters LIB, PREFIX and the various INSTALL*
196 arguments are resolved so that:
197 · setting LIB overrides any setting of INSTALLPRIVLIB,
199 INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not
200 affected by PREFIX);
201 · without LIB, setting PREFIX replaces the initial $Config{prefix}
203 part of those INSTALL* arguments, even if the latter are explicitly
204 set (but are set to still start with $Config{prefix}).
205 If the user has superuser privileges, and is not working on AFS or
207 relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
208 INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
209 the best:
210 perl Makefile.PL;
212 make;
213 make test
214 make install
215 make install by default writes some documentation of what has been done
217 into the file "$(INSTALLARCHLIB)/perllocal.pod". This feature can be
218 bypassed by calling make pure_install.
219 AFS users
221 will have to specify the installation directories as these most
222 probably have changed since perl itself has been installed. They will
223 have to do this by calling
224 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
226 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
227 make
228 Be careful to repeat this procedure every time you recompile an
230 extension, unless you are sure the AFS installation directories are
231 still valid.
232 Static Linking of a new Perl Binary
234 An extension that is built with the above steps is ready to use on
235 systems supporting dynamic loading. On systems that do not support
236 dynamic loading, any newly created extension has to be linked together
237 with the available resources. MakeMaker supports the linking process by
238 creating appropriate targets in the Makefile whenever an extension is
239 built. You can invoke the corresponding section of the makefile with
240 make perl
242 That produces a new perl binary in the current directory with all
244 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP, and
245 PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on UNIX,
246 this is called Makefile.aperl (may be system dependent). If you want to
247 force the creation of a new perl, it is recommended that you delete
248 this Makefile.aperl, so the directories are searched through for
249 linkable libraries again.
250 The binary can be installed into the directory where perl normally
252 resides on your machine with
253 make inst_perl
255 To produce a perl binary with a different name than "perl", either say
257 perl Makefile.PL MAP_TARGET=myperl
259 make myperl
260 make inst_perl
261 or say
263 perl Makefile.PL
265 make myperl MAP_TARGET=myperl
266 make inst_perl MAP_TARGET=myperl
267 In any case you will be prompted with the correct invocation of the
269 "inst_perl" target that installs the new binary into INSTALLBIN.
270 make inst_perl by default writes some documentation of what has been
272 done into the file "$(INSTALLARCHLIB)/perllocal.pod". This can be
273 bypassed by calling make pure_inst_perl.
274 Warning: the inst_perl: target will most probably overwrite your
276 existing perl binary. Use with care!
277 Sometimes you might want to build a statically linked perl although
279 your system supports dynamic loading. In this case you may explicitly
280 set the linktype with the invocation of the Makefile.PL or make:
281 perl Makefile.PL LINKTYPE=static # recommended
283 or
285 make LINKTYPE=static # works on most systems
287 Determination of Perl Library and Installation Locations
289 MakeMaker needs to know, or to guess, where certain things are located.
290 Especially INST_LIB and INST_ARCHLIB (where to put the files during the
291 make(1) run), PERL_LIB and PERL_ARCHLIB (where to read existing modules
292 from), and PERL_INC (header files and "libperl*.*").
293 Extensions may be built either using the contents of the perl source
295 directory tree or from the installed perl library. The recommended way
296 is to build extensions after you have run 'make install' on perl
297 itself. You can do that in any directory on your hard disk that is not
298 below the perl source tree. The support for extensions below the ext
299 directory of the perl distribution is only good for the standard
300 extensions that come with perl.
301 If an extension is being built below the "ext/" directory of the perl
303 source then MakeMaker will set PERL_SRC automatically (e.g., "../..").
304 If PERL_SRC is defined and the extension is recognized as a standard
305 extension, then other variables default to the following:
306 PERL_INC = PERL_SRC
308 PERL_LIB = PERL_SRC/lib
309 PERL_ARCHLIB = PERL_SRC/lib
310 INST_LIB = PERL_LIB
311 INST_ARCHLIB = PERL_ARCHLIB
312 If an extension is being built away from the perl source then MakeMaker
314 will leave PERL_SRC undefined and default to using the installed copy
315 of the perl library. The other variables default to the following:
316 PERL_INC = $archlibexp/CORE
318 PERL_LIB = $privlibexp
319 PERL_ARCHLIB = $archlibexp
320 INST_LIB = ./blib/lib
321 INST_ARCHLIB = ./blib/arch
322 If perl has not yet been installed then PERL_SRC can be defined on the
324 command line as shown in the previous section.
325 Which architecture dependent directory?
327 If you don't want to keep the defaults for the INSTALL* macros,
328 MakeMaker helps you to minimize the typing needed: the usual
329 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined by
330 Configure at perl compilation time. MakeMaker supports the user who
331 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
332 then MakeMaker defaults the latter to be the same subdirectory of
333 INSTALLPRIVLIB as Configure decided for the counterparts in %Config,
334 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
335 for INSTALLSITELIB and INSTALLSITEARCH.
336 MakeMaker gives you much more freedom than needed to configure internal
338 variables and get different results. It is worth mentioning that
339 make(1) also lets you configure most of the variables that are used in
340 the Makefile. But in the majority of situations this will not be
341 necessary, and should only be done if the author of a package
342 recommends it (or you know what you're doing).
343 Using Attributes and Parameters
345 The following attributes may be specified as arguments to
346 WriteMakefile() or as NAME=VALUE pairs on the command line.
347 ABSTRACT
349 One line description of the module. Will be included in PPD file.
350 ABSTRACT_FROM
352 Name of the file that contains the package description. MakeMaker
353 looks for a line in the POD matching /^($package\s-\s)(.*)/. This is
354 typically the first line in the "=head1 NAME" section. $2 becomes the
355 abstract.
356 AUTHOR
358 Array of strings containing name (and email address) of package
359 author(s). Is used in CPAN Meta files (META.yml or META.json) and
360 PPD (Perl Package Description) files for PPM (Perl Package Manager).
361 BINARY_LOCATION
363 Used when creating PPD files for binary packages. It can be set to a
364 full or relative path or URL to the binary archive for a particular
365 architecture. For example:
366 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
368 builds a PPD package that references a binary of the "Agent" package,
370 located in the "x86" directory relative to the PPD itself.
371 BUILD_REQUIRES
373 A hash of modules that are needed to build your module but not run
374 it.
375 This will go into the "build_requires" field of your CPAN Meta file.
377 (META.yml or META.json).
378 The format is the same as PREREQ_PM.
380 C Ref to array of *.c file names. Initialised from a directory scan and
382 the values portion of the XS attribute hash. This is not currently
383 used by MakeMaker but may be handy in Makefile.PLs.
384 CCFLAGS
386 String that will be included in the compiler call command line
387 between the arguments INC and OPTIMIZE.
388 CONFIG
390 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
391 config.sh. MakeMaker will add to CONFIG the following values anyway:
392 ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
393 lib_ext obj_ext ranlib sitelibexp sitearchexp so
394 CONFIGURE
396 CODE reference. The subroutine should return a hash reference. The
397 hash may contain further attributes, e.g. {LIBS => ...}, that have to
398 be determined by some evaluation method.
399 CONFIGURE_REQUIRES
401 A hash of modules that are required to run Makefile.PL itself, but
402 not to run your distribution.
403 This will go into the "configure_requires" field of your CPAN Meta
405 file (META.yml or META.json)
406 Defaults to "{ "ExtUtils::MakeMaker" => 0 }"
408 The format is the same as PREREQ_PM.
410 DEFINE
412 Something like "-DHAVE_UNISTD_H"
413 DESTDIR
415 This is the root directory into which the code will be installed. It
416 prepends itself to the normal prefix. For example, if your code
417 would normally go into /usr/local/lib/perl you could set
418 DESTDIR=~/tmp/ and installation would go into
419 ~/tmp/usr/local/lib/perl.
420 This is primarily of use for people who repackage Perl modules.
422 NOTE: Due to the nature of make, it is important that you put the
424 trailing slash on your DESTDIR. ~/tmp/ not ~/tmp.
425 DIR
427 Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
428 in ext/SDBM_File
429 DISTNAME
431 A safe filename for the package.
432 Defaults to NAME below but with :: replaced with -.
434 For example, Foo::Bar becomes Foo-Bar.
436 DISTVNAME
438 Your name for distributing the package with the version number
439 included. This is used by 'make dist' to name the resulting archive
440 file.
441 Defaults to DISTNAME-VERSION.
443 For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
445 On some OS's where . has special meaning VERSION_SYM may be used in
447 place of VERSION.
448 DL_FUNCS
450 Hashref of symbol names for routines to be made available as
451 universal symbols. Each key/value pair consists of the package name
452 and an array of routine names in that package. Used only under AIX,
453 OS/2, VMS and Win32 at present. The routine names supplied will be
454 expanded in the same way as XSUB names are expanded by the XS()
455 macro. Defaults to
456 {"$(NAME)" => ["boot_$(NAME)" ] }
458 e.g.
460 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
462 "NetconfigPtr" => [ 'DESTROY'] }
463 Please see the ExtUtils::Mksymlists documentation for more
465 information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
466 DL_VARS
468 Array of symbol names for variables to be made available as universal
469 symbols. Used only under AIX, OS/2, VMS and Win32 at present.
470 Defaults to []. (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
471 EXCLUDE_EXT
473 Array of extension names to exclude when doing a static build. This
474 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
475 details. (e.g. [ qw( Socket POSIX ) ] )
476 This attribute may be most useful when specified as a string on the
478 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
479 EXE_FILES
481 Ref to array of executable files. The files will be copied to the
482 INST_SCRIPT directory. Make realclean will delete them from there
483 again.
484 If your executables start with something like #!perl or
486 #!/usr/bin/perl MakeMaker will change this to the path of the perl
487 'Makefile.PL' was invoked with so the programs will be sure to run
488 properly even if perl is not in /usr/bin/perl.
489 FIRST_MAKEFILE
491 The name of the Makefile to be produced. This is used for the second
492 Makefile that will be produced for the MAP_TARGET.
493 Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
495 (Note: we couldn't use MAKEFILE because dmake uses this for something
497 else).
498 FULLPERL
500 Perl binary able to run this extension, load XS modules, etc...
501 FULLPERLRUN
503 Like PERLRUN, except it uses FULLPERL.
504 FULLPERLRUNINST
506 Like PERLRUNINST, except it uses FULLPERL.
507 FUNCLIST
509 This provides an alternate means to specify function names to be
510 exported from the extension. Its value is a reference to an array of
511 function names to be exported by the extension. These names are
512 passed through unaltered to the linker options file.
513 H Ref to array of *.h file names. Similar to C.
515 IMPORTS
517 This attribute is used to specify names to be imported into the
518 extension. Takes a hash ref.
519 It is only used on OS/2 and Win32.
521 INC
523 Include file dirs eg: "-I/usr/5include -I/path/to/inc"
524 INCLUDE_EXT
526 Array of extension names to be included when doing a static build.
527 MakeMaker will normally build with all of the installed extensions
528 when doing a static build, and that is usually the desired behavior.
529 If INCLUDE_EXT is present then MakeMaker will build only with those
530 extensions which are explicitly mentioned. (e.g. [ qw( Socket POSIX
531 ) ])
532 It is not necessary to mention DynaLoader or the current extension
534 when filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is
535 empty then only DynaLoader and the current extension will be included
536 in the build.
537 This attribute may be most useful when specified as a string on the
539 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket
540 Devel::Peek'
541 INSTALLARCHLIB
543 Used by 'make install', which copies files from INST_ARCHLIB to this
544 directory if INSTALLDIRS is set to perl.
545 INSTALLBIN
547 Directory to install binary files (e.g. tkperl) into if
548 INSTALLDIRS=perl.
549 INSTALLDIRS
551 Determines which of the sets of installation directories to choose:
552 perl, site or vendor. Defaults to site.
553 INSTALLMAN1DIR
555 INSTALLMAN3DIR
556 These directories get the man pages at 'make install' time if
557 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
558 If set to 'none', no man pages will be installed.
560 INSTALLPRIVLIB
562 Used by 'make install', which copies files from INST_LIB to this
563 directory if INSTALLDIRS is set to perl.
564 Defaults to $Config{installprivlib}.
566 INSTALLSCRIPT
568 Used by 'make install' which copies files from INST_SCRIPT to this
569 directory if INSTALLDIRS=perl.
570 INSTALLSITEARCH
572 Used by 'make install', which copies files from INST_ARCHLIB to this
573 directory if INSTALLDIRS is set to site (default).
574 INSTALLSITEBIN
576 Used by 'make install', which copies files from INST_BIN to this
577 directory if INSTALLDIRS is set to site (default).
578 INSTALLSITELIB
580 Used by 'make install', which copies files from INST_LIB to this
581 directory if INSTALLDIRS is set to site (default).
582 INSTALLSITEMAN1DIR
584 INSTALLSITEMAN3DIR
585 These directories get the man pages at 'make install' time if
586 INSTALLDIRS=site (default). Defaults to
587 $(SITEPREFIX)/man/man$(MAN*EXT).
588 If set to 'none', no man pages will be installed.
590 INSTALLSITESCRIPT
592 Used by 'make install' which copies files from INST_SCRIPT to this
593 directory if INSTALLDIRS is set to site (default).
594 INSTALLVENDORARCH
596 Used by 'make install', which copies files from INST_ARCHLIB to this
597 directory if INSTALLDIRS is set to vendor.
598 INSTALLVENDORBIN
600 Used by 'make install', which copies files from INST_BIN to this
601 directory if INSTALLDIRS is set to vendor.
602 INSTALLVENDORLIB
604 Used by 'make install', which copies files from INST_LIB to this
605 directory if INSTALLDIRS is set to vendor.
606 INSTALLVENDORMAN1DIR
608 INSTALLVENDORMAN3DIR
609 These directories get the man pages at 'make install' time if
610 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
611 If set to 'none', no man pages will be installed.
613 INSTALLVENDORSCRIPT
615 Used by 'make install' which copies files from INST_SCRIPT to this
616 directory if INSTALLDIRS is set to vendor.
617 INST_ARCHLIB
619 Same as INST_LIB for architecture dependent files.
620 INST_BIN
622 Directory to put real binary files during 'make'. These will be
623 copied to INSTALLBIN during 'make install'
624 INST_LIB
626 Directory where we put library files of this extension while building
627 it.
628 INST_MAN1DIR
630 Directory to hold the man pages at 'make' time
631 INST_MAN3DIR
633 Directory to hold the man pages at 'make' time
634 INST_SCRIPT
636 Directory where executable files should be installed during 'make'.
637 Defaults to "./blib/script", just to have a dummy location during
638 testing. make install will copy the files in INST_SCRIPT to
639 INSTALLSCRIPT.
640 LD
642 Program to be used to link libraries for dynamic loading.
643 Defaults to $Config{ld}.
645 LDDLFLAGS
647 Any special flags that might need to be passed to ld to create a
648 shared library suitable for dynamic loading. It is up to the
649 makefile to use it. (See "lddlflags" in Config)
650 Defaults to $Config{lddlflags}.
652 LDFROM
654 Defaults to "$(OBJECT)" and is used in the ld command to specify what
655 files to link/load from (also see dynamic_lib below for how to
656 specify ld flags)
657 LIB
659 LIB should only be set at "perl Makefile.PL" time but is allowed as a
660 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
661 and INSTALLSITELIB to that value regardless any explicit setting of
662 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
663 are set to the corresponding architecture subdirectory.
664 LIBPERL_A
666 The filename of the perllibrary that will be used together with this
667 extension. Defaults to libperl.a.
668 LIBS
670 An anonymous array of alternative library specifications to be
671 searched for (in order) until at least one library is found. E.g.
672 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
674 Mind, that any element of the array contains a complete set of
676 arguments for the ld command. So do not specify
677 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
679 See ODBM_File/Makefile.PL for an example, where an array is needed.
681 If you specify a scalar as in
682 'LIBS' => "-ltcl -ltk -lX11"
684 MakeMaker will turn it into an array with one element.
686 LICENSE
688 The licensing terms of your distribution. Generally it's "perl" for
689 the same license as Perl itself.
690 See Module::Build::API for the list of options.
692 Defaults to "unknown".
694 LINKTYPE
696 'static' or 'dynamic' (default unless usedl=undef in config.sh).
697 Should only be used to force static linking (also see linkext below).
698 MAKE
700 Variant of make you intend to run the generated Makefile with. This
701 parameter lets Makefile.PL know what make quirks to account for when
702 generating the Makefile.
703 MakeMaker also honors the MAKE environment variable. This parameter
705 takes precedence.
706 Currently the only significant values are 'dmake' and 'nmake' for
708 Windows users, instructing MakeMaker to generate a Makefile in the
709 flavour of DMake ("Dennis Vadura's Make") or Microsoft NMake
710 respectively.
711 Defaults to $Config{make}, which may go looking for a Make program in
713 your environment.
714 How are you supposed to know what flavour of Make a Makefile has been
716 generated for if you didn't specify a value explicitly? Search the
717 generated Makefile for the definition of the MAKE variable, which is
718 used to recursively invoke the Make utility. That will tell you what
719 Make you're supposed to invoke the Makefile with.
720 MAKEAPERL
722 Boolean which tells MakeMaker that it should include the rules to
723 make a perl. This is handled automatically as a switch by MakeMaker.
724 The user normally does not need it.
725 MAKEFILE_OLD
727 When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
728 backed up at this location.
729 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
731 MAN1PODS
733 Hashref of pod-containing files. MakeMaker will default this to all
734 EXE_FILES files that include POD directives. The files listed here
735 will be converted to man pages and installed as was requested at
736 Configure time.
737 This hash should map POD files (or scripts containing POD) to the man
739 file names under the "blib/man1/" directory, as in the following
740 example:
741 MAN1PODS => {
743 'doc/command.pod' => 'blib/man1/command.1',
744 'scripts/script.pl' => 'blib/man1/script.1',
745 }
746 MAN3PODS
748 Hashref that assigns to *.pm and *.pod files the files into which the
749 manpages are to be written. MakeMaker parses all *.pod and *.pm files
750 for POD directives. Files that contain POD will be the default keys
751 of the MAN3PODS hashref. These will then be converted to man pages
752 during "make" and will be installed during "make install".
753 Example similar to MAN1PODS.
755 MAP_TARGET
757 If it is intended that a new perl binary be produced, this variable
758 may hold a name for that binary. Defaults to perl
759 META_ADD
761 META_MERGE
762 A hashref of items to add to the CPAN Meta file (META.yml or
763 META.json).
764 They differ in how they behave if they have the same key as the
766 default metadata. META_ADD will override the default value with its
767 own. META_MERGE will merge its value with the default.
768 Unless you want to override the defaults, prefer META_MERGE so as to
770 get the advantage of any future defaults.
771 By default CPAN Meta specification 1.4 is used. In order to use CPAN
773 Meta specification 2.0, indicate with "meta-spec" the version you
774 want to use.
775 META_MERGE => {
777 "meta-spec" => { version => 2 },
779 repository => {
781 type => 'git',
782 url => 'git://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker.git',
783 web => 'https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker',
784 },
785 },
787 MIN_PERL_VERSION
789 The minimum required version of Perl for this distribution.
790 Either the 5.006001 or the 5.6.1 format is acceptable.
792 MYEXTLIB
794 If the extension links to a library that it builds, set this to the
795 name of the library (see SDBM_File)
796 NAME
798 The package representing the distribution. For example, "Test::More"
799 or "ExtUtils::MakeMaker". It will be used to derive information about
800 the distribution such as the DISTNAME, installation locations within
801 the Perl library and where XS files will be looked for by default
802 (see XS).
803 "NAME" must be a valid Perl package name and it must have an
805 associated ".pm" file. For example, "Foo::Bar" is a valid "NAME" and
806 there must exist Foo/Bar.pm. Any XS code should be in Bar.xs unless
807 stated otherwise.
808 Your distribution must have a "NAME".
810 NEEDS_LINKING
812 MakeMaker will figure out if an extension contains linkable code
813 anywhere down the directory tree, and will set this variable
814 accordingly, but you can speed it up a very little bit if you define
815 this boolean variable yourself.
816 NOECHO
818 Command so make does not print the literal commands it's running.
819 By setting it to an empty string you can generate a Makefile that
821 prints all commands. Mainly used in debugging MakeMaker itself.
822 Defaults to "@".
824 NORECURS
826 Boolean. Attribute to inhibit descending into subdirectories.
827 NO_META
829 When true, suppresses the generation and addition to the MANIFEST of
830 the META.yml and META.json module meta-data files during 'make
831 distdir'.
832 Defaults to false.
834 NO_MYMETA
836 When true, suppresses the generation of MYMETA.yml and MYMETA.json
837 module meta-data files during 'perl Makefile.PL'.
838 Defaults to false.
840 NO_VC
842 In general, any generated Makefile checks for the current version of
843 MakeMaker and the version the Makefile was built under. If NO_VC is
844 set, the version check is neglected. Do not write this into your
845 Makefile.PL, use it interactively instead.
846 OBJECT
848 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be
849 a long string containing all object files, e.g. "tkpBind.o
850 tkpButton.o tkpCanvas.o"
851 (Where BASEEXT is the last component of NAME, and OBJ_EXT is
853 $Config{obj_ext}.)
854 OPTIMIZE
856 Defaults to "-O". Set it to "-g" to turn debugging on. The flag is
857 passed to subdirectory makes.
858 PERL
860 Perl binary for tasks that can be done by miniperl.
861 PERL_CORE
863 Set only when MakeMaker is building the extensions of the Perl core
864 distribution.
865 PERLMAINCC
867 The call to the program that is able to compile perlmain.c. Defaults
868 to $(CC).
869 PERL_ARCHLIB
871 Same as for PERL_LIB, but for architecture dependent files.
872 Used only when MakeMaker is building the extensions of the Perl core
874 distribution (because normally $(PERL_ARCHLIB) is automatically in
875 @INC, and adding it would get in the way of PERL5LIB).
876 PERL_LIB
878 Directory containing the Perl library to use.
879 Used only when MakeMaker is building the extensions of the Perl core
881 distribution (because normally $(PERL_LIB) is automatically in @INC,
882 and adding it would get in the way of PERL5LIB).
883 PERL_MALLOC_OK
885 defaults to 0. Should be set to TRUE if the extension can work with
886 the memory allocation routines substituted by the Perl malloc()
887 subsystem. This should be applicable to most extensions with
888 exceptions of those
889 · with bugs in memory allocations which are caught by Perl's
891 malloc();
892 · which interact with the memory allocator in other ways than via
894 malloc(), realloc(), free(), calloc(), sbrk() and brk();
895 · which rely on special alignment which is not provided by Perl's
897 malloc().
898 NOTE. Neglecting to set this flag in any one of the loaded extension
900 nullifies many advantages of Perl's malloc(), such as better usage of
901 system resources, error detection, memory usage reporting, catchable
902 failure of memory allocations, etc.
903 PERLPREFIX
905 Directory under which core modules are to be installed.
906 Defaults to $Config{installprefixexp}, falling back to
908 $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
909 $Config{installprefixexp} not exist.
910 Overridden by PREFIX.
912 PERLRUN
914 Use this instead of $(PERL) when you wish to run perl. It will set
915 up extra necessary flags for you.
916 PERLRUNINST
918 Use this instead of $(PERL) when you wish to run perl to work with
919 modules. It will add things like -I$(INST_ARCH) and other necessary
920 flags so perl can see the modules you're about to install.
921 PERL_SRC
923 Directory containing the Perl source code (use of this should be
924 avoided, it may be undefined)
925 PERM_DIR
927 Desired permission for directories. Defaults to 755.
928 PERM_RW
930 Desired permission for read/writable files. Defaults to 644.
931 PERM_RWX
933 Desired permission for executable files. Defaults to 755.
934 PL_FILES
936 MakeMaker can run programs to generate files for you at build time.
937 By default any file named *.PL (except Makefile.PL and Build.PL) in
938 the top level directory will be assumed to be a Perl program and run
939 passing its own basename in as an argument. For example...
940 perl foo.PL foo
942 This behavior can be overridden by supplying your own set of files to
944 search. PL_FILES accepts a hash ref, the key being the file to run
945 and the value is passed in as the first argument when the PL file is
946 run.
947 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
949 Would run bin/foobar.PL like this:
951 perl bin/foobar.PL bin/foobar
953 If multiple files from one program are desired an array ref can be
955 used.
956 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
958 In this case the program will be run multiple times using each target
960 file.
961 perl bin/foobar.PL bin/foobar1
963 perl bin/foobar.PL bin/foobar2
964 PL files are normally run after pm_to_blib and include INST_LIB and
966 INST_ARCH in their @INC, so the just built modules can be accessed...
967 unless the PL file is making a module (or anything else in PM) in
968 which case it is run before pm_to_blib and does not include INST_LIB
969 and INST_ARCH in its @INC. This apparently odd behavior is there for
970 backwards compatibility (and it's somewhat DWIM).
971 PM
973 Hashref of .pm files and *.pl files to be installed. e.g.
974 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
976 By default this will include *.pm and *.pl and the files found in the
978 PMLIBDIRS directories. Defining PM in the Makefile.PL will override
979 PMLIBDIRS.
980 PMLIBDIRS
982 Ref to array of subdirectories containing library files. Defaults to
983 [ 'lib', $(BASEEXT) ]. The directories will be scanned and any files
984 they contain will be installed in the corresponding location in the
985 library. A libscan() method can be used to alter the behaviour.
986 Defining PM in the Makefile.PL will override PMLIBDIRS.
987 (Where BASEEXT is the last component of NAME.)
989 PM_FILTER
991 A filter program, in the traditional Unix sense (input from stdin,
992 output to stdout) that is passed on each .pm file during the build
993 (in the pm_to_blib() phase). It is empty by default, meaning no
994 filtering is done.
995 Great care is necessary when defining the command if quoting needs to
997 be done. For instance, you would need to say:
998 {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
1000 to remove all the leading comments on the fly during the build. The
1002 extra \\ are necessary, unfortunately, because this variable is
1003 interpolated within the context of a Perl program built on the
1004 command line, and double quotes are what is used with the -e switch
1005 to build that command line. The # is escaped for the Makefile, since
1006 what is going to be generated will then be:
1007 PM_FILTER = grep -v \"^\#\"
1009 Without the \\ before the #, we'd have the start of a Makefile
1011 comment, and the macro would be incorrectly defined.
1012 POLLUTE
1014 Release 5.005 grandfathered old global symbol names by providing
1015 preprocessor macros for extension source compatibility. As of
1016 release 5.6, these preprocessor definitions are not available by
1017 default. The POLLUTE flag specifies that the old names should still
1018 be defined:
1019 perl Makefile.PL POLLUTE=1
1021 Please inform the module author if this is necessary to successfully
1023 install a module under 5.6 or later.
1024 PPM_INSTALL_EXEC
1026 Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
1027 perl)
1028 PPM_INSTALL_SCRIPT
1030 Name of the script that gets executed by the Perl Package Manager
1031 after the installation of a package.
1032 PREFIX
1034 This overrides all the default install locations. Man pages,
1035 libraries, scripts, etc... MakeMaker will try to make an educated
1036 guess about where to place things under the new PREFIX based on your
1037 Config defaults. Failing that, it will fall back to a structure
1038 which should be sensible for your platform.
1039 If you specify LIB or any INSTALL* variables they will not be
1041 affected by the PREFIX.
1042 PREREQ_FATAL
1044 Bool. If this parameter is true, failing to have the required modules
1045 (or the right versions thereof) will be fatal. "perl Makefile.PL"
1046 will "die" instead of simply informing the user of the missing
1047 dependencies.
1048 It is extremely rare to have to use "PREREQ_FATAL". Its use by module
1050 authors is strongly discouraged and should never be used lightly.
1051 Module installation tools have ways of resolving unmet dependencies
1053 but to do that they need a Makefile. Using "PREREQ_FATAL" breaks
1054 this. That's bad.
1055 Assuming you have good test coverage, your tests should fail with
1057 missing dependencies informing the user more strongly that something
1058 is wrong. You can write a t/00compile.t test which will simply check
1059 that your code compiles and stop "make test" prematurely if it
1060 doesn't. See "BAIL_OUT" in Test::More for more details.
1061 PREREQ_PM
1063 A hash of modules that are needed to run your module. The keys are
1064 the module names ie. Test::More, and the minimum version is the
1065 value. If the required version number is 0 any version will do.
1066 This will go into the "requires" field of your CPAN Meta file
1068 (META.yml or META.json).
1069 PREREQ_PM => {
1071 # Require Test::More at least 0.47
1072 "Test::More" => "0.47",
1073 # Require any version of Acme::Buffy
1075 "Acme::Buffy" => 0,
1076 }
1077 PREREQ_PRINT
1079 Bool. If this parameter is true, the prerequisites will be printed
1080 to stdout and MakeMaker will exit. The output format is an evalable
1081 hash ref.
1082 $PREREQ_PM = {
1084 'A::B' => Vers1,
1085 'C::D' => Vers2,
1086 ...
1087 };
1088 If a distribution defines a minimal required perl version, this is
1090 added to the output as an additional line of the form:
1091 $MIN_PERL_VERSION = '5.008001';
1093 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1095 hashref.
1096 PRINT_PREREQ
1098 RedHatism for "PREREQ_PRINT". The output format is different,
1099 though:
1100 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1102 A minimal required perl version, if present, will look like this:
1104 perl(perl)>=5.008001
1106 SITEPREFIX
1108 Like PERLPREFIX, but only for the site install locations.
1109 Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
1111 an explicit siteprefix in the Config. In those cases
1112 $Config{installprefix} will be used.
1113 Overridable by PREFIX
1115 SIGN
1117 When true, perform the generation and addition to the MANIFEST of the
1118 SIGNATURE file in the distdir during 'make distdir', via 'cpansign
1119 -s'.
1120 Note that you need to install the Module::Signature module to perform
1122 this operation.
1123 Defaults to false.
1125 SKIP
1127 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1128 Makefile. Caution! Do not use the SKIP attribute for the negligible
1129 speedup. It may seriously damage the resulting Makefile. Only use it
1130 if you really need it.
1131 TEST_REQUIRES
1133 A hash of modules that are needed to test your module but not run or
1134 build it.
1135 This will go into the "test_requires" field of your CPAN Meta file.
1137 (META.yml or META.json).
1138 The format is the same as PREREQ_PM.
1140 TYPEMAPS
1142 Ref to array of typemap file names. Use this when the typemaps are
1143 in some directory other than the current directory or when they are
1144 not named typemap. The last typemap in the list takes precedence. A
1145 typemap in the current directory has highest precedence, even if it
1146 isn't listed in TYPEMAPS. The default system typemap has lowest
1147 precedence.
1148 USE_MM_LD_RUN_PATH
1150 boolean The Fedora perl MakeMaker distribution differs from the
1151 standard upstream release in that it disables use of the MakeMaker
1152 generated LD_RUN_PATH by default, UNLESS this attribute is specified
1153 , or the USE_MM_LD_RUN_PATH environment variable is set during the
1154 MakeMaker run.
1155 The upstream MakeMaker will set the ld(1) environment variable
1157 LD_RUN_PATH to the concatenation of every -L ld(1) option directory
1158 in which a -l ld(1) option library is found, which is used as the
1159 ld(1) -rpath option if none is specified. This means that, if your
1160 application builds shared libraries and your MakeMaker application
1161 links to them, that the absolute paths of the libraries in the build
1162 tree will be inserted into the RPATH header of all MakeMaker
1163 generated binaries, and that such binaries will be unable to link to
1164 these libraries if they do not still reside in the build tree
1165 directories (unlikely) or in the system library directories (/lib or
1166 /usr/lib), regardless of any LD_LIBRARY_PATH setting. So if you
1167 specified -L../mylib -lmylib , and
1168 your 'libmylib.so' gets installed into
1169 /some_directory_other_than_usr_lib,
1170 your MakeMaker application will be unable to link to it, even if
1171 LD_LIBRARY_PATH is set to include /some_directory_other_than_usr_lib,
1172 because RPATH overrides LD_LIBRARY_PATH.
1173 So for Fedora MakeMaker builds LD_RUN_PATH is NOT generated by
1175 default for every link. You can still use explicit -rpath ld options
1176 or the LD_RUN_PATH environment variable during the build to generate
1177 an RPATH for the binaries.
1178 You can set the USE_MM_LD_RUN_PATH attribute to 1 on the MakeMaker
1180 command line or in the WriteMakefile arguments to enable generation
1181 of LD_RUN_PATH for every link command.
1182 USE_MM_LD_RUN_PATH will default to 1 (LD_RUN_PATH will be used) IF
1184 the $USE_MM_LD_RUN_PATH environment variable is set during a
1185 MakeMaker run.
1186 VENDORPREFIX
1188 Like PERLPREFIX, but only for the vendor install locations.
1189 Defaults to $Config{vendorprefixexp}.
1191 Overridable by PREFIX
1193 VERBINST
1195 If true, make install will be verbose
1196 VERSION
1198 Your version number for distributing the package. This defaults to
1199 0.1.
1200 VERSION_FROM
1202 Instead of specifying the VERSION in the Makefile.PL you can let
1203 MakeMaker parse a file to determine the version number. The parsing
1204 routine requires that the file named by VERSION_FROM contains one
1205 single line to compute the version number. The first line in the file
1206 that contains something like a $VERSION assignment or "package Name
1207 VERSION" will be used. The following lines will be parsed o.k.:
1208 # Good
1210 package Foo::Bar 1.23; # 1.23
1211 $VERSION = '1.00'; # 1.00
1212 *VERSION = \'1.01'; # 1.01
1213 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
1214 $FOO::VERSION = '1.10'; # 1.10
1215 *FOO::VERSION = \'1.11'; # 1.11
1216 but these will fail:
1218 # Bad
1220 my $VERSION = '1.01';
1221 local $VERSION = '1.02';
1222 local $FOO::VERSION = '1.30';
1223 (Putting "my" or "local" on the preceding line will work o.k.)
1225 "Version strings" are incompatible and should not be used.
1227 # Bad
1229 $VERSION = 1.2.3;
1230 $VERSION = v1.2.3;
1231 version objects are fine. As of MakeMaker 6.35 version.pm will be
1233 automatically loaded, but you must declare the dependency on
1234 version.pm. For compatibility with older MakeMaker you should load
1235 on the same line as $VERSION is declared.
1236 # All on one line
1238 use version; our $VERSION = qv(1.2.3);
1239 The file named in VERSION_FROM is not added as a dependency to
1241 Makefile. This is not really correct, but it would be a major pain
1242 during development to have to rewrite the Makefile for any smallish
1243 change in that file. If you want to make sure that the Makefile
1244 contains the correct VERSION macro after any change of the file, you
1245 would have to do something like
1246 depend => { Makefile => '$(VERSION_FROM)' }
1248 See attribute "depend" below.
1250 VERSION_SYM
1252 A sanitized VERSION with . replaced by _. For places where . has
1253 special meaning (some filesystems, RCS labels, etc...)
1254 XS
1256 Hashref of .xs files. MakeMaker will default this. e.g.
1257 {'name_of_file.xs' => 'name_of_file.c'}
1259 The .c files will automatically be included in the list of files
1261 deleted by a make clean.
1262 XSOPT
1264 String of options to pass to xsubpp. This might include "-C++" or
1265 "-extern". Do not include typemaps here; the TYPEMAP parameter
1266 exists for that purpose.
1267 XSPROTOARG
1269 May be set to an empty string, which is identical to "-prototypes",
1270 or "-noprototypes". See the xsubpp documentation for details.
1271 MakeMaker defaults to the empty string.
1272 XS_VERSION
1274 Your version number for the .xs file of this package. This defaults
1275 to the value of the VERSION attribute.
1276 Additional lowercase attributes
1278 can be used to pass parameters to the methods which implement that part
1279 of the Makefile. Parameters are specified as a hash ref but are passed
1280 to the method as a hash.
1281 clean
1283 {FILES => "*.xyz foo"}
1284 depend
1286 {ANY_TARGET => ANY_DEPENDENCY, ...}
1287 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1289 dist
1291 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1292 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1293 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1294 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1296 needed to tell make the target file of the compression. Setting
1297 DIST_CP to ln can be useful, if you need to preserve the timestamps
1298 on your files. DIST_CP can take the values 'cp', which copies the
1299 file, 'ln', which links the file, and 'best' which copies symbolic
1300 links and links the rest. Default is 'best'.
1301 dynamic_lib
1303 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1304 linkext
1306 {LINKTYPE => 'static', 'dynamic' or ''}
1307 NB: Extensions that have nothing but *.pm files had to say
1309 {LINKTYPE => ''}
1311 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1313 can be deleted safely. MakeMaker recognizes when there's nothing to
1314 be linked.
1315 macro
1317 {ANY_MACRO => ANY_VALUE, ...}
1318 postamble
1320 Anything put here will be passed to MY::postamble() if you have one.
1321 realclean
1323 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1324 test
1326 {TESTS => 't/*.t'}
1327 tool_autosplit
1329 {MAXLEN => 8}
1330 Overriding MakeMaker Methods
1332 If you cannot achieve the desired Makefile behaviour by specifying
1333 attributes you may define private subroutines in the Makefile.PL. Each
1334 subroutine returns the text it wishes to have written to the Makefile.
1335 To override a section of the Makefile you can either say:
1336 sub MY::c_o { "new literal text" }
1338 or you can edit the default by saying something like:
1340 package MY; # so that "SUPER" works right
1342 sub c_o {
1343 my $inherited = shift->SUPER::c_o(@_);
1344 $inherited =~ s/old text/new text/;
1345 $inherited;
1346 }
1347 If you are running experiments with embedding perl as a library into
1349 other applications, you might find MakeMaker is not sufficient. You'd
1350 better have a look at ExtUtils::Embed which is a collection of
1351 utilities for embedding.
1352 If you still need a different solution, try to develop another
1354 subroutine that fits your needs and submit the diffs to
1355 "makemaker@perl.org"
1356 For a complete description of all MakeMaker methods see
1358 ExtUtils::MM_Unix.
1359 Here is a simple example of how to add a new target to the generated
1361 Makefile:
1362 sub MY::postamble {
1364 return <<'MAKE_FRAG';
1365 $(MYEXTLIB): sdbm/Makefile
1366 cd sdbm && $(MAKE) all
1367 MAKE_FRAG
1369 }
1370 The End Of Cargo Cult Programming
1372 WriteMakefile() now does some basic sanity checks on its parameters to
1373 protect against typos and malformatted values. This means some things
1374 which happened to work in the past will now throw warnings and possibly
1375 produce internal errors.
1376 Some of the most common mistakes:
1378 "MAN3PODS => ' '"
1380 This is commonly used to suppress the creation of man pages.
1381 MAN3PODS takes a hash ref not a string, but the above worked by
1382 accident in old versions of MakeMaker.
1383 The correct code is "MAN3PODS => { }".
1385 Hintsfile support
1387 MakeMaker.pm uses the architecture-specific information from Config.pm.
1388 In addition it evaluates architecture specific hints files in a
1389 "hints/" directory. The hints files are expected to be named like their
1390 counterparts in "PERL_SRC/hints", but with an ".pl" file name extension
1391 (eg. "next_3_2.pl"). They are simply "eval"ed by MakeMaker within the
1392 WriteMakefile() subroutine, and can be used to execute commands as well
1393 as to include special variables. The rules which hintsfile is chosen
1394 are the same as in Configure.
1395 The hintsfile is eval()ed immediately after the arguments given to
1397 WriteMakefile are stuffed into a hash reference $self but before this
1398 reference becomes blessed. So if you want to do the equivalent to
1399 override or create an attribute you would say something like
1400 $self->{LIBS} = ['-ldbm -lucb -lc'];
1402 Distribution Support
1404 For authors of extensions MakeMaker provides several Makefile targets.
1405 Most of the support comes from the ExtUtils::Manifest module, where
1406 additional documentation can be found.
1407 make distcheck
1409 reports which files are below the build directory but not in the
1410 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck()
1411 for details)
1412 make skipcheck
1414 reports which files are skipped due to the entries in the
1415 "MANIFEST.SKIP" file (See ExtUtils::Manifest::skipcheck() for
1416 details)
1417 make distclean
1419 does a realclean first and then the distcheck. Note that this is
1420 not needed to build a new distribution as long as you are sure that
1421 the MANIFEST file is ok.
1422 make manifest
1424 rewrites the MANIFEST file, adding all remaining files found (See
1425 ExtUtils::Manifest::mkmanifest() for details)
1426 make distdir
1428 Copies all the files that are in the MANIFEST file to a newly
1429 created directory with the name "$(DISTNAME)-$(VERSION)". If that
1430 directory exists, it will be removed first.
1431 Additionally, it will create META.yml and META.json module meta-
1433 data file in the distdir and add this to the distdir's MANIFEST.
1434 You can shut this behavior off with the NO_META flag.
1435 make disttest
1437 Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1438 make test in that directory.
1439 make tardist
1441 First does a distdir. Then a command $(PREOP) which defaults to a
1442 null command, followed by $(TO_UNIX), which defaults to a null
1443 command under UNIX, and will convert files in distribution
1444 directory to UNIX format otherwise. Next it runs "tar" on that
1445 directory into a tarfile and deletes the directory. Finishes with a
1446 command $(POSTOP) which defaults to a null command.
1447 make dist
1449 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1450 make uutardist
1452 Runs a tardist first and uuencodes the tarfile.
1453 make shdist
1455 First does a distdir. Then a command $(PREOP) which defaults to a
1456 null command. Next it runs "shar" on that directory into a sharfile
1457 and deletes the intermediate directory again. Finishes with a
1458 command $(POSTOP) which defaults to a null command. Note: For
1459 shdist to work properly a "shar" program that can handle
1460 directories is mandatory.
1461 make zipdist
1463 First does a distdir. Then a command $(PREOP) which defaults to a
1464 null command. Runs "$(ZIP) $(ZIPFLAGS)" on that directory into a
1465 zipfile. Then deletes that directory. Finishes with a command
1466 $(POSTOP) which defaults to a null command.
1467 make ci
1469 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1470 Customization of the dist targets can be done by specifying a hash
1472 reference to the dist attribute of the WriteMakefile call. The
1473 following parameters are recognized:
1474 CI ('ci -u')
1476 COMPRESS ('gzip --best')
1477 POSTOP ('@ :')
1478 PREOP ('@ :')
1479 TO_UNIX (depends on the system)
1480 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1481 SHAR ('shar')
1482 SUFFIX ('.gz')
1483 TAR ('tar')
1484 TARFLAGS ('cvf')
1485 ZIP ('zip')
1486 ZIPFLAGS ('-r')
1487 An example:
1489 WriteMakefile(
1491 ...other options...
1492 dist => {
1493 COMPRESS => "bzip2",
1494 SUFFIX => ".bz2"
1495 }
1496 );
1497 Module Meta-Data (META and MYMETA)
1499 Long plaguing users of MakeMaker based modules has been the problem of
1500 getting basic information about the module out of the sources without
1501 running the Makefile.PL and doing a bunch of messy heuristics on the
1502 resulting Makefile. Over the years, it has become standard to keep
1503 this information in one or more CPAN Meta files distributed with each
1504 distribution.
1505 The original format of CPAN Meta files was YAML and the corresponding
1507 file was called META.yml. In 2010, version 2 of the CPAN::Meta::Spec
1508 was released, which mandates JSON format for the metadata in order to
1509 overcome certain compatibility issues between YAML serializers and to
1510 avoid breaking older clients unable to handle a new version of the
1511 spec. The CPAN::Meta library is now standard for accessing old and
1512 new-style Meta files.
1513 If CPAN::Meta is installed, MakeMaker will automatically generate
1515 META.json and META.yml files for you and add them to your MANIFEST as
1516 part of the 'distdir' target (and thus the 'dist' target). This is
1517 intended to seamlessly and rapidly populate CPAN with module meta-data.
1518 If you wish to shut this feature off, set the "NO_META"
1519 "WriteMakefile()" flag to true.
1520 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers
1522 agrees to use the CPAN Meta format to communicate post-configuration
1523 requirements between toolchain components. These files, MYMETA.json
1524 and MYMETA.yml, are generated when Makefile.PL generates a Makefile (if
1525 CPAN::Meta is installed). Clients like CPAN or CPANPLUS will read this
1526 files to see what prerequisites must be fulfilled before building or
1527 testing the distribution. If you with to shut this feature off, set
1528 the "NO_MYMETA" "WriteMakeFile()" flag to true.
1529 Disabling an extension
1531 If some events detected in Makefile.PL imply that there is no way to
1532 create the Module, but this is a normal state of things, then you can
1533 create a Makefile which does nothing, but succeeds on all the "usual"
1534 build targets. To do so, use
1535 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1537 WriteEmptyMakefile();
1538 instead of WriteMakefile().
1540 This may be useful if other modules expect this module to be built OK,
1542 as opposed to work OK (say, this system-dependent module builds in a
1543 subdirectory of some other distribution, or is listed as a dependency
1544 in a CPAN::Bundle, but the functionality is supported by different
1545 means on the current architecture).
1546 Other Handy Functions
1548 prompt
1549 my $value = prompt($message);
1550 my $value = prompt($message, $default);
1551 The "prompt()" function provides an easy way to request user input
1553 used to write a makefile. It displays the $message as a prompt for
1554 input. If a $default is provided it will be used as a default.
1555 The function returns the $value selected by the user.
1556 If "prompt()" detects that it is not running interactively and
1558 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1559 variable is set to true, the $default will be used without
1560 prompting. This prevents automated processes from blocking on user
1561 input.
1562 If no $default is provided an empty string will be used instead.
1564
1566 PERL_MM_OPT
1567 Command line options used by "MakeMaker->new()", and thus by
1568 "WriteMakefile()". The string is split on whitespace, and the
1569 result is processed before any actual command line arguments are
1570 processed.
1571 PERL_MM_USE_DEFAULT
1573 If set to a true value then MakeMaker's prompt function will always
1574 return the default without waiting for user input.
1575 PERL_CORE
1577 Same as the PERL_CORE parameter. The parameter overrides this.
1578
1580 Module::Build is a pure-Perl alternative to MakeMaker which does not
1581 rely on make or any other external utility. It is easier to extend to
1582 suit your needs.
1583 Module::Install is a wrapper around MakeMaker which adds features not
1585 normally available.
1586 ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1588 setup your distribution.
1589 CPAN::Meta and CPAN::Meta::Spec explain CPAN Meta files in detail.
1591
1593 Andy Dougherty "doughera@lafayette.edu", Andreas Koenig
1594 "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org". VMS support by
1595 Charles Bailey "bailey@newman.upenn.edu". OS/2 support by Ilya
1596 Zakharevich "ilya@math.ohio-state.edu".
1597 Currently maintained by Michael G Schwern "schwern@pobox.com"
1599 Send patches and ideas to "makemaker@perl.org".
1601 Send bug reports via http://rt.cpan.org/. Please send your generated
1603 Makefile along with your report.
1604 For more up-to-date information, see
1606 <https://metacpan.org/release/ExtUtils-MakeMaker>.
1607 Repository available at
1609 <https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
1610
1612 This program is free software; you can redistribute it and/or modify it
1613 under the same terms as Perl itself.
1614 See <http://www.perl.com/perl/misc/Artistic.html>
1616perl v5.16.3 2014-06-10 ExtUtils::MakeMaker(3)