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