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