1ExtUtils::MakeMaker(3pm)Perl Programmers Reference GuideExtUtils::MakeMaker(3pm)
2
6 ExtUtils::MakeMaker - Create a module Makefile
7
9 use ExtUtils::MakeMaker;
10 WriteMakefile( ATTRIBUTE => VALUE [, ...] );
12
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 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 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 How To Write A Makefile.PL
28 See ExtUtils::MakeMaker::Tutorial.
29 The long answer is the rest of the manpage :-)
31 Default Makefile Behaviour
33 The generated Makefile enables the user of the extension to invoke
34 perl Makefile.PL # optionally "perl Makefile.PL verbose"
36 make
37 make test # optionally set TEST_VERBOSE=1
38 make install # See below
39 The Makefile to be produced may be altered by adding arguments of the
41 form "KEY=VALUE". E.g.
42 perl Makefile.PL INSTALL_BASE=~
44 Other interesting targets in the generated Makefile are
46 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 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 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 If you'd like to see the raw output of your tests, set the
63 "TEST_VERBOSE" variable to true.
64 make test TEST_VERBOSE=1
66 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 If you want to debug some other testfile, set the "TEST_FILE" variable
73 thusly:
74 make testdb TEST_FILE=t/mytest.t
76 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 make testdb TESTDB_SW=-Dx
81 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 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 INSTALLDIRS set to
96 perl site vendor
97 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 The INSTALL... macros in turn default to their %Config
107 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
108 You can check the values of these variables on your system with
110 perl '-V:install.*'
112 And to check the sequence in which the library directories are searched
114 by perl, run
115 perl -le 'print join $/, @INC'
117 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 make install UNINST=1
126 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 To have everything installed in your home directory, do the following.
133 # Unix users, INSTALL_BASE=~ works fine
135 perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
136 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 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 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 INSTALL_BASE was added in 6.31.
154 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 # Unix users, PREFIX=~ works fine
160 perl Makefile.PL PREFIX=/path/to/your/home/dir
161 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 Another way to specify many INSTALL directories with a single parameter
170 is LIB.
171 perl Makefile.PL LIB=~/lib
173 This will install the module's architecture-independent files into
175 ~/lib, the architecture-dependent files into ~/lib/$archname.
176 Note, that in both cases the tilde expansion is done by MakeMaker, not
178 by perl by default, nor by make.
179 Conflicts between parameters LIB, PREFIX and the various INSTALL*
181 arguments are resolved so that:
182 · setting LIB overrides any setting of INSTALLPRIVLIB,
184 INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not
185 affected by PREFIX);
186 · 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 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 perl Makefile.PL;
197 make;
198 make test
199 make install
200 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 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 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
211 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
212 make
213 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 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 make perl
227 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 The binary can be installed into the directory where perl normally
237 resides on your machine with
238 make inst_perl
240 To produce a perl binary with a different name than "perl", either say
242 perl Makefile.PL MAP_TARGET=myperl
244 make myperl
245 make inst_perl
246 or say
248 perl Makefile.PL
250 make myperl MAP_TARGET=myperl
251 make inst_perl MAP_TARGET=myperl
252 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 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 Warning: the inst_perl: target will most probably overwrite your
261 existing perl binary. Use with care!
262 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 perl Makefile.PL LINKTYPE=static # recommended
268 or
270 make LINKTYPE=static # works on most systems
272 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 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 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 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 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 PERL_INC = $archlibexp/CORE
303 PERL_LIB = $privlibexp
304 PERL_ARCHLIB = $archlibexp
305 INST_LIB = ./blib/lib
306 INST_ARCHLIB = ./blib/arch
307 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 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 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 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 ABSTRACT
334 One line description of the module. Will be included in PPD file.
335 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 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 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 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
353 builds a PPD package that references a binary of the "Agent" package,
355 located in the "x86" directory relative to the PPD itself.
356 BUILD_REQUIRES
358 A hash of modules that are needed to build your module but not run
359 it.
360 This will go into the "build_requires" field of your META.yml.
362 The format is the same as PREREQ_PM.
364 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 CCFLAGS
370 String that will be included in the compiler call command line
371 between the arguments INC and OPTIMIZE.
372 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 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 CONFIGURE_REQUIRES
385 A hash of modules that are required to run Makefile.PL itself, but
386 not to run your distribution.
387 This will go into the "configure_requires" field of your META.yml.
389 Defaults to "{ "ExtUtils::MakeMaker" => 0 }"
391 The format is the same as PREREQ_PM.
393 DEFINE
395 Something like "-DHAVE_UNISTD_H"
396 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 This is primarily of use for people who repackage Perl modules.
405 NOTE: Due to the nature of make, it is important that you put the
407 trailing slash on your DESTDIR. ~/tmp/ not ~/tmp.
408 DIR
410 Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
411 in ext/SDBM_File
412 DISTNAME
414 A safe filename for the package.
415 Defaults to NAME above but with :: replaced with -.
417 For example, Foo::Bar becomes Foo-Bar.
419 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 Defaults to DISTNAME-VERSION.
426 For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
428 On some OS's where . has special meaning VERSION_SYM may be used in
430 place of VERSION.
431 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 {"$(NAME)" => ["boot_$(NAME)" ] }
441 e.g.
443 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
445 "NetconfigPtr" => [ 'DESTROY'] }
446 Please see the ExtUtils::Mksymlists documentation for more
448 information about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
449 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 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 This attribute may be most useful when specified as a string on the
461 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
462 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 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 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 Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
478 (Note: we couldn't use MAKEFILE because dmake uses this for something
480 else).
481 FULLPERL
483 Perl binary able to run this extension, load XS modules, etc...
484 FULLPERLRUN
486 Like PERLRUN, except it uses FULLPERL.
487 FULLPERLRUNINST
489 Like PERLRUNINST, except it uses FULLPERL.
490 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 H Ref to array of *.h file names. Similar to C.
498 IMPORTS
500 This attribute is used to specify names to be imported into the
501 extension. Takes a hash ref.
502 It is only used on OS/2 and Win32.
504 INC
506 Include file dirs eg: "-I/usr/5include -I/path/to/inc"
507 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 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 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 INSTALLARCHLIB
526 Used by 'make install', which copies files from INST_ARCHLIB to this
527 directory if INSTALLDIRS is set to perl.
528 INSTALLBIN
530 Directory to install binary files (e.g. tkperl) into if
531 INSTALLDIRS=perl.
532 INSTALLDIRS
534 Determines which of the sets of installation directories to choose:
535 perl, site or vendor. Defaults to site.
536 INSTALLMAN1DIR
538 INSTALLMAN3DIR
539 These directories get the man pages at 'make install' time if
540 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
541 If set to 'none', no man pages will be installed.
543 INSTALLPRIVLIB
545 Used by 'make install', which copies files from INST_LIB to this
546 directory if INSTALLDIRS is set to perl.
547 Defaults to $Config{installprivlib}.
549 INSTALLSCRIPT
551 Used by 'make install' which copies files from INST_SCRIPT to this
552 directory if INSTALLDIRS=perl.
553 INSTALLSITEARCH
555 Used by 'make install', which copies files from INST_ARCHLIB to this
556 directory if INSTALLDIRS is set to site (default).
557 INSTALLSITEBIN
559 Used by 'make install', which copies files from INST_BIN to this
560 directory if INSTALLDIRS is set to site (default).
561 INSTALLSITELIB
563 Used by 'make install', which copies files from INST_LIB to this
564 directory if INSTALLDIRS is set to site (default).
565 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 If set to 'none', no man pages will be installed.
573 INSTALLSITESCRIPT
575 Used by 'make install' which copies files from INST_SCRIPT to this
576 directory if INSTALLDIRS is set to site (default).
577 INSTALLVENDORARCH
579 Used by 'make install', which copies files from INST_ARCHLIB to this
580 directory if INSTALLDIRS is set to vendor.
581 INSTALLVENDORBIN
583 Used by 'make install', which copies files from INST_BIN to this
584 directory if INSTALLDIRS is set to vendor.
585 INSTALLVENDORLIB
587 Used by 'make install', which copies files from INST_LIB to this
588 directory if INSTALLDIRS is set to vendor.
589 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 If set to 'none', no man pages will be installed.
596 INSTALLVENDORSCRIPT
598 Used by 'make install' which copies files from INST_SCRIPT to this
599 directory if INSTALLDIRS is set to vendor.
600 INST_ARCHLIB
602 Same as INST_LIB for architecture dependent files.
603 INST_BIN
605 Directory to put real binary files during 'make'. These will be
606 copied to INSTALLBIN during 'make install'
607 INST_LIB
609 Directory where we put library files of this extension while building
610 it.
611 INST_MAN1DIR
613 Directory to hold the man pages at 'make' time
614 INST_MAN3DIR
616 Directory to hold the man pages at 'make' time
617 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 LD
625 Program to be used to link libraries for dynamic loading.
626 Defaults to $Config{ld}.
628 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 Defaults to $Config{lddlflags}.
635 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 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 LIBPERL_A
649 The filename of the perllibrary that will be used together with this
650 extension. Defaults to libperl.a.
651 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 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
657 Mind, that any element of the array contains a complete set of
659 arguments for the ld command. So do not specify
660 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
662 See ODBM_File/Makefile.PL for an example, where an array is needed.
664 If you specify a scalar as in
665 'LIBS' => "-ltcl -ltk -lX11"
667 MakeMaker will turn it into an array with one element.
669 LICENSE
671 The licensing terms of your distribution. Generally its "perl" for
672 the same license as Perl itself.
673 See Module::Build::API for the list of options.
675 Defaults to "unknown".
677 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 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 MakeMaker also honors the MAKE environment variable. This parameter
688 takes precedent.
689 Currently the only significant values are 'dmake' and 'nmake' for
691 Windows users.
692 Defaults to $Config{make}.
694 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 MAKEFILE_OLD
701 When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
702 backed up at this location.
703 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
705 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 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 MAN1PODS => {
717 'doc/command.pod' => 'blib/man1/command.1',
718 'scripts/script.pl' => 'blib/man1/script.1',
719 }
720 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 Example similar to MAN1PODS.
729 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 META_ADD
735 META_MERGE
736 A hashrefs of items to add to the META.yml.
737 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 Unless you want to override the defaults, prefer META_MERGE so as to
743 get the advantage of any future defaults.
744 MIN_PERL_VERSION
746 The minimum required version of Perl for this distribution.
747 Either 5.006001 or 5.6.1 format is acceptable.
749 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 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 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 NOECHO
766 Command so make does not print the literal commands its running.
767 By setting it to an empty string you can generate a Makefile that
769 prints all commands. Mainly used in debugging MakeMaker itself.
770 Defaults to "@".
772 NORECURS
774 Boolean. Attribute to inhibit descending into subdirectories.
775 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 Defaults to false.
781 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 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 (Where BASEEXT is the last component of NAME, and OBJ_EXT is
794 $Config{obj_ext}.)
795 OPTIMIZE
797 Defaults to "-O". Set it to "-g" to turn debugging on. The flag is
798 passed to subdirectory makes.
799 PERL
801 Perl binary for tasks that can be done by miniperl
802 PERL_CORE
804 Set only when MakeMaker is building the extensions of the Perl core
805 distribution.
806 PERLMAINCC
808 The call to the program that is able to compile perlmain.c. Defaults
809 to $(CC).
810 PERL_ARCHLIB
812 Same as for PERL_LIB, but for architecture dependent files.
813 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 PERL_LIB
819 Directory containing the Perl library to use.
820 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 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 · with bugs in memory allocations which are caught by Perl's
832 malloc();
833 · which interact with the memory allocator in other ways than via
835 malloc(), realloc(), free(), calloc(), sbrk() and brk();
836 · which rely on special alignment which is not provided by Perl's
838 malloc().
839 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 PERLPREFIX
846 Directory under which core modules are to be installed.
847 Defaults to $Config{installprefixexp} falling back to
849 $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
850 $Config{installprefixexp} not exist.
851 Overridden by PREFIX.
853 PERLRUN
855 Use this instead of $(PERL) when you wish to run perl. It will set
856 up extra necessary flags for you.
857 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 PERL_SRC
864 Directory containing the Perl source code (use of this should be
865 avoided, it may be undefined)
866 PERM_DIR
868 Desired permission for directories. Defaults to 755.
869 PERM_RW
871 Desired permission for read/writable files. Defaults to 644.
872 PERM_RWX
874 Desired permission for executable files. Defaults to 755.
875 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 perl foo.PL foo
883 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 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
890 Would run bin/foobar.PL like this:
892 perl bin/foobar.PL bin/foobar
894 If multiple files from one program are desired an array ref can be
896 used.
897 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
899 In this case the program will be run multiple times using each target
901 file.
902 perl bin/foobar.PL bin/foobar1
904 perl bin/foobar.PL bin/foobar2
905 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 PM
914 Hashref of .pm files and *.pl files to be installed. e.g.
915 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
917 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 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 (Where BASEEXT is the last component of NAME.)
930 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 Great care is necessary when defining the command if quoting needs to
938 be done. For instance, you would need to say:
939 {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
941 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 PM_FILTER = grep -v \"^\#\"
950 Without the \\ before the #, we'd have the start of a Makefile
952 comment, and the macro would be incorrectly defined.
953 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 perl Makefile.PL POLLUTE=1
962 Please inform the module author if this is necessary to successfully
964 install a module under 5.6 or later.
965 PPM_INSTALL_EXEC
967 Name of the executable used to run "PPM_INSTALL_SCRIPT" below. (e.g.
968 perl)
969 PPM_INSTALL_SCRIPT
971 Name of the script that gets executed by the Perl Package Manager
972 after the installation of a package.
973 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 If you specify LIB or any INSTALL* variables they will not be
982 effected by the PREFIX.
983 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 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 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 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 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 This will go into the "requires" field of your META.yml.
1011 PREREQ_PM => {
1013 # Require Test::More at least 0.47
1014 "Test::More" => "0.47",
1015 # Require any version of Acme::Buffy
1017 "Acme::Buffy" => 0,
1018 }
1019 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 $PREREQ_PM = {
1026 'A::B' => Vers1,
1027 'C::D' => Vers2,
1028 ...
1029 };
1030 If a distribution defines a minimal required perl version, this is
1032 added to the output as an additional line of the form:
1033 $MIN_PERL_VERSION = '5.008001';
1035 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES
1037 hasref.
1038 PRINT_PREREQ
1040 RedHatism for "PREREQ_PRINT". The output format is different,
1041 though:
1042 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1044 A minimal required perl version, if present, will look like this:
1046 perl(perl)>=5.008001
1048 SITEPREFIX
1050 Like PERLPREFIX, but only for the site install locations.
1051 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 Overridable by PREFIX
1057 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 Note that you need to install the Module::Signature module to perform
1064 this operation.
1065 Defaults to false.
1067 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 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 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 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 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 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 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 VENDORPREFIX
1121 Like PERLPREFIX, but only for the vendor install locations.
1122 Defaults to $Config{vendorprefixexp}.
1124 Overridable by PREFIX
1126 VERBINST
1128 If true, make install will be verbose
1129 VERSION
1131 Your version number for distributing the package. This defaults to
1132 0.1.
1133 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 something like a $VERSION assignment or "package Name
1140 VERSION" will be used. The following lines will be parsed o.k.:
1141 # Good
1143 package Foo::Bar 1.23; # 1.23
1144 $VERSION = '1.00'; # 1.00
1145 *VERSION = \'1.01'; # 1.01
1146 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
1147 $FOO::VERSION = '1.10'; # 1.10
1148 *FOO::VERSION = \'1.11'; # 1.11
1149 but these will fail:
1151 # Bad
1153 my $VERSION = '1.01';
1154 local $VERSION = '1.02';
1155 local $FOO::VERSION = '1.30';
1156 "Version strings" are incompatible should not be used.
1158 # Bad
1160 $VERSION = 1.2.3;
1161 $VERSION = v1.2.3;
1162 version objects are fine. As of MakeMaker 6.35 version.pm will be
1164 automatically loaded, but you must declare the dependency on
1165 version.pm. For compatibility with older MakeMaker you should load
1166 on the same line as $VERSION is declared.
1167 # All on one line
1169 use version; our $VERSION = qv(1.2.3);
1170 (Putting "my" or "local" on the preceding line will work o.k.)
1172 The file named in VERSION_FROM is not added as a dependency to
1174 Makefile. This is not really correct, but it would be a major pain
1175 during development to have to rewrite the Makefile for any smallish
1176 change in that file. If you want to make sure that the Makefile
1177 contains the correct VERSION macro after any change of the file, you
1178 would have to do something like
1179 depend => { Makefile => '$(VERSION_FROM)' }
1181 See attribute "depend" below.
1183 VERSION_SYM
1185 A sanitized VERSION with . replaced by _. For places where . has
1186 special meaning (some filesystems, RCS labels, etc...)
1187 XS
1189 Hashref of .xs files. MakeMaker will default this. e.g.
1190 {'name_of_file.xs' => 'name_of_file.c'}
1192 The .c files will automatically be included in the list of files
1194 deleted by a make clean.
1195 XSOPT
1197 String of options to pass to xsubpp. This might include "-C++" or
1198 "-extern". Do not include typemaps here; the TYPEMAP parameter
1199 exists for that purpose.
1200 XSPROTOARG
1202 May be set to an empty string, which is identical to "-prototypes",
1203 or "-noprototypes". See the xsubpp documentation for details.
1204 MakeMaker defaults to the empty string.
1205 XS_VERSION
1207 Your version number for the .xs file of this package. This defaults
1208 to the value of the VERSION attribute.
1209 Additional lowercase attributes
1211 can be used to pass parameters to the methods which implement that part
1212 of the Makefile. Parameters are specified as a hash ref but are passed
1213 to the method as a hash.
1214 clean
1216 {FILES => "*.xyz foo"}
1217 depend
1219 {ANY_TARGET => ANY_DEPENDENCY, ...}
1220 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1222 dist
1224 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1225 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1226 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1227 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1229 needed to tell make the target file of the compression. Setting
1230 DIST_CP to ln can be useful, if you need to preserve the timestamps
1231 on your files. DIST_CP can take the values 'cp', which copies the
1232 file, 'ln', which links the file, and 'best' which copies symbolic
1233 links and links the rest. Default is 'best'.
1234 dynamic_lib
1236 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1237 linkext
1239 {LINKTYPE => 'static', 'dynamic' or ''}
1240 NB: Extensions that have nothing but *.pm files had to say
1242 {LINKTYPE => ''}
1244 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1246 can be deleted safely. MakeMaker recognizes when there's nothing to
1247 be linked.
1248 macro
1250 {ANY_MACRO => ANY_VALUE, ...}
1251 postamble
1253 Anything put here will be passed to MY::postamble() if you have one.
1254 realclean
1256 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1257 test
1259 {TESTS => 't/*.t'}
1260 tool_autosplit
1262 {MAXLEN => 8}
1263 Overriding MakeMaker Methods
1265 If you cannot achieve the desired Makefile behaviour by specifying
1266 attributes you may define private subroutines in the Makefile.PL. Each
1267 subroutine returns the text it wishes to have written to the Makefile.
1268 To override a section of the Makefile you can either say:
1269 sub MY::c_o { "new literal text" }
1271 or you can edit the default by saying something like:
1273 package MY; # so that "SUPER" works right
1275 sub c_o {
1276 my $inherited = shift->SUPER::c_o(@_);
1277 $inherited =~ s/old text/new text/;
1278 $inherited;
1279 }
1280 If you are running experiments with embedding perl as a library into
1282 other applications, you might find MakeMaker is not sufficient. You'd
1283 better have a look at ExtUtils::Embed which is a collection of
1284 utilities for embedding.
1285 If you still need a different solution, try to develop another
1287 subroutine that fits your needs and submit the diffs to
1288 "makemaker@perl.org"
1289 For a complete description of all MakeMaker methods see
1291 ExtUtils::MM_Unix.
1292 Here is a simple example of how to add a new target to the generated
1294 Makefile:
1295 sub MY::postamble {
1297 return <<'MAKE_FRAG';
1298 $(MYEXTLIB): sdbm/Makefile
1299 cd sdbm && $(MAKE) all
1300 MAKE_FRAG
1302 }
1303 The End Of Cargo Cult Programming
1305 WriteMakefile() now does some basic sanity checks on its parameters to
1306 protect against typos and malformatted values. This means some things
1307 which happened to work in the past will now throw warnings and possibly
1308 produce internal errors.
1309 Some of the most common mistakes:
1311 "MAN3PODS => ' '"
1313 This is commonly used to suppress the creation of man pages.
1314 MAN3PODS takes a hash ref not a string, but the above worked by
1315 accident in old versions of MakeMaker.
1316 The correct code is "MAN3PODS => { }".
1318 Hintsfile support
1320 MakeMaker.pm uses the architecture specific information from Config.pm.
1321 In addition it evaluates architecture specific hints files in a
1322 "hints/" directory. The hints files are expected to be named like their
1323 counterparts in "PERL_SRC/hints", but with an ".pl" file name extension
1324 (eg. "next_3_2.pl"). They are simply "eval"ed by MakeMaker within the
1325 WriteMakefile() subroutine, and can be used to execute commands as well
1326 as to include special variables. The rules which hintsfile is chosen
1327 are the same as in Configure.
1328 The hintsfile is eval()ed immediately after the arguments given to
1330 WriteMakefile are stuffed into a hash reference $self but before this
1331 reference becomes blessed. So if you want to do the equivalent to
1332 override or create an attribute you would say something like
1333 $self->{LIBS} = ['-ldbm -lucb -lc'];
1335 Distribution Support
1337 For authors of extensions MakeMaker provides several Makefile targets.
1338 Most of the support comes from the ExtUtils::Manifest module, where
1339 additional documentation can be found.
1340 make distcheck
1342 reports which files are below the build directory but not in the
1343 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck()
1344 for details)
1345 make skipcheck
1347 reports which files are skipped due to the entries in the
1348 "MANIFEST.SKIP" file (See ExtUtils::Manifest::skipcheck() for
1349 details)
1350 make distclean
1352 does a realclean first and then the distcheck. Note that this is
1353 not needed to build a new distribution as long as you are sure that
1354 the MANIFEST file is ok.
1355 make manifest
1357 rewrites the MANIFEST file, adding all remaining files found (See
1358 ExtUtils::Manifest::mkmanifest() for details)
1359 make distdir
1361 Copies all the files that are in the MANIFEST file to a newly
1362 created directory with the name "$(DISTNAME)-$(VERSION)". If that
1363 directory exists, it will be removed first.
1364 Additionally, it will create a META.yml module meta-data file in
1366 the distdir and add this to the distdir's MANIFEST. You can shut
1367 this behavior off with the NO_META flag.
1368 make disttest
1370 Makes a distdir first, and runs a "perl Makefile.PL", a make, and a
1371 make test in that directory.
1372 make tardist
1374 First does a distdir. Then a command $(PREOP) which defaults to a
1375 null command, followed by $(TO_UNIX), which defaults to a null
1376 command under UNIX, and will convert files in distribution
1377 directory to UNIX format otherwise. Next it runs "tar" on that
1378 directory into a tarfile and deletes the directory. Finishes with a
1379 command $(POSTOP) which defaults to a null command.
1380 make dist
1382 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1383 make uutardist
1385 Runs a tardist first and uuencodes the tarfile.
1386 make shdist
1388 First does a distdir. Then a command $(PREOP) which defaults to a
1389 null command. Next it runs "shar" on that directory into a sharfile
1390 and deletes the intermediate directory again. Finishes with a
1391 command $(POSTOP) which defaults to a null command. Note: For
1392 shdist to work properly a "shar" program that can handle
1393 directories is mandatory.
1394 make zipdist
1396 First does a distdir. Then a command $(PREOP) which defaults to a
1397 null command. Runs "$(ZIP) $(ZIPFLAGS)" on that directory into a
1398 zipfile. Then deletes that directory. Finishes with a command
1399 $(POSTOP) which defaults to a null command.
1400 make ci
1402 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
1403 Customization of the dist targets can be done by specifying a hash
1405 reference to the dist attribute of the WriteMakefile call. The
1406 following parameters are recognized:
1407 CI ('ci -u')
1409 COMPRESS ('gzip --best')
1410 POSTOP ('@ :')
1411 PREOP ('@ :')
1412 TO_UNIX (depends on the system)
1413 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
1414 SHAR ('shar')
1415 SUFFIX ('.gz')
1416 TAR ('tar')
1417 TARFLAGS ('cvf')
1418 ZIP ('zip')
1419 ZIPFLAGS ('-r')
1420 An example:
1422 WriteMakefile(
1424 ...other options...
1425 dist => {
1426 COMPRESS => "bzip2",
1427 SUFFIX => ".bz2"
1428 }
1429 );
1430 Module Meta-Data
1432 Long plaguing users of MakeMaker based modules has been the problem of
1433 getting basic information about the module out of the sources without
1434 running the Makefile.PL and doing a bunch of messy heuristics on the
1435 resulting Makefile. To this end a simple module meta-data file has
1436 been introduced, META.yml.
1437 META.yml is a YAML document (see http://www.yaml.org) containing basic
1439 information about the module (name, version, prerequisites...) in an
1440 easy to read format. The format is developed and defined by the
1441 Module::Build developers (see
1442 http://module-build.sourceforge.net/META-spec.html)
1443 MakeMaker will automatically generate a META.yml file for you and add
1445 it to your MANIFEST as part of the 'distdir' target (and thus the
1446 'dist' target). This is intended to seamlessly and rapidly populate
1447 CPAN with module meta-data. If you wish to shut this feature off, set
1448 the "NO_META" "WriteMakefile()" flag to true.
1449 Disabling an extension
1451 If some events detected in Makefile.PL imply that there is no way to
1452 create the Module, but this is a normal state of things, then you can
1453 create a Makefile which does nothing, but succeeds on all the "usual"
1454 build targets. To do so, use
1455 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
1457 WriteEmptyMakefile();
1458 instead of WriteMakefile().
1460 This may be useful if other modules expect this module to be built OK,
1462 as opposed to work OK (say, this system-dependent module builds in a
1463 subdirectory of some other distribution, or is listed as a dependency
1464 in a CPAN::Bundle, but the functionality is supported by different
1465 means on the current architecture).
1466 Other Handy Functions
1468 prompt
1469 my $value = prompt($message);
1470 my $value = prompt($message, $default);
1471 The "prompt()" function provides an easy way to request user input
1473 used to write a makefile. It displays the $message as a prompt for
1474 input. If a $default is provided it will be used as a default.
1475 The function returns the $value selected by the user.
1476 If "prompt()" detects that it is not running interactively and
1478 there is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment
1479 variable is set to true, the $default will be used without
1480 prompting. This prevents automated processes from blocking on user
1481 input.
1482 If no $default is provided an empty string will be used instead.
1484
1486 PERL_MM_OPT
1487 Command line options used by "MakeMaker->new()", and thus by
1488 "WriteMakefile()". The string is split on whitespace, and the
1489 result is processed before any actual command line arguments are
1490 processed.
1491 PERL_MM_USE_DEFAULT
1493 If set to a true value then MakeMaker's prompt function will always
1494 return the default without waiting for user input.
1495 PERL_CORE
1497 Same as the PERL_CORE parameter. The parameter overrides this.
1498
1500 Module::Build is a pure-Perl alternative to MakeMaker which does not
1501 rely on make or any other external utility. It is easier to extend to
1502 suit your needs.
1503 Module::Install is a wrapper around MakeMaker which adds features not
1505 normally available.
1506 ExtUtils::ModuleMaker and Module::Starter are both modules to help you
1508 setup your distribution.
1509
1511 Andy Dougherty "doughera@lafayette.edu", Andreas Koenig
1512 "andreas.koenig@mind.de", Tim Bunce "timb@cpan.org". VMS support by
1513 Charles Bailey "bailey@newman.upenn.edu". OS/2 support by Ilya
1514 Zakharevich "ilya@math.ohio-state.edu".
1515 Currently maintained by Michael G Schwern "schwern@pobox.com"
1517 Send patches and ideas to "makemaker@perl.org".
1519 Send bug reports via http://rt.cpan.org/. Please send your generated
1521 Makefile along with your report.
1522 For more up-to-date information, see <http://www.makemaker.org>.
1524
1526 This program is free software; you can redistribute it and/or modify it
1527 under the same terms as Perl itself.
1528 See <http://www.perl.com/perl/misc/Artistic.html>
1530perl v5.12.4 2011-11-04 ExtUtils::MakeMaker(3pm)