1NAME
2 Module::Install - Standalone, extensible Perl module installer
3
4SYNOPSIS
5 In your Makefile.PL: (Recommended Usage)
6
7 use inc::Module::Install;
8
9 # Define metadata
10 name 'Your-Module';
11 all_from 'lib/Your/Module.pm';
12
13 # Specific dependencies
14 requires 'File::Spec' => '0.80';
15 test_requires 'Test::More' => '0.42';
16 recommends 'Text::CSV_XS'=> '0.50';
17 no_index 'directory' => 'demos';
18 install_script 'myscript';
19
20 WriteAll;
21
22 Quickly upgrade a legacy ExtUtil::MakeMaker installer:
23
24 use inc::Module::Install;
25 WriteMakefile( ... );
26
27WARNING
28 Please note that while Module::Install pioneered many great ideas in its
29 time, its primary benefits have been better achieved by the authoring
30 tool Dist::Zilla, and its spinoffs Dist::Milla and Minilla. These tools
31 allow the author to build and maintain distributions with DWIM
32 convenience, while the distribution is installed directly by
33 ExtUtils::MakeMaker or similar installation tools, avoiding the
34 complexity of bundling the installer. Dist::Zilla additionally has a
35 more robust plugin system which makes it easier to keep up with changes
36 to the CPAN::Meta::Spec and add other new functionality. Use of
37 Module::Install for new distributions is therefore discouraged by the
38 maintainers.
39
40DESCRIPTION
41 Module::Install is a package for writing installers for CPAN (or
42 CPAN-like) distributions that are clean, simple, minimalist, act in a
43 strictly correct manner with ExtUtils::MakeMaker, and will run on any
44 Perl installation version 5.005 or newer.
45
46 The intent is to make it as easy as possible for CPAN authors (and
47 especially for first-time CPAN authors) to have installers that follow
48 all the best practices for distribution installation, but involve as
49 much DWIM (Do What I Mean) as possible when writing them.
50
51 Writing Module::Install Installers
52 The quickest way to get started with Module::Install is to copy the
53 "SYNOPSIS" from above and save it as your own Makefile.PL. Then modify
54 the file to suit your own particular case, using the list of commands
55 documented in "COMMON COMMANDS" below.
56
57 If all you want to do is write an installer, go and do that now. You
58 don't really need the rest of this description unless you are interested
59 in the details.
60
61How it Works
62 The motivation behind Module::Install is that distributions need to
63 interact with a large number of different versions of perl and module
64 installers infrastructure, primarily CPAN.pm, CPANPLUS.pm,
65 ExtUtils::MakeMaker and Module::Build.
66
67 These have accumulated greatly varying feature and bug profiles over the
68 years, and it is now very difficult to write an installer that will work
69 properly using only the installed versions of these modules,
70
71 For example, the CPAN.pm version shipped with Perl 5.005 is now 5+ years
72 old and considered highly buggy, yet it still exists on quite a number
73 of legacy machines.
74
75 Rather than try to target one specific installer and/or make you add
76 twisty workaround expressions to every piece of install code you write,
77 Module::Install will copy part of itself into each module distribution
78 it creates.
79
80 This allows new improvements to be used in your installers regardless of
81 the age of the system a distribution is being installed on, at the cost
82 of a small increase in the size of your distribution.
83
84 History
85 This module was originally written by Brian Ingerson as a smart drop-in
86 replacement for ExtUtils::MakeMaker.
87
88 For more information, see Brian's *Creating Module Distributions with
89 Module::Install* in June 2003 issue of The Perl Journal
90 (<http://www.drdobbs.com/web-development/creating-module-distributions-w
91 ith-modul/184416018>)
92
93 For a lot more information, and some personal opinions on the module and
94 its creation, see Module::Install::Philosophy.
95
96COMMON COMMANDS
97 The following are the most common commands generally used in installers.
98
99 It is far from an exhaustive list, as many of the plugins provide
100 commands to work in more details that you would normally need.
101
102 name
103 name 'My-Module';
104
105 The name command is compulsory command, generally the first.
106
107 It provides the name of your distribution, which for a module like
108 Your::Module would normally be "Your-Module".
109
110 This naming scheme is not hard and fast and you should note that
111 distributions are actually a separate naming scheme from modules.
112
113 For example the LWP modules come in a distribution called "libwww-perl".
114
115 all_from
116 all_from 'lib/My/Module.pm';
117
118 For most simple Perl distributions that feature one dominant module or
119 class as the base, you can get the most Do What I Mean functionality by
120 using the all_from command, which will try to extract as much metadata
121 as possible from the Perl code and POD in that primary module.
122
123 Functionally, "all_from" is equivalent to "abstract_from" +
124 "author_from" + "version_from" + "license_from" + "perl_version_from".
125 See below for details.
126
127 If any of these values are set already before "all_from" is used, they
128 will kept and not be overwritten.
129
130 abstract
131 abstract 'This distribution does something';
132
133 All distributions have an abstract, a short description of the
134 distribution as a whole. It is usually around 30-70 characters long.
135
136 The "abstract" command is used to explicitly set the abstract for the
137 distribution, at least as far as the metadata file for the distribution
138 is concerned.
139
140 abstract_from
141 abstract_from 'lib/My/Module.pm';
142
143 The "abstract_from" command retrieves the abstract from a particular
144 file contained in the distribution package. Most often this is done from
145 the main module, where "Module::Install" will read the POD and use
146 whatever is in the "=head1 NAME" section (with module name stripped if
147 needed)
148
149 "abstract_from" is set as part of "all_from".
150
151 author
152 author 'Adam Kennedy <adamk@cpan.org>';
153
154 The distribution metadata contains information on the primary author or
155 the distribution, or the primary maintainer if the original author is no
156 longer involved. It should generally be specified in the form of an
157 email address.
158
159 It you don't want to give away a real email address, you should use the
160 "CPANID@cpan.org" address you receive automatically when you got your
161 PAUSE account.
162
163 The "author" command is used to explicitly set this value.
164
165 author_from
166 author_from 'lib/My/Module.pm';
167
168 The "author_from" command retrieves the author from a particular file
169 contained in the distribution package. Most often this is done using the
170 main module, where Module::Install will read the POD and use whatever it
171 can find in the "=head1 AUTHOR" section.
172
173 version
174 version '0.01';
175
176 The "version" command is used to specify the version of the
177 distribution, as distinct from the version of any single module within
178 the distribution.
179
180 Of course, in almost all cases you want it to match the version of the
181 primary module within the distribution, which you can do using
182 "version_from".
183
184 version_from
185 version_from 'lib/My/Module.pm';
186
187 The "version_from" command retrieves the distribution version from a
188 particular file contained in the distribution package. Most often this
189 is done from the main module.
190
191 "version_from" will look for the first time you set $VERSION and use the
192 same value, using a technique consistent with various other module
193 version scanning tools.
194
195 license
196 license 'perl';
197
198 The "license" command specifies the license for the distribution.
199
200 Most often this value will be 'perl', meaning *"the same as for Perl
201 itself"*. Other allowed values include 'gpl', 'lgpl', 'bsd', 'MIT', and
202 'artistic'.
203
204 This value is always considered a summary, and it is normal for authors
205 to include a LICENSE file in the distribution, containing the full
206 license for the distribution.
207
208 You are also reminded that if the distribution is intended to be
209 uploaded to the CPAN, it must be an OSI-approved open source license.
210 Commercial software is not permitted on the CPAN.
211
212 license_from
213 license_from 'lib/My/Module.pm';
214
215 The "license_from" command retrieves the distribution license from a
216 particular file contained in the distribution package. Most often this
217 is done from the main module.
218
219 "license_from" will look inside the POD within the indicated file for a
220 licensing or copyright-related section and scan for a variety of strings
221 that identify the general class of license.
222
223 At this time it supports only the 6 values mentioned above in the
224 "license" command summary.
225
226 perl_version
227 perl_version '5.006';
228
229 The "perl_version" command is used to specify the minimum version of the
230 perl interpreter your distribution requires.
231
232 When specifying the version, you should try to use the normalized
233 version string. Perl version segments are 3 digits long, so a dependency
234 on Perl 5.6 will become '5.006' and Perl 5.10.2 will become '5.010002'.
235
236 perl_version_from
237 perl_version_from 'lib/My/Module.pm'
238
239 The "perl_version_from" command retrieves the minimum perl interpreter
240 version from a particular file contained in the distribution package.
241 Most often this is done from the main module.
242
243 The minimum version is detected by scanning the file for "use 5.xxx"
244 pragma calls in the module file.
245
246 recommends
247 recommends 'Text::CSV_XS' => '0.50'
248
249 The "recommends" command indicates an optional run-time module that
250 provides extra functionality. Recommended dependencies are not needed to
251 build or test your distribution, but are considered "nice to have".
252
253 As with "requires", the dependency is on a module and not a
254 distribution. A version of zero indicates that any version of the module
255 is recommended.
256
257 requires
258 requires 'List::Util' => 0;
259 requires 'LWP' => '5.69';
260
261 The "requires" command indicates a normal run-time dependency of your
262 distribution on another module. Most distributions will have one or more
263 of these commands, indicating which CPAN (or otherwise) modules your
264 distribution needs.
265
266 A "requires" dependency can be verbalised as *"If you wish to install
267 and use this distribution, you must first install these modules first"*.
268
269 Note that the dependency is on a module and not a distribution. This is
270 to ensure that your dependency stays correct, even if the module is
271 moved or merged into a different distribution, as is occasionally the
272 case.
273
274 A dependency on version zero indicates any version of module is
275 sufficient. Versions should generally be quoted for clarity.
276
277 test_requires
278 test_requires 'Test::More' => '0.47';
279
280 The "test_requires" command indicates a test script dependency for the
281 distribution. The specification format is identical to that of the
282 "requires" command.
283
284 The "test_requires" command is distinct from the "requires" command in
285 that it indicates a module that is needed only during the testing of the
286 distribution (often a period of only a few seconds) but will not be
287 needed after the distribution is installed.
288
289 The "testrequires" command is used to allow the installer some
290 flexibility in how it provides the module, and to allow downstream
291 packagers (Debian, FreeBSD, ActivePerl etc) to retain only the
292 dependencies needed for run-time operation.
293
294 The "include" command is sometimes used by some authors along with
295 "test_requires" to bundle a small well-tested module into the
296 distribution package itself rather than inflict yet another module
297 installation on users installing from CPAN directly.
298
299 configure_requires
300 configure_requires 'File::Spec' => '0.80';
301
302 The "configure_requires" command indicates a configure-time dependency
303 for the distribution. The specification format is identical to that of
304 the "requires" command.
305
306 The "configure_requires" command is used to get around the conundrum of
307 how to use a CPAN module in your Makefile.PL, when you have to load
308 Makefile.PL (and thus the CPAN module) in order to know that you need
309 it.
310
311 Traditionally, this circular logic could not be broken and so
312 Makefile.PL scripts needed to rely on lowest-common-denominator
313 approaches, or to bundle those dependencies using something like the
314 "include" command.
315
316 The "configure_requires" command creates an entry in the special
317 configure_requires: key in the distribution's META.yml file.
318
319 Although most of META.yml is considered advisory only, a CPAN client
320 will treat the contents of configure_requires: as authoritative, and
321 install the listed modules before it executes the Makefile.PL (from
322 which it then determines the other dependencies).
323
324 Please note that support for configure_requires: in CPAN clients is not
325 100% complete at time of writing, and still cannot be relied upon.
326
327 Because Module::Install itself only supports 5.005, it will silently add
328 the equivalent of a "configure_requires( perl => '5.005' );" command to
329 your distribution.
330
331 requires_external_bin
332 requires_external_bin 'cvs';
333
334 As part of its role as the dominant "glue" language, a lot of Perl
335 modules run commands or programs on the host system.
336
337 The "requires_external_bin" command is used to verify that a particular
338 command is available on the host system.
339
340 Unlike a missing Perl module, a missing external binary is unresolvable
341 at make-time, and so the Makefile.PL run will abort with a "NA" (Not
342 Applicable) result.
343
344 In future, this command will also add additional information to the
345 metadata for the dist, so that auto-packagers for particular operating
346 system are more-easily able to auto-discover the appropriate non-Perl
347 packages needed as a dependency.
348
349 install_script
350 # The following are equivalent
351 install_script 'script/scriptname'
352
353 The "install_script" command provides support for the installation of
354 scripts that will become available at the console on both Unix and
355 Windows (in the later case by wrapping it up as a .bat file).
356
357 Note that is it normal practice to not put a .pl on the end of such
358 scripts, so that they feel more natural when being used.
359
360 In the example above, the script/scriptname program could be run after
361 the installation just by doing the following.
362
363 > scriptname
364 Running scriptname 0.01...
365
366 >
367
368 By convention, scripts should be placed in a /script directory within
369 your distribution. To support less typing, if a script is located in the
370 script directory, you need refer to it by name only.
371
372 # The following are equivalent
373 install_script 'foo';
374 install_script 'script/foo';
375
376 no_index
377 no_index directory => 'examples';
378 no_index package => 'DB';
379
380 Quite often a distribution will provide example scripts or testing
381 modules (.pm files) as well as the actual library modules.
382
383 In almost all situations, you do not want these indexed in the CPAN
384 index, the master Perl packages list, or displayed on
385 <https://metacpan.org/> or <http://search.cpan.org/> websites, you just
386 want them along for the ride.
387
388 The "no_index" command is used to indicate directories or files where
389 there might be non-library .pm files or other files that the CPAN
390 indexer and websites such as <https://metacpan.org/> or
391 <http://search.cpan.org/> should explicitly ignore.
392
393 The most common situation is to ignore example or demo directories, but
394 a variety of different situations may require a "no_index" entry.
395
396 Another common use for "no_index" is to prevent the PAUSE indexer
397 complaining when your module makes changes inside a "package DB" block.
398 This is used to interact with the debugger in some specific ways.
399
400 See the META.yml documentation for more details on what "no_index"
401 values are allowed.
402
403 The inc, t and share (if "install_share" is used) directories are
404 automatically "no_index"'ed for you if found and do not require an
405 explicit command.
406
407 To summarize, if you can see it on <https://metacpan.org/> or
408 <http://search.cpan.org/> and you shouldn't be able to, you need a
409 "no_index" entry to remove it.
410
411 installdirs, install_as_*
412 installdirs 'site'; # the default
413
414 install_as_core; # alias for installdirs 'perl'
415 install_as_cpan; # alias for installdirs 'site'
416 install_as_site; # alias for installdirs 'site'
417 install_as_vendor; # alias for installdirs 'vendor'
418
419 The "installdirs" and "install_as" commands specify the location where
420 the module should be installed; this is the equivalent to
421 ExtUtils::MakeMaker's "INSTALLDIRS" option. For almost all regular
422 modules, the default is recommended, and need not be changed. Dual-life
423 (core and CPAN) modules, as well as vendor-specific modules, may need to
424 use the other options.
425
426 If unsure, do not use this option.
427
428 WriteAll
429 The "WriteAll" command is generally the last command in the file; it
430 writes out META.yml and Makefile so the user can run the "make", "make
431 test", "make install" install sequence.
432
433EXTENSIONS
434 All extensions belong to the Module::Install::* namespace, and inherit
435 from Module::Install::Base. There are three categories of extensions:
436
437 Standard Extensions
438 Methods defined by a standard extension may be called as plain functions
439 inside Makefile.PL; a corresponding singleton object will be spawned
440 automatically. Other extensions may also invoke its methods just like
441 their own methods:
442
443 # delegates to $other_extension_obj->method_name(@args)
444 $self->method_name(@args);
445
446 At the first time an extension's method is invoked, a POD-stripped
447 version of it will be included under the inc/Module/Install/ directory,
448 and becomes *fixed* -- i.e., even if the user had installed a different
449 version of the same extension, the included one will still be used
450 instead.
451
452 If the author wish to upgrade extensions in inc/ with installed ones,
453 simply run "perl Makefile.PL" again; Module::Install determines whether
454 you are an author by the existence of the inc/.author/ directory.
455 End-users can reinitialize everything and become the author by typing
456 "make realclean" and "perl Makefile.PL".
457
458 Private Extensions
459 Those extensions take the form of Module::Install::PRIVATE and
460 Module::Install::PRIVATE::*.
461
462 Authors are encouraged to put all existing Makefile.PL magics into such
463 extensions (e.g. Module::Install::PRIVATE for common bits;
464 Module::Install::PRIVATE::DISTNAME for functions specific to a
465 distribution).
466
467 Private extensions should not to be released on CPAN; simply put them
468 somewhere in your @INC, under the "Module/Install/" directory, and start
469 using their functions in Makefile.PL. Like standard extensions, they
470 will never be installed on the end-user's machine, and therefore never
471 conflict with other people's private extensions.
472
473 Administrative Extensions
474 Extensions under the Module::Install::Admin::* namespace are never
475 included with the distribution. Their methods are not directly
476 accessible from Makefile.PL or other extensions; they are invoked like
477 this:
478
479 # delegates to $other_admin_extension_obj->method_name(@args)
480 $self->admin->method_name(@args);
481
482 These methods only take effect during the *initialization* run, when
483 inc/ is being populated; they are ignored for end-users. Again, to
484 re-initialize everything, just run "perl Makefile.PL" as the author.
485
486 Scripts (usually one-liners in Makefile) that wish to dispatch AUTOLOAD
487 functions into administrative extensions (instead of standard
488 extensions) should use the Module::Install::Admin module directly. See
489 Module::Install::Admin for details.
490
491EXTENSIONS
492 Detailed information is provided for all (some) of the relevant modules
493 via their own POD documentation.
494
495 Module::Install::AutoInstall
496 Provides "auto_install()" to automatically fetch and install
497 prerequisites.
498
499 Module::Install::Base
500 The base class for all extensions
501
502 Module::Install::Bundle
503 Provides the "bundle" family of commands, allowing you to bundle another
504 CPAN distribution within your distribution.
505
506 Module::Install::Fetch
507 Handles install-time fetching of files from remote servers via FTP and
508 HTTP.
509
510 Module::Install::Include
511 Provides the "include" family of commands for embedding modules that are
512 only need at build-time in your distribution and won't be installed.
513
514 Module::Install::Inline
515 Provides "&Inline->write" to replace Inline::MakeMaker's functionality
516 for making Inline-based modules (and cleaning up).
517
518 However, you should invoke this with "WriteAll( inline => 1 )".
519
520 Module::Install::Makefile
521 Provides "&Makefile->write" to generate a Makefile for you distribution.
522
523 Module::Install::Metadata
524 Provides "&Meta->write" to generate a META.yml file for your
525 distribution.
526
527 Module::Install::PAR
528 Makes pre-compiled module binary packages from the built blib directory,
529 and download existing ones to save recompiling.
530
531 Module::Install::Run
532 Determines if commands are available on the user's machine, and runs
533 them via IPC::Run3.
534
535 Module::Install::Scripts
536 Handles packaging and installation of scripts to various bin dirs.
537
538 Module::Install::Win32
539 Functions for installing modules on Win32 and finding/installing
540 nmake.exe for users that need it.
541
542 Module::Install::WriteAll
543 Provides the "WriteAll", which writes all the requires files, such as
544 META.yml and Makefile.
545
546 "WriteAll" takes four optional named parameters:
547
548 "check_nmake" (defaults to true)
549 If true, invokes functions with the same name.
550
551 *The use of this param is no longer recommended.*
552
553 "inline" (defaults to false)
554 If true, invokes "&Inline->write" Inline modules.
555
556 "meta" (defaults to true)
557 If true, writes a "META.yml" file.
558
559 "sign" (defaults to false)
560 If true, invokes "sign" command to digitally sign erm... something.
561
562 Module::Install::Admin::Find
563 Package-time functions for finding extensions, installed packages and
564 files in subdirectories.
565
566 Module::Install::Admin::Manifest
567 Package-time functions for manipulating and updating the MANIFEST file.
568
569 Module::Install::Admin::Metadata
570 Package-time functions for manipulating and updating the META.yml file.
571
572 Module::Install::Admin::ScanDeps
573 Package-time scanning for non-core dependencies via Module::ScanDeps and
574 Module::CoreList.
575
576FAQ
577 What are the benefits of using Module::Install?
578 Here is a brief overview of the reasons:
579
580 * Extremely easy for beginners to learn
581
582 * Does everything ExtUtils::MakeMaker does.
583
584 * Does it with a dramatically simpler syntax.
585
586 * Automatically scans for metadata for you.
587
588 * Requires no installation for end-users.
589
590 * Guaranteed forward-compatibility.
591
592 * Automatically updates your MANIFEST.
593
594 * Distributing scripts is easy.
595
596 * Include prerequisite modules (less dependencies to install)
597
598 * Auto-installation of prerequisites.
599
600 * Support for Inline-based modules.
601
602 * Support for File::ShareDir shared data files
603
604 * Support for precompiled PAR binaries.
605
606 * Deals with Win32 install issues for you.
607
608 By greatly shrinking and simplifying the syntax, Module::Install keeps
609 the amount of work required to maintain your Makefile.PL files to an
610 absolute minimum.
611
612 And if you maintain more than one module than needs to do unusual
613 installation tricks, you can create a specific module to abstract away
614 this complexity.
615
616 Module::Install isn't at 1.00 yet, is it safe to use yet?
617 As long as you are going to periodically do incremental releases to get
618 any bug fixes and new functionality, yes.
619
620 If you don't plan to do incremental releases, it might be a good idea to
621 continue to wait for a while.
622
623COOKBOOK / EXAMPLES
624 The following are some real-life examples of Makefile.PL files using
625 Module::Install.
626
627 Method::Alias
628 Method::Alias is a trivially-small utility module, with almost the
629 smallest possible Makefile.PL.
630
631 use inc::Module::Install;
632
633 name 'Method-Alias';
634 all_from 'lib/Method/Alias.pm';
635 test_requires 'Test::More' => '0.42';
636
637 File::HomeDir
638 File::HomeDir locates your home directory on any platform. It needs an
639 installer that can handle different dependencies on different platforms.
640
641 use inc::Module::Install;
642
643 name 'File-HomeDir';
644 all_from 'lib/File/HomeDir.pm';
645 requires 'File::Spec' => '0.80';
646 test_requires 'Test::More' => '0.47';
647
648 if ( $MacPerl::Version ) {
649 # Needed on legacy Mac OS 9
650 requires 'Mac::Files' => 0;
651 }
652
653 if ( $^O eq 'MXWin32' ) {
654 # Needed on Windows platforms
655 requires 'Win32::TieRegistry' => 0;
656 }
657
658 WriteAll;
659
660TO DO
661 Implement Module::Install::Compiled and Module::Install::Admin::Compiled
662 to integrate the Module::Compiled "perl 6 to perl 5" functionality with
663 Module::Install. Because this would add SIGNIFICANT dependencies (i.e.
664 pugs!) this should almost certainly be distributed as a separate
665 distribution.
666
667 Go over POD docs in detail.
668
669 Test recursive Makefile directories
670
671 The test suite needs a great deal more test scripts.
672
673 Dependencies on shared libraries (libxml/libxml.dll etc) and binary
674 files so that debian/Win32/etc autopackaging applications can create the
675 appropriate package-level dependencies there.
676
677 EU::MM 6.06_03+ supports META.yml natively. Maybe probe for that?
678
679SEE ALSO
680 Module::Install::Philosophy
681
682 inc::Module::Install
683
684 Module::Install::AutoInstall
685
686 Module::Install::Base
687
688 Module::Install::Bundle
689
690 Module::Install::MakeMaker
691
692 Module::Install::Share
693
694 Module::Install::Admin
695
696 Module::Install::Admin::Include
697
698 Module::Install::Admin::Manifest
699
700 CPAN::MakeMaker, Inline::MakeMaker
701
702 ExtUtils::MakeMaker
703
704SUPPORT
705 Bugs should be reported via the CPAN bug tracker at
706
707 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install>
708
709 For other issues, contact the (topmost) author.
710
711AUTHORS
712 Adam Kennedy <adamk@cpan.org>
713
714 Audrey Tang <autrijus@autrijus.org>
715
716 Brian Ingerson <ingy@cpan.org>
717
718COPYRIGHT
719 Copyright 2002 - 2012 Brian Ingerson, Audrey Tang and Adam Kennedy.
720
721 This program is free software; you can redistribute it and/or modify it
722 under the same terms as Perl itself.
723
724