5 Module::Install - Standalone, extensible Perl module installer
9 In your F<Makefile.PL>: (Recommended Usage)
11 use inc::Module::Install;
15 all_from 'lib/Your/Module.pm';
17 # 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';
26 Quickly upgrade a legacy L<ExtUtil::MakeMaker> installer:
28 use inc::Module::Install;
33 B<Module::Install> is a package for writing installers for CPAN (or
34 CPAN-like) distributions that are clean, simple, minimalist, act in a
35 strictly correct manner with L<ExtUtils::MakeMaker>, and will run on
36 any Perl installation version 5.005 or newer.
38 The intent is to make it as easy as possible for CPAN authors (and
39 especially for first-time CPAN authors) to have installers that follow
40 all the best practices for distribution installation, but involve as
41 much DWIM (Do What I Mean) as possible when writing them.
43 =head2 Writing Module::Install Installers
45 The quickest way to get started with Module::Install is to copy the
46 L</SYNOPSIS> from above and save it as your own F<Makefile.PL>. Then
47 modify the file to suit your own particular case, using the list of
48 commands documented in L</COMMON COMMANDS> below.
50 If all you want to do is write an installer, go and do that now. You
51 don't really need the rest of this description unless you are
52 interested in the details.
56 The motivation behind B<Module::Install> is that distributions need
57 to interact with a large number of different versions of L<perl> and
58 module installers infrastructure, primarily L<CPAN.pm>, L<CPANPLUS.pm>,
59 L<ExtUtils::MakeMaker> and L<Module::Build>.
61 These have accumulated B<greatly> varying feature and bug profiles over
62 the years, and it is now very difficult to write an installer that will
63 work properly using only the installed versions of these modules,
65 For example, the L<CPAN.pm> version shipped with Perl 5.005 is now 5+
66 years old and considered highly buggy, yet it still exists on quite a
67 number of legacy machines.
69 Rather than try to target one specific installer and/or make you add
70 twisty workaround expressions to every piece of install code you write,
71 B<Module::Install> will copy part of itself into each module distribution
74 This allows new improvements to be used in your installers regardless of
75 the age of the system a distribution is being installed on, at the cost
76 of a small increase in the size of your distribution.
80 This module was originally written by Brian Ingerson as a smart drop-in
81 replacement for L<ExtUtils::MakeMaker>.
83 For more information, see Brian's I<Creating Module Distributions with
84 Module::Install> in June 2003 issue of The Perl Journal
85 (L<http://www.tpj.com/issues/>).
87 For a B<lot> more information, and some personal opinions on the module
88 and its creation, see L<Module::Install::Philosophy>.
90 =head1 COMMON COMMANDS
92 The following are the most common commands generally used in installers.
94 It is far from an exhaustive list, as many of the plugins provide commands
95 to work in more details that you would normally need.
101 The B<name> command is compulsory command, generally the first.
103 It provides the name of your distribution, which for a module like
104 B<Your::Module> would normally be C<Your-Module>.
106 This naming scheme is not hard and fast and you should note that
107 distributions are actually a seperate naming scheme from modules.
109 For example the L<LWP> modules come in a distribution called
114 all_from 'lib/My/Module.pm';
116 For most simple Perl distributions that feature one dominant module or
117 class as the base, you can get the most Do What I Mean functionality by
118 using the B<all_from> command, which will try to extract as much
119 metadata as possible from the Perl code and POD in that primary module.
121 Functionally, C<all_from> is equivalent to C<abstract_from> +
122 C<author_from> + C<version_from> + C<license_from> +
123 C<perl_version_from>. See below for details.
125 If any of these values are set already B<before> C<all_from> is used,
126 they will kept and B<not> be overwritten.
130 abstract 'This distribution does something';
132 All distributions have an abstract, a short description of the
133 distribution as a whole. It is usually around 30-70 characters long.
135 The C<abstract> command is used to explicitly set the abstract for the
136 distribution, at least as far as the metadata file for the distribution
141 abstract_from 'lib/My/Module.pm';
143 The C<abstract_from> command retrieves the abstract from a particular
144 file contained in the distribution package. Most often this is done
145 from the main module, where C<Module::Install> will read the POD and
146 use whatever is in the C<=head1 NAME> section (with module name stripped
149 C<abstract_from> is set as part of C<all_from>.
153 author 'Adam Kennedy <adamk@cpan.org>';
155 The distribution metadata contains information on the primary author
156 or the distribution, or the primary maintainer if the original author
157 is no longer involved. It should generally be specified in the form
160 It you don't want to give away a real email address, you should use
161 the C<CPANID@cpan.org> address you recieve automatically when you
162 got your PAUSE account.
164 The C<author> command is used to explicitly set this value.
168 author_from 'lib/My/Module.pm';
170 The C<author_from> command retrieves the author from a particular
171 file contained in the distribution package. Most often this is done
172 using the main module, where L<Module::Install> will read the POD
173 and use whatever it can find in the C<=head1 AUTHOR> section.
179 The C<version> command is used to specify the version of the
180 distribution, as distinct from the version of any single module within
183 Of course, in almost all cases you want it to match the version of the
184 primary module within the distribution, which you can do using
189 version_from 'lib/My/Module.pm';
191 The C<version_from> command retrieves the distribution version from a
192 particular file contained in the distribution package. Most often this is
193 done from the main module.
195 C<version_from> will look for the first time you set C<$VERSION> and use
196 the same value, using a technique consistent with various other module
197 version scanning tools.
203 The C<license> command specifies the license for the distribution.
205 Most often this value will be C<'perl'>, meaning I<"the same as for Perl
206 itself">. Other allowed values include C<'gpl'>, C<'lgpl'>, C<'bsd'>,
207 C<'MIT'>, and C<'artistic'>.
209 This value is always considered a summary, and it is normal for authors
210 to include a F<LICENSE> file in the distribution, containing the full
211 license for the distribution.
213 You are also reminded that if the distribution is intended to be uploaded
214 to the CPAN, it B<must> be an OSI-approved open source license. Commercial
215 software is not permitted on the CPAN.
219 license_from 'lib/My/Module.pm';
221 The C<license_from> command retrieves the distribution license from a
222 particular file contained in the distribution package. Most often this
223 is done from the main module.
225 C<license_from> will look inside the POD within the indicated file for
226 a licensing or copyright-related section and scan for a variety of
227 strings that identify the general class of license.
229 At this time it supports only the 6 values mentioned above in the
230 C<license> command summary.
234 perl_version '5.006';
236 The C<perl_version> command is used to specify the minimum version of the
237 perl interpreter your distribution requires.
239 When specifying the version, you should try to use the normalized version
240 string. Perl version segments are 3 digits long, so a dependency on Perl
241 5.6 will become C<'5.006'> and Perl 5.10.2 will become C<'5.010002'>.
243 =head2 perl_version_from
245 perl_version_from 'lib/My/Module.pm'
247 The C<perl_version_from> command retrieves the minimum F<perl> interpreter
248 version from a particular file contained in the distribution package. Most
249 often this is done from the main module.
251 The minimum version is detected by scanning the file for C<use 5.xxx>
252 pragma calls in the module file.
256 recommends 'Text::CSV_XS' => '0.50'
258 The C<recommends> command indicates an optional run-time module that
259 provides extra functionality. Recommended dependencies are not
260 needed to build or test your distribution, but are considered "nice
263 As with L</requires>, the dependency is on a B<module> and not
264 a distribution. A version of zero indicates that any version of
265 the module is recommended.
269 requires 'List::Util' => 0;
270 requires 'LWP' => '5.69';
272 The C<requires> command indicates a normal run-time dependency of your
273 distribution on another module. Most distributions will have one or
274 more of these commands, indicating which CPAN (or otherwise) modules
275 your distribution needs.
277 A C<requires> dependency can be verbalised as I<"If you wish to install
278 and use this distribution, you must first install these modules first">.
280 Note that the dependency is on a B<module> and not a distribution. This
281 is to ensure that your dependency stays correct, even if the module is
282 moved or merged into a different distribtion, as is occasionally the
285 A dependency on version zero indicates B<any> version of module is
286 sufficient. Versions should generally be quoted for clarity.
290 test_requires 'Test::More' => '0.47';
292 The C<test_requires> command indicates a test script dependency for
293 the distribution. The specification format is identical to that of
294 the C<requires> command.
296 The C<test_requires> command is distinct from the C<requires> command
297 in that it indicates a module that is needed B<only> during the
298 testing of the distribution (often a period of only a few seconds)
299 but will B<not> be needed after the distribution is installed.
301 The C<testrequires> command is used to allow the installer some
302 flexibility in how it provides the module, and to allow downstream
303 packagers (Debian, FreeBSD, ActivePerl etc) to retain only the
304 dependencies needed for run-time operation.
306 The C<include> command is sometimes used by some authors along with
307 C<test_requires> to bundle a small well-tested module into the
308 distribution package itself rather than inflict yet another module
309 installation on users installing from CPAN directly.
311 =head2 configure_requires
313 configure_requires 'File::Spec' => '0.80';
315 The C<configure_requires> command indicates a configure-time dependency
316 for the distribution. The specification format is identical to that of
317 the C<requires> command.
319 The C<configure_requires> command is used to get around the conundrum
320 of how to use a CPAN module in your Makefile.PL, when you have to load
321 Makefile.PL (and thus the CPAN module) in order to know that you need it.
323 Traditionally, this circular logic could not be broken and so Makefile.PL
324 scripts needed to rely on lowest-common-denominator approaches, or to
325 bundle those dependencies using something like the C<include> command.
327 The C<configure_requires> command creates an entry in the special
328 configure_requires: key in the distribution's F<META.yml> file.
330 Although most of F<META.yml> is considered advisory only, a L<CPAN>
331 client will treat the contents of configure_requires: as authorative,
332 and install the listed modules B<before> it executes the F<Makefile.PL>
333 (from which it then determines the other dependencies).
335 Please note that support for configure_requires: in CPAN clients is not
336 100% complete at time of writing, and still cannot be relied upon.
338 Because B<Module::Install> itself only supports 5.005, it will silently
339 add the equivalent of a C<configure_requires( perl => '5.005' );>
340 command to your distribution.
342 =head2 requires_external_bin
344 requires_external_bin 'cvs';
346 As part of its role as the dominant "glue" language, a lot of Perl
347 modules run commands or programs on the host system.
349 The C<requires_external_bin> command is used to verify that a particular
350 command is available on the host system.
352 Unlike a missing Perl module, a missing external binary is unresolvable
353 at make-time, and so the F<Makefile.PL> run will abort with a "NA"
354 (Not Applicable) result.
356 In future, this command will also add additional information to the
357 metadata for the dist, so that auto-packagers for particular operating
358 system are more-easily able to auto-discover the appropriate non-Perl
359 packages needed as a dependency.
361 =head2 install_script
363 # The following are equivalent
364 install_script 'script/scriptname'
366 The C<install_script> command provides support for the installation of
367 scripts that will become available at the console on both Unix and
368 Windows (in the later case by wrapping it up as a .bat file).
370 Note that is it normal practice to B<not> put a .pl on the end of such
371 scripts, so that they feel more natural when being used.
373 In the example above, the F<script/scriptname> program could be run after
374 the installation just by doing the following.
377 Running scriptname 0.01...
381 By convention, scripts should be placed in a /script directory within your
382 distribution. To support less typing, if a script is located in the script
383 directory, you need refer to it by name only.
385 # The following are equivalent
386 install_script 'foo';
387 install_script 'script/foo';
391 no_index directory => 'examples';
392 no_index package => 'DB';
394 Quite often a distrubition will provide example scripts or testing
395 modules (.pm files) as well as the actual library modules.
397 In almost all situations, you do B<not> want these indexed in the CPAN
398 index, the master Perl packages list, or displayed on the
399 L<http://search.cpan.org/> website, you just want them along for the
402 The C<no_index> command is used to indicate directories or files where
403 there might be non-library .pm files or other files that the CPAN
404 indexer and websites such as L<http://search.cpan.org/> should
407 The most common situation is to ignore example or demo directories,
408 but a variety of different situations may require a C<no_index> entry.
410 Another common use for C<no_index> is to prevent the PAUSE indexer
411 complaining when your module makes changes inside a "package DB" block.
412 This is used to interact with the debugger in some specific ways.
414 See the F<META.yml> documentation for more details on what C<no_index>
417 The F<inc>, F<t> and F<share> (if C<install_share> is used) directories
418 are automatically C<no_index>'ed for you if found and do not require
421 To summarize, if you can see it on L<http://search.cpan.org/> and you
422 shouldn't be able to, you need a C<no_index> entry to remove it.
424 =head2 installdirs, install_as_*
426 installdirs 'site'; # the default
428 install_as_core; # alias for installdirs 'perl'
429 install_as_cpan; # alias for installdirs 'site'
430 install_as_site; # alias for installdirs 'site'
431 install_as_vendor; # alias for installdirs 'vendor'
433 The C<installdirs> and C<install_as> commands specify the location
434 where the module should be installed; this is the equivalent to
435 L<ExtUtils::MakeMaker>'s C<INSTALLDIRS> option. For almost all
436 regular modules, the default is recommended, and need not be
437 changed. Dual-life (core and CPAN) modules, as well as
438 vendor-specific modules, may need to use the other options.
440 If unsure, do not use this option.
444 The C<WriteAll> command is generally the last command in the file;
445 it writes out F<META.yml> and F<Makefile> so the user can run the
446 C<make>, C<make test>, C<make install> install sequence.
450 All extensions belong to the B<Module::Install::*> namespace, and
451 inherit from B<Module::Install::Base>. There are three categories
454 =head2 Standard Extensions
456 Methods defined by a standard extension may be called as plain functions
457 inside F<Makefile.PL>; a corresponding singleton object will be spawned
458 automatically. Other extensions may also invoke its methods just like
461 # delegates to $other_extension_obj->method_name(@args)
462 $self->method_name(@args);
464 At the first time an extension's method is invoked, a POD-stripped
465 version of it will be included under the F<inc/Module/Install/>
466 directory, and becomes I<fixed> -- i.e., even if the user had installed a
467 different version of the same extension, the included one will still be
470 If the author wish to upgrade extensions in F<inc/> with installed ones,
471 simply run C<perl Makefile.PL> again; B<Module::Install> determines
472 whether you are an author by the existence of the F<inc/.author/>
473 directory. End-users can reinitialize everything and become the author
474 by typing C<make realclean> and C<perl Makefile.PL>.
476 =head2 Private Extensions
478 Those extensions take the form of B<Module::Install::PRIVATE> and
479 B<Module::Install::PRIVATE::*>.
481 Authors are encouraged to put all existing F<Makefile.PL> magics into
482 such extensions (e.g. F<Module::Install::PRIVATE> for common bits;
483 F<Module::Install::PRIVATE::DISTNAME> for functions specific to a
486 Private extensions should not to be released on CPAN; simply put them
487 somewhere in your C<@INC>, under the C<Module/Install/> directory, and
488 start using their functions in F<Makefile.PL>. Like standard
489 extensions, they will never be installed on the end-user's machine,
490 and therefore never conflict with other people's private extensions.
492 =head2 Administrative Extensions
494 Extensions under the B<Module::Install::Admin::*> namespace are never
495 included with the distribution. Their methods are not directly
496 accessible from F<Makefile.PL> or other extensions; they are invoked
499 # delegates to $other_admin_extension_obj->method_name(@args)
500 $self->admin->method_name(@args);
502 These methods only take effect during the I<initialization> run, when
503 F<inc/> is being populated; they are ignored for end-users. Again,
504 to re-initialize everything, just run C<perl Makefile.PL> as the author.
506 Scripts (usually one-liners in F<Makefile>) that wish to dispatch
507 B<AUTOLOAD> functions into administrative extensions (instead of
508 standard extensions) should use the B<Module::Install::Admin> module
509 directly. See L<Module::Install::Admin> for details.
513 Detailed information is provided for all (some) of the relevant
514 modules via their own POD documentation.
516 =head2 Module::Install::AutoInstall
518 Provides C<auto_install()> to automatically fetch and install
521 The use of C<auto_install> is B<strongly> discouraged in any distribution
522 to be uploaded to the CPAN, as the use of it violates the normal CPAN
523 client to toolchain communication protocol.
525 Support may be dropped at a future time, with some alternative process
526 providing the equivalent functionality.
528 =head2 Module::Install::Base
530 The base class for all extensions
532 =head2 Module::Install::Build
534 Provides integration with L<Module::Build> via C<&Build-E<gt>write>.
536 =head2 Module::Install::Bundle
538 Provides the C<bundle> family of commands, allowing you to bundle
539 another CPAN distribution within your distribution.
541 =head2 Module::Install::Fetch
543 Handles install-time fetching of files from remote servers via
546 =head2 Module::Install::Include
548 Provides the C<include> family of commands for embedding modules
549 that are only need at build-time in your distribution and won't
552 =head2 Module::Install::Inline
554 Provides C<&Inline-E<gt>write> to replace B<Inline::MakeMaker>'s
555 functionality for making B<Inline>-based modules (and cleaning up).
557 However, you should invoke this with C<WriteAll( inline => 1 )>.
559 =head2 Module::Install::Makefile
561 Provides C<&Makefile-E<gt>write> to generate a F<Makefile> for you
564 =head2 Module::Install::Metadata
566 Provides C<&Meta-E<gt>write> to generate a F<META.yml> file for your
569 =head2 Module::Install::PAR
571 Makes pre-compiled module binary packages from the built F<blib>
572 directory, and download existing ones to save recompiling.
574 =head2 Module::Install::Run
576 Determines if commands are available on the user's machine, and runs
577 them via B<IPC::Run3>.
579 =head2 Module::Install::Scripts
581 Handles packaging and installation of scripts to various bin dirs.
583 =head2 Module::Install::Win32
585 Functions for installing modules on Win32 and finding/installing
586 F<nmake.exe> for users that need it.
588 =head2 Module::Install::WriteAll
590 Provides the C<WriteAll>, which writes all the requires files,
591 such as F<META.yml> and either F<Makefile> or F<Build>.
593 C<WriteAll> takes four optional named parameters:
597 =item C<check_nmake> (defaults to true)
599 If true, invokes functions with the same name.
601 I<The use of this param is no longer recommended.>
603 =item C<inline> (defaults to false)
605 If true, invokes C<&Inline-E<gt>write> L<Inline> modules.
607 =item C<meta> (defaults to true)
609 If true, writes a C<META.yml> file.
611 =item C<sign> (defaults to false)
613 If true, invokes C<sign> command to digitally sign erm... something.
617 =head2 Module::Install::Admin::Find
619 Package-time functions for finding extensions, installed packages
620 and files in subdirectories.
622 =head2 Module::Install::Admin::Manifest
624 Package-time functions for manipulating and updating the
627 =head2 Module::Install::Admin::Metadata
629 Package-time functions for manipulating and updating the
632 =head2 Module::Install::Admin::ScanDeps
634 Package-time scanning for non-core dependencies via B<Module::ScanDeps>
635 and B<Module::CoreList>.
639 =head2 What are the benefits of using B<Module::Install>?
641 Here is a brief overview of the reasons:
645 =item * Extremely easy for beginners to learn
647 =item * Does everything ExtUtils::MakeMaker does.
649 =item * Does it with a dramatically simpler syntax.
651 =item * Automatically scans for metadata for you.
653 =item * Requires no installation for end-users.
655 =item * Guaranteed forward-compatibility.
657 =item * Automatically updates your MANIFEST.
659 =item * Distributing scripts is easy.
661 =item * Include prerequisite modules (less dependencies to install)
663 =item * Auto-installation of prerequisites.
665 =item * Support for L<Inline>-based modules.
667 =item * Support for L<File::ShareDir> shared data files
669 =item * Support for precompiled L<PAR> binaries.
671 =item * Deals with Win32 install issues for you.
675 By greatly shrinking and simplifying the syntax, B<Module::Install>
676 keeps the amount of work required to maintain your F<Makefile.PL>
677 files to an absolute minimum.
679 And if you maintain more than one module than needs to do unusual
680 installation tricks, you can create a specific module to abstract
681 away this complexity.
683 =head2 Module::Install isn't at 1.00 yet, is it safe to use yet?
685 As long as you are going to periodically do incremental releases
686 to get any bug fixes and new functionality, yes.
688 You should also B<strongly> avoid the use of C<auto_install>.
690 If you don't plan to do incremental releases, it might be a good
691 idea to continue to wait for a while.
693 =head1 COOKBOOK / EXAMPLES
695 The following are some real-life examples of F<Makefile.PL> files
696 using B<Module::Install>.
700 L<Method::Alias> is a trivially-small utility module, with almost the
701 smallest possible F<Makefile.PL>.
703 use inc::Module::Install;
706 all_from 'lib/Method/Alias.pm';
707 test_requires 'Test::More' => '0.42';
711 L<File::HomeDir> locates your home directory on any platform. It needs
712 an installer that can handle different dependencies on different platforms.
714 use inc::Module::Install;
717 all_from 'lib/File/HomeDir.pm';
718 requires 'File::Spec' => '0.80';
719 test_requires 'Test::More' => '0.47';
721 if ( $MacPerl::Version ) {
722 # Needed on legacy Mac OS 9
723 requires 'Mac::Files' => 0;
726 if ( $^O eq 'MXWin32' ) {
727 # Needed on Windows platforms
728 requires 'Win32::TieRegistry' => 0;
735 Implement L<Module::Install::Compiled> and Module::Install::Admin::Compiled
736 to integrate the L<Module::Compiled> "perl 6 to perl 5" functionality with
738 Because this would add SIGNIFICANT dependencies (i.e. pugs!) this should
739 almost certainly be distributed as a seperate distribution.
741 Go over POD docs in detail.
743 Test recursive Makefile directories
745 The test suite needs a great deal more test scripts.
747 Dependencies on shared libraries (libxml/libxml.dll etc) and binary files
748 so that debian/Win32/etc autopackaging applications can create the
749 appropriate package-level dependencies there.
751 EU::MM 6.06_03+ supports META.yml natively. Maybe probe for that?
755 L<Module::Install::Philosophy>
757 L<inc::Module::Install>
759 L<Module::Install::AutoInstall>
761 L<Module::Install::Base>
763 L<Module::Install::Bundle>
765 L<Module::Install::Build>
767 L<Module::Install::MakeMaker>
769 L<Module::Install::Share>
771 L<Module::Install::Admin>
773 L<Module::Install::Admin::Include>
775 L<Module::Install::Admin::Manifest>
777 L<CPAN::MakeMaker>, L<Inline::MakeMaker>
779 L<ExtUtils::MakeMaker>
783 Bugs should be reported via the CPAN bug tracker at
785 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install>
787 For other issues, contact the (topmost) author.
791 Adam Kennedy E<lt>adamk@cpan.orgE<gt>
793 Audrey Tang E<lt>autrijus@autrijus.orgE<gt>
795 Brian Ingerson E<lt>ingy@cpan.orgE<gt>
799 Copyright 2002 - 2009 Brian Ingerson, Audrey Tang and Adam Kennedy.
801 This program is free software; you can redistribute it and/or
802 modify it under the same terms as Perl itself.