1NAME
2
3 Module::Build - Build and install Perl modules
4
5SYNOPSIS
6
7 Standard process for building & installing modules:
8
9 perl Build.PL
10 ./Build
11 ./Build test
12 ./Build install
13
14 Or, if you're on a platform (like DOS or Windows) that doesn't require
15 the "./" notation, you can do this:
16
17 perl Build.PL
18 Build
19 Build test
20 Build install
21
22DESCRIPTION
23
24 Module::Build is a system for building, testing, and installing Perl
25 modules. It is meant to be an alternative to ExtUtils::MakeMaker.
26 Developers may alter the behavior of the module through subclassing. It
27 also does not require a make on your system - most of the Module::Build
28 code is pure-perl and written in a very cross-platform way.
29
30 See "COMPARISON" for more comparisons between Module::Build and other
31 installer tools.
32
33 To install Module::Build, and any other module that uses Module::Build
34 for its installation process, do the following:
35
36 perl Build.PL # 'Build.PL' script creates the 'Build' script
37 ./Build # Need ./ to ensure we're using this "Build" script
38 ./Build test # and not another one that happens to be in the PATH
39 ./Build install
40
41 This illustrates initial configuration and the running of three
42 'actions'. In this case the actions run are 'build' (the default
43 action), 'test', and 'install'. Other actions defined so far include:
44
45 <action_list>
46
47 You can run the 'help' action for a complete list of actions.
48
49GUIDE TO DOCUMENTATION
50
51 The documentation for Module::Build is broken up into sections:
52
53 General Usage (Module::Build)
54
55 This is the document you are currently reading. It describes basic
56 usage and background information. Its main purpose is to assist the
57 user who wants to learn how to invoke and control Module::Build
58 scripts at the command line.
59
60 Authoring Reference (Module::Build::Authoring)
61
62 This document describes the structure and organization of
63 Module::Build, and the relevant concepts needed by authors who are
64 writing Build.PL scripts for a distribution or controlling
65 Module::Build processes programmatically.
66
67 API Reference (Module::Build::API)
68
69 This is a reference to the Module::Build API.
70
71 Cookbook (Module::Build::Cookbook)
72
73 This document demonstrates how to accomplish many common tasks. It
74 covers general command line usage and authoring of Build.PL scripts.
75 Includes working examples.
76
77ACTIONS
78
79 There are some general principles at work here. First, each task when
80 building a module is called an "action". These actions are listed
81 above; they correspond to the building, testing, installing, packaging,
82 etc., tasks.
83
84 Second, arguments are processed in a very systematic way. Arguments are
85 always key=value pairs. They may be specified at perl Build.PL time
86 (i.e. perl Build.PL destdir=/my/secret/place), in which case their
87 values last for the lifetime of the Build script. They may also be
88 specified when executing a particular action (i.e. Build test
89 verbose=1), in which case their values last only for the lifetime of
90 that command. Per-action command line parameters take precedence over
91 parameters specified at perl Build.PL time.
92
93 The build process also relies heavily on the Config.pm module. If the
94 user wishes to override any of the values in Config.pm, she may specify
95 them like so:
96
97 perl Build.PL --config cc=gcc --config ld=gcc
98
99 The following build actions are provided by default.
100
101 build
102
103 [version 0.01]
104
105 If you run the Build script without any arguments, it runs the build
106 action, which in turn runs the code and docs actions.
107
108 This is analogous to the MakeMaker make all target.
109
110 clean
111
112 [version 0.01]
113
114 This action will clean up any files that the build process may have
115 created, including the blib/ directory (but not including the _build/
116 directory and the Build script itself).
117
118 code
119
120 [version 0.20]
121
122 This action builds your code base.
123
124 By default it just creates a blib/ directory and copies any .pm and
125 .pod files from your lib/ directory into the blib/ directory. It also
126 compiles any .xs files from lib/ and places them in blib/. Of course,
127 you need a working C compiler (probably the same one that built perl
128 itself) for the compilation to work properly.
129
130 The code action also runs any .PL files in your lib/ directory.
131 Typically these create other files, named the same but without the
132 .PL ending. For example, a file lib/Foo/Bar.pm.PL could create the
133 file lib/Foo/Bar.pm. The .PL files are processed first, so any .pm
134 files (or other kinds that we deal with) will get copied correctly.
135
136 config_data
137
138 [version 0.26]
139
140 ...
141
142 diff
143
144 [version 0.14]
145
146 This action will compare the files about to be installed with their
147 installed counterparts. For .pm and .pod files, a diff will be shown
148 (this currently requires a 'diff' program to be in your PATH). For
149 other files like compiled binary files, we simply report whether they
150 differ.
151
152 A flags parameter may be passed to the action, which will be passed
153 to the 'diff' program. Consult your 'diff' documentation for the
154 parameters it will accept - a good one is -u:
155
156 ./Build diff flags=-u
157
158 dist
159
160 [version 0.02]
161
162 This action is helpful for module authors who want to package up
163 their module for source distribution through a medium like CPAN. It
164 will create a tarball of the files listed in MANIFEST and compress
165 the tarball using GZIP compression.
166
167 By default, this action will use the Archive::Tar module. However,
168 you can force it to use binary "tar" and "gzip" executables by
169 supplying an explicit tar (and optional gzip) parameter:
170
171 ./Build dist --tar C:\path\to\tar.exe --gzip C:\path\to\zip.exe
172
173 distcheck
174
175 [version 0.05]
176
177 Reports which files are in the build directory but not in the
178 MANIFEST file, and vice versa. (See "manifest" for details.)
179
180 distclean
181
182 [version 0.05]
183
184 Performs the 'realclean' action and then the 'distcheck' action.
185
186 distdir
187
188 [version 0.05]
189
190 Creates a "distribution directory" named $dist_name-$dist_version (if
191 that directory already exists, it will be removed first), then copies
192 all the files listed in the MANIFEST file to that directory. This
193 directory is what the distribution tarball is created from.
194
195 distinstall
196
197 [version 0.37]
198
199 Performs the 'distdir' action, then switches into that directory and
200 runs a perl Build.PL, followed by the 'build' and 'install' actions
201 in that directory. Use PERL_MB_OPT or .modulebuildrc to set options
202 that should be applied during subprocesses
203
204 distmeta
205
206 [version 0.21]
207
208 Creates the META.yml file that describes the distribution.
209
210 META.yml is a file containing various bits of metadata about the
211 distribution. The metadata includes the distribution name, version,
212 abstract, prerequisites, license, and various other data about the
213 distribution. This file is created as META.yml in a simplified YAML
214 format.
215
216 META.yml file must also be listed in MANIFEST - if it's not, a
217 warning will be issued.
218
219 The current version of the META.yml specification can be found on
220 CPAN as CPAN::Meta::Spec.
221
222 distsign
223
224 [version 0.16]
225
226 Uses Module::Signature to create a SIGNATURE file for your
227 distribution, and adds the SIGNATURE file to the distribution's
228 MANIFEST.
229
230 disttest
231
232 [version 0.05]
233
234 Performs the 'distdir' action, then switches into that directory and
235 runs a perl Build.PL, followed by the 'build' and 'test' actions in
236 that directory. Use PERL_MB_OPT or .modulebuildrc to set options that
237 should be applied during subprocesses
238
239 docs
240
241 [version 0.20]
242
243 This will generate documentation (e.g. Unix man pages and HTML
244 documents) for any installable items under blib/ that contain POD. If
245 there are no bindoc or libdoc installation targets defined (as will
246 be the case on systems that don't support Unix manpages) no action is
247 taken for manpages. If there are no binhtml or libhtml installation
248 targets defined no action is taken for HTML documents.
249
250 fakeinstall
251
252 [version 0.02]
253
254 This is just like the install action, but it won't actually do
255 anything, it will just report what it would have done if you had
256 actually run the install action.
257
258 help
259
260 [version 0.03]
261
262 This action will simply print out a message that is meant to help you
263 use the build process. It will show you a list of available build
264 actions too.
265
266 With an optional argument specifying an action name (e.g. Build help
267 test), the 'help' action will show you any POD documentation it can
268 find for that action.
269
270 html
271
272 [version 0.26]
273
274 This will generate HTML documentation for any binary or library files
275 under blib/ that contain POD. The HTML documentation will only be
276 installed if the install paths can be determined from values in
277 Config.pm. You can also supply or override install paths on the
278 command line by specifying install_path values for the binhtml and/or
279 libhtml installation targets.
280
281 With an optional html_links argument set to a false value, you can
282 skip the search for other documentation to link to, because that can
283 waste a lot of time if there aren't any links to generate anyway:
284
285 ./Build html --html_links 0
286
287 install
288
289 [version 0.01]
290
291 This action will use ExtUtils::Install to install the files from
292 blib/ into the system. See "INSTALL PATHS" for details about how
293 Module::Build determines where to install things, and how to
294 influence this process.
295
296 If you want the installation process to look around in @INC for other
297 versions of the stuff you're installing and try to delete it, you can
298 use the uninst parameter, which tells ExtUtils::Install to do so:
299
300 ./Build install uninst=1
301
302 This can be a good idea, as it helps prevent multiple versions of a
303 module from being present on your system, which can be a confusing
304 situation indeed.
305
306 installdeps
307
308 [version 0.36]
309
310 This action will use the cpan_client parameter as a command to
311 install missing prerequisites. You will be prompted whether to
312 install optional dependencies.
313
314 The cpan_client option defaults to 'cpan' but can be set as an option
315 or in .modulebuildrc. It must be a shell command that takes a list of
316 modules to install as arguments (e.g. 'cpanp -i' for CPANPLUS). If
317 the program part is a relative path (e.g. 'cpan' or 'cpanp'), it will
318 be located relative to the perl program that executed Build.PL.
319
320 /opt/perl/5.8.9/bin/perl Build.PL
321 ./Build installdeps --cpan_client 'cpanp -i'
322 # installs to 5.8.9
323
324 manifest
325
326 [version 0.05]
327
328 This is an action intended for use by module authors, not people
329 installing modules. It will bring the MANIFEST up to date with the
330 files currently present in the distribution. You may use a
331 MANIFEST.SKIP file to exclude certain files or directories from
332 inclusion in the MANIFEST. MANIFEST.SKIP should contain a bunch of
333 regular expressions, one per line. If a file in the distribution
334 directory matches any of the regular expressions, it won't be
335 included in the MANIFEST.
336
337 The following is a reasonable MANIFEST.SKIP starting point, you can
338 add your own stuff to it:
339
340 ^_build
341 ^Build$
342 ^blib
343 ~$
344 \.bak$
345 ^MANIFEST\.SKIP$
346 CVS
347
348 See the "distcheck" and "skipcheck" actions if you want to find out
349 what the manifest action would do, without actually doing anything.
350
351 manifest_skip
352
353 [version 0.3608]
354
355 This is an action intended for use by module authors, not people
356 installing modules. It will generate a boilerplate MANIFEST.SKIP file
357 if one does not already exist.
358
359 manpages
360
361 [version 0.28]
362
363 This will generate man pages for any binary or library files under
364 blib/ that contain POD. The man pages will only be installed if the
365 install paths can be determined from values in Config.pm. You can
366 also supply or override install paths by specifying there values on
367 the command line with the bindoc and libdoc installation targets.
368
369 pardist
370
371 [version 0.2806]
372
373 Generates a PAR binary distribution for use with PAR or PAR::Dist.
374
375 It requires that the PAR::Dist module (version 0.17 and up) is
376 installed on your system.
377
378 ppd
379
380 [version 0.20]
381
382 Build a PPD file for your distribution.
383
384 This action takes an optional argument codebase which is used in the
385 generated PPD file to specify the (usually relative) URL of the
386 distribution. By default, this value is the distribution name without
387 any path information.
388
389 Example:
390
391 ./Build ppd --codebase "MSWin32-x86-multi-thread/Module-Build-0.21.tar.gz"
392
393 ppmdist
394
395 [version 0.23]
396
397 Generates a PPM binary distribution and a PPD description file. This
398 action also invokes the ppd action, so it can accept the same
399 codebase argument described under that action.
400
401 This uses the same mechanism as the dist action to tar & zip its
402 output, so you can supply tar and/or gzip parameters to affect the
403 result.
404
405 prereq_data
406
407 [version 0.32]
408
409 This action prints out a Perl data structure of all prerequisites and
410 the versions required. The output can be loaded again using eval().
411 This can be useful for external tools that wish to query a Build
412 script for prerequisites.
413
414 prereq_report
415
416 [version 0.28]
417
418 This action prints out a list of all prerequisites, the versions
419 required, and the versions actually installed. This can be useful for
420 reviewing the configuration of your system prior to a build, or when
421 compiling data to send for a bug report.
422
423 pure_install
424
425 [version 0.28]
426
427 This action is identical to the install action. In the future,
428 though, when install starts writing to the file
429 $(INSTALLARCHLIB)/perllocal.pod, pure_install won't, and that will be
430 the only difference between them.
431
432 realclean
433
434 [version 0.01]
435
436 This action is just like the clean action, but also removes the
437 _build directory and the Build script. If you run the realclean
438 action, you are essentially starting over, so you will have to
439 re-create the Build script again.
440
441 retest
442
443 [version 0.2806]
444
445 This is just like the test action, but doesn't actually build the
446 distribution first, and doesn't add blib/ to the load path, and
447 therefore will test against a previously installed version of the
448 distribution. This can be used to verify that a certain installed
449 distribution still works, or to see whether newer versions of a
450 distribution still pass the old regression tests, and so on.
451
452 skipcheck
453
454 [version 0.05]
455
456 Reports which files are skipped due to the entries in the
457 MANIFEST.SKIP file (See "manifest" for details)
458
459 test
460
461 [version 0.01]
462
463 This will use Test::Harness or TAP::Harness to run any regression
464 tests and report their results. Tests can be defined in the standard
465 places: a file called test.pl in the top-level directory, or several
466 files ending with .t in a t/ directory.
467
468 If you want tests to be 'verbose', i.e. show details of test
469 execution rather than just summary information, pass the argument
470 verbose=1.
471
472 If you want to run tests under the perl debugger, pass the argument
473 debugger=1.
474
475 If you want to have Module::Build find test files with different file
476 name extensions, pass the test_file_exts argument with an array of
477 extensions, such as [qw( .t .s .z )].
478
479 If you want test to be run by TAP::Harness, rather than
480 Test::Harness, pass the argument tap_harness_args as an array
481 reference of arguments to pass to the TAP::Harness constructor.
482
483 In addition, if a file called visual.pl exists in the top-level
484 directory, this file will be executed as a Perl script and its output
485 will be shown to the user. This is a good place to put speed tests or
486 other tests that don't use the Test::Harness format for output.
487
488 To override the choice of tests to run, you may pass a test_files
489 argument whose value is a whitespace-separated list of test scripts
490 to run. This is especially useful in development, when you only want
491 to run a single test to see whether you've squashed a certain bug
492 yet:
493
494 ./Build test --test_files t/something_failing.t
495
496 You may also pass several test_files arguments separately:
497
498 ./Build test --test_files t/one.t --test_files t/two.t
499
500 or use a glob()-style pattern:
501
502 ./Build test --test_files 't/01-*.t'
503
504 testall
505
506 [version 0.2807]
507
508 [Note: the 'testall' action and the code snippets below are currently
509 in alpha stage, see
510 http://www.nntp.perl.org/group/perl.module.build/2007/03/msg584.html
511 ]
512
513 Runs the test action plus each of the test$type actions defined by
514 the keys of the test_types parameter.
515
516 Currently, you need to define the ACTION_test$type method yourself
517 and enumerate them in the test_types parameter.
518
519 my $mb = Module::Build->subclass(
520 code => q(
521 sub ACTION_testspecial { shift->generic_test(type => 'special'); }
522 sub ACTION_testauthor { shift->generic_test(type => 'author'); }
523 )
524 )->new(
525 ...
526 test_types => {
527 special => '.st',
528 author => ['.at', '.pt' ],
529 },
530 ...
531
532 testcover
533
534 [version 0.26]
535
536 Runs the test action using Devel::Cover, generating a code-coverage
537 report showing which parts of the code were actually exercised during
538 the tests.
539
540 To pass options to Devel::Cover, set the $DEVEL_COVER_OPTIONS
541 environment variable:
542
543 DEVEL_COVER_OPTIONS=-ignore,Build ./Build testcover
544
545 testdb
546
547 [version 0.05]
548
549 This is a synonym for the 'test' action with the debugger=1 argument.
550
551 testpod
552
553 [version 0.25]
554
555 This checks all the files described in the docs action and produces
556 Test::Harness-style output. If you are a module author, this is
557 useful to run before creating a new release.
558
559 testpodcoverage
560
561 [version 0.28]
562
563 This checks the pod coverage of the distribution and produces
564 Test::Harness-style output. If you are a module author, this is
565 useful to run before creating a new release.
566
567 versioninstall
568
569 [version 0.16]
570
571 ** Note: since only.pm is so new, and since we just recently added
572 support for it here too, this feature is to be considered
573 experimental. **
574
575 If you have the only.pm module installed on your system, you can use
576 this action to install a module into the version-specific library
577 trees. This means that you can have several versions of the same
578 module installed and use a specific one like this:
579
580 use only MyModule => 0.55;
581
582 To override the default installation libraries in only::config,
583 specify the versionlib parameter when you run the Build.PL script:
584
585 perl Build.PL --versionlib /my/version/place/
586
587 To override which version the module is installed as, specify the
588 version parameter when you run the Build.PL script:
589
590 perl Build.PL --version 0.50
591
592 See the only.pm documentation for more information on
593 version-specific installs.
594
595OPTIONS
596
597 Command Line Options
598
599 The following options can be used during any invocation of Build.PL or
600 the Build script, during any action. For information on other options
601 specific to an action, see the documentation for the respective action.
602
603 NOTE: There is some preliminary support for options to use the more
604 familiar long option style. Most options can be preceded with the --
605 long option prefix, and the underscores changed to dashes (e.g.
606 --use-rcfile). Additionally, the argument to boolean options is
607 optional, and boolean options can be negated by prefixing them with no
608 or no- (e.g. --noverbose or --no-verbose).
609
610 quiet
611
612 Suppress informative messages on output.
613
614 verbose
615
616 Display extra information about the Build on output. verbose will
617 turn off quiet
618
619 cpan_client
620
621 Sets the cpan_client command for use with the installdeps action. See
622 installdeps for more details.
623
624 use_rcfile
625
626 Load the ~/.modulebuildrc option file. This option can be set to
627 false to prevent the custom resource file from being loaded.
628
629 allow_mb_mismatch
630
631 Suppresses the check upon startup that the version of Module::Build
632 we're now running under is the same version that was initially
633 invoked when building the distribution (i.e. when the Build.PL script
634 was first run). As of 0.3601, a mismatch results in a warning instead
635 of a fatal error, so this option effectively just suppresses the
636 warning.
637
638 debug
639
640 Prints Module::Build debugging information to STDOUT, such as a trace
641 of executed build actions.
642
643 Default Options File (.modulebuildrc)
644
645 [version 0.28]
646
647 When Module::Build starts up, it will look first for a file,
648 $ENV{HOME}/.modulebuildrc. If it's not found there, it will look in the
649 .modulebuildrc file in the directories referred to by the environment
650 variables HOMEDRIVE + HOMEDIR, USERPROFILE, APPDATA, WINDIR, SYS$LOGIN.
651 If the file exists, the options specified there will be used as
652 defaults, as if they were typed on the command line. The defaults can
653 be overridden by specifying new values on the command line.
654
655 The action name must come at the beginning of the line, followed by any
656 amount of whitespace and then the options. Options are given the same
657 as they would be on the command line. They can be separated by any
658 amount of whitespace, including newlines, as long there is whitespace
659 at the beginning of each continued line. Anything following a hash mark
660 (#) is considered a comment, and is stripped before parsing. If more
661 than one line begins with the same action name, those lines are merged
662 into one set of options.
663
664 Besides the regular actions, there are two special pseudo-actions: the
665 key * (asterisk) denotes any global options that should be applied to
666 all actions, and the key 'Build_PL' specifies options to be applied
667 when you invoke perl Build.PL.
668
669 * verbose=1 # global options
670 diff flags=-u
671 install --install_base /home/ken
672 --install_path html=/home/ken/docs/html
673 installdeps --cpan_client 'cpanp -i'
674
675 If you wish to locate your resource file in a different location, you
676 can set the environment variable MODULEBUILDRC to the complete absolute
677 path of the file containing your options.
678
679 Environment variables
680
681 MODULEBUILDRC
682
683 [version 0.28]
684
685 Specifies an alternate location for a default options file as
686 described above.
687
688 PERL_MB_OPT
689
690 [version 0.36]
691
692 Command line options that are applied to Build.PL or any Build
693 action. The string is split as the shell would (e.g. whitespace) and
694 the result is prepended to any actual command-line arguments.
695
696INSTALL PATHS
697
698 [version 0.19]
699
700 When you invoke Module::Build's build action, it needs to figure out
701 where to install things. The nutshell version of how this works is that
702 default installation locations are determined from Config.pm, and they
703 may be overridden by using the install_path parameter. An install_base
704 parameter lets you specify an alternative installation root like
705 /home/foo, and a destdir lets you specify a temporary installation
706 directory like /tmp/install in case you want to create bundled-up
707 installable packages.
708
709 Natively, Module::Build provides default installation locations for the
710 following types of installable items:
711
712 lib
713
714 Usually pure-Perl module files ending in .pm.
715
716 arch
717
718 "Architecture-dependent" module files, usually produced by compiling
719 XS, Inline, or similar code.
720
721 script
722
723 Programs written in pure Perl. In order to improve reuse, try to make
724 these as small as possible - put the code into modules whenever
725 possible.
726
727 bin
728
729 "Architecture-dependent" executable programs, i.e. compiled C code or
730 something. Pretty rare to see this in a perl distribution, but it
731 happens.
732
733 bindoc
734
735 Documentation for the stuff in script and bin. Usually generated from
736 the POD in those files. Under Unix, these are manual pages belonging
737 to the 'man1' category.
738
739 libdoc
740
741 Documentation for the stuff in lib and arch. This is usually
742 generated from the POD in .pm files. Under Unix, these are manual
743 pages belonging to the 'man3' category.
744
745 binhtml
746
747 This is the same as bindoc above, but applies to HTML documents.
748
749 libhtml
750
751 This is the same as libdoc above, but applies to HTML documents.
752
753 Four other parameters let you control various aspects of how
754 installation paths are determined:
755
756 installdirs
757
758 The default destinations for these installable things come from
759 entries in your system's Config.pm. You can select from three
760 different sets of default locations by setting the installdirs
761 parameter as follows:
762
763 'installdirs' set to:
764 core site vendor
765
766 uses the following defaults from Config.pm:
767
768 lib => installprivlib installsitelib installvendorlib
769 arch => installarchlib installsitearch installvendorarch
770 script => installscript installsitescript installvendorscript
771 bin => installbin installsitebin installvendorbin
772 bindoc => installman1dir installsiteman1dir installvendorman1dir
773 libdoc => installman3dir installsiteman3dir installvendorman3dir
774 binhtml => installhtml1dir installsitehtml1dir installvendorhtml1dir [*]
775 libhtml => installhtml3dir installsitehtml3dir installvendorhtml3dir [*]
776
777 * Under some OS (eg. MSWin32) the destination for HTML documents is
778 determined by the C<Config.pm> entry C<installhtmldir>.
779
780 The default value of installdirs is "site". If you're creating vendor
781 distributions of module packages, you may want to do something like
782 this:
783
784 perl Build.PL --installdirs vendor
785
786 or
787
788 ./Build install --installdirs vendor
789
790 If you're installing an updated version of a module that was included
791 with perl itself (i.e. a "core module"), then you may set installdirs
792 to "core" to overwrite the module in its present location.
793
794 (Note that the 'script' line is different from MakeMaker -
795 unfortunately there's no such thing as "installsitescript" or
796 "installvendorscript" entry in Config.pm, so we use the
797 "installsitebin" and "installvendorbin" entries to at least get the
798 general location right. In the future, if Config.pm adds some more
799 appropriate entries, we'll start using those.)
800
801 install_path
802
803 Once the defaults have been set, you can override them.
804
805 On the command line, that would look like this:
806
807 perl Build.PL --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
808
809 or this:
810
811 ./Build install --install_path lib=/foo/lib --install_path arch=/foo/lib/arch
812
813 install_base
814
815 You can also set the whole bunch of installation paths by supplying
816 the install_base parameter to point to a directory on your system.
817 For instance, if you set install_base to "/home/ken" on a Linux
818 system, you'll install as follows:
819
820 lib => /home/ken/lib/perl5
821 arch => /home/ken/lib/perl5/i386-linux
822 script => /home/ken/bin
823 bin => /home/ken/bin
824 bindoc => /home/ken/man/man1
825 libdoc => /home/ken/man/man3
826 binhtml => /home/ken/html
827 libhtml => /home/ken/html
828
829 Note that this is different from how MakeMaker's PREFIX parameter
830 works. install_base just gives you a default layout under the
831 directory you specify, which may have little to do with the
832 installdirs=site layout.
833
834 The exact layout under the directory you specify may vary by system -
835 we try to do the "sensible" thing on each platform.
836
837 destdir
838
839 If you want to install everything into a temporary directory first
840 (for instance, if you want to create a directory tree that a package
841 manager like rpm or dpkg could create a package from), you can use
842 the destdir parameter:
843
844 perl Build.PL --destdir /tmp/foo
845
846 or
847
848 ./Build install --destdir /tmp/foo
849
850 This will effectively install to "/tmp/foo/$sitelib",
851 "/tmp/foo/$sitearch", and the like, except that it will use
852 File::Spec to make the pathnames work correctly on whatever platform
853 you're installing on.
854
855 prefix
856
857 Provided for compatibility with ExtUtils::MakeMaker's PREFIX
858 argument. prefix should be used when you want Module::Build to
859 install your modules, documentation, and scripts in the same place as
860 ExtUtils::MakeMaker's PREFIX mechanism.
861
862 The following are equivalent.
863
864 perl Build.PL --prefix /tmp/foo
865 perl Makefile.PL PREFIX=/tmp/foo
866
867 Because of the complex nature of the prefixification logic, the
868 behavior of PREFIX in MakeMaker has changed subtly over time.
869 Module::Build's --prefix logic is equivalent to the PREFIX logic
870 found in ExtUtils::MakeMaker 6.30.
871
872 The maintainers of MakeMaker do understand the troubles with the
873 PREFIX mechanism, and added INSTALL_BASE support in version 6.31 of
874 MakeMaker, which was released in 2006.
875
876 If you don't need to retain compatibility with old versions
877 (pre-6.31) of ExtUtils::MakeMaker or are starting a fresh Perl
878 installation we recommend you use install_base instead (and
879 INSTALL_BASE in ExtUtils::MakeMaker). See "Installing in the same
880 location as ExtUtils::MakeMaker" in Module::Build::Cookbook for
881 further information.
882
883COMPARISON
884
885 A comparison between Module::Build and other CPAN distribution
886 installers.
887
888 * ExtUtils::MakeMaker requires make and use of a Makefile.
889 Module::Build does not, nor do other pure-perl installers following
890 the Build.PL spec such as Module::Build::Tiny. In practice, this is
891 usually not an issue for the end user, as make is already required to
892 install most CPAN modules, even on Windows.
893
894 * ExtUtils::MakeMaker has been a core module in every version of Perl
895 5, and must maintain compatibility to install the majority of CPAN
896 modules. Module::Build was added to core in Perl 5.10 and removed
897 from core in Perl 5.20, and (like ExtUtils::MakeMaker) is only
898 updated to fix critical issues and maintain compatibility.
899 Module::Build and other non-core installers like Module::Build::Tiny
900 are installed from CPAN by declaring themselves as a configure phase
901 prerequisite, and in this way any installer can be used in place of
902 ExtUtils::MakeMaker.
903
904 * Customizing the build process with ExtUtils::MakeMaker involves
905 overriding certain methods that form the Makefile by defining the
906 subs in the MY:: namespace, requiring in-depth knowledge of Makefile,
907 but allowing targeted customization of the entire build. Customizing
908 Module::Build involves subclassing Module::Build itself, adding or
909 overriding pure-perl methods that represent build actions, which are
910 invoked as arguments passed to the generated ./Build script. This is
911 a simpler concept but requires redefining the standard build actions
912 to invoke your customizations. Module::Build::Tiny does not allow for
913 customization.
914
915 * Module::Build provides more features and a better experience for
916 distribution authors than ExtUtils::MakeMaker. However, tools
917 designed specifically for authoring, such as Dist::Zilla and its
918 spinoffs Dist::Milla and Minilla, provide these features and more,
919 and generate a configure script (Makefile.PL/Build.PL) that will use
920 any of the various installers separately on the end user side.
921 App::ModuleBuildTiny is an alternative standalone authoring tool for
922 distributions using Module::Build::Tiny, which requires only a simple
923 two-line Build.PL.
924
925TO DO
926
927 The current method of relying on time stamps to determine whether a
928 derived file is out of date isn't likely to scale well, since it
929 requires tracing all dependencies backward, it runs into problems on
930 NFS, and it's just generally flimsy. It would be better to use an MD5
931 signature or the like, if available. See cons for an example.
932
933 - append to perllocal.pod
934 - add a 'plugin' functionality
935
936AUTHOR
937
938 Ken Williams <kwilliams@cpan.org>
939
940 Development questions, bug reports, and patches should be sent to the
941 Module-Build mailing list at <module-build@perl.org>.
942
943 Bug reports are also welcome at
944 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build>.
945
946 The latest development version is available from the Git repository at
947 <https://github.com/Perl-Toolchain-Gang/Module-Build>
948
949COPYRIGHT
950
951 Copyright (c) 2001-2006 Ken Williams. All rights reserved.
952
953 This library is free software; you can redistribute it and/or modify it
954 under the same terms as Perl itself.
955
956SEE ALSO
957
958 perl(1), Module::Build::Cookbook, Module::Build::Authoring,
959 Module::Build::API, ExtUtils::MakeMaker
960
961 META.yml Specification: CPAN::Meta::Spec
962
963 http://www.dsmit.com/cons/
964
965 http://search.cpan.org/dist/PerlBuildSystem/
966
967