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 # Load the Module::Install bundled in ./inc/
12 use inc::Module::Install;
13 # Define metadata
15 name 'Your-Module';
16 all_from 'lib/Your/Module.pm';
17 # Specific dependencies
19 requires 'Carp' => 0;
20 requires 'File::Spec' => '0.80';
21 build_requires 'Test::More' => '0.42';
22 recommends 'Your::OtherModule' => '0.01';
23 no_index 'directory' => 'demos';
25 install_script 'bin/myscript';
27 auto_install;
29 WriteAll;
30 Quickly upgrade a legacy ExtUtil::MakeMaker installer:
32 # Drop-in replacement to ExtUtils::MakeMaker
34 use inc::Module::Install;
35 WriteMakefile( ... );
36 A dummy Build.PL so we can work with Module::Build as well:
38 # Dear Distribution Packager. This use of require is intentional.
40 # Module::Install detects Build.PL usage and acts accordingly.
41 require 'Makefile.PL';
42
44 Module::Install is a package for writing installers for CPAN (or
45 CPAN-like) distributions that are clean, simple, minimalist, act in a
46 strictly correct manner with both the ExtUtils::MakeMaker and Mod‐
47 ule::Build build systems, and will run on any Perl installation version
48 5.004 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
58 "SYNOPSIS" from above and save it as your own Makefile.PL. Then modify
59 the file to suit your own particular case, using the list of commands
60 documented in "COMMANDS" below.
61 If all you want to do is write an installer, go and do that now. You
63 don't really need the rest of this description unless you are inter‐
64 ested in the details.
65
67 The motivation behind Module::Install is that distributions need to
68 interact with a large number of different versions of perl and module
69 installers infrastructure, primarily CPAN.pm, CPANPLUS.pm, ExtU‐
70 tils::MakeMaker and Module::Build.
71 These have accumulated greatly varying feature and bug profiles over
73 the years, and it is now very difficult to write an installer that will
74 work properly using only the installed versions of these modules,
75 For example, the CPAN.pm version shipped with Perl 5.005 is now 5+
77 years old and considered highly buggy, yet it still exists on quite a
78 number of legacy machines.
79 Rather than try to target one specific installer and/or make you add
81 twisty workaround expressions to every piece of install code you write,
82 Module::Install will copy part of itself into each module distribution
83 it creates.
84 This allows new improvements to be used in your installers regardless
86 of the age of the system a distribution is being installed on, at the
87 cost of a small increase in the size of your distribution.
88 History
90 This module was originally written by Brian Ingerson as a smart drop-in
92 replacement for ExtUtils::MakeMaker.
93 For more information, see Brian's Creating Module Distributions with
95 Module::Install in June 2003 issue of The Perl Journal
96 (<http://www.tpj.com/issues/>).
97 For a lot more information, and some personal opinions on the module
99 and its creation, see Module::Install::Philosophy.
100
102 The following are the most common commands generally used in install‐
103 ers.
104 It is far from an exhaustive list, as many of the plugins provide com‐
106 mands to work in more details that you would normally need.
107 name
109 name 'My-Module';
111 The name command is compulsory command, generally the first.
113 It provides the name of your distribution, which for a module like
115 Your::Module would normally be "Your-Module".
116 This naming scheme is not hard and fast and you should note that dis‐
118 tributions are actually a seperate naming scheme.
119 For example the LWP modules come in a distribution called "lib‐
121 www-perl".
122 all_from
124 all_from 'lib/My/Module.pm';
126 For most simple Perl distributions that feature one dominant module or
128 class as the base, you can get the most Do What I Mean functionality by
129 using the all_from command, which will try to extract as much metadata
130 as possible from the Perl code and POD in that primary module.
131 Functionally, "all_from" is equivalent to "abstract_from" +
133 "author_from" + "version_from" + "license_from" + "perl_version_from".
134 See below for details.
135 If any of these values are set already before "all_from" is used, they
137 will kept and not be overwritten.
138 abstract
140 abstract 'This distribution does something';
142 All distributions have an abstract, a short description of the distri‐
144 bution as a whole. It is usually around 30-70 characters long.
145 The "abstract" command is used to explicitly set the abstract for the
147 distribution, at least as far as the metadata file for the distribution
148 is concerned.
149 abstract_from
151 abstract_from 'lib/My/Module.pm';
153 The "abstract_from" command retrieves the abstract from a particular
155 file contained in the distribution package. Most often this is done
156 from the main module, where "Module::Install" will read the POD and use
157 whatever is in the "=head1 NAME" section (with module name stripped if
158 needed)
159 "abstract_from" is set as part of "all_from".
161 author
163 author 'Adam Kennedy <adamk@cpan.org>';
165 The distribution metadata contains information on the primary author or
167 the distribution, or the primary maintainer if the original author is
168 no longer involved. It should generally be specified in the form of an
169 email address.
170 It you don't want to give away a real email address, you should use the
172 "CPANID@cpan.org" address you recieve automatically when you got your
173 PAUSE account.
174 The "author" command is used to explicitly set this value.
176 author_from
178 author_from 'lib/My/Module.pm';
180 The "author_from" command retrieves the author from a particular file
182 contained in the distribution package. Most often this is done using
183 the main module, where Module::Install will read the POD and use what‐
184 ever it can find in the "=head1 AUTHOR" section.
185 version
187 version '0.01';
189 The "version" command is used to specify the version of the distribu‐
191 tion, as distinct from the version of any single module within the dis‐
192 tribution.
193 Of course, in almost all cases you want it to match the version of the
195 primary module within the distribution, which you can do using "ver‐
196 sion_from".
197 version_from
199 version_from 'lib/My/Module.pm';
201 The "version_from" command retrieves the distribution version from a
203 particular file contained in the distribution package. Most often this
204 is done from the main module.
205 "version_from" will look for the first time you set $VERSION and use
207 the same value, using a technique consistent with various other module
208 version scanning tools.
209 license
211 license 'perl';
213 The "license" command specifies the license for the distribution.
215 Most often this value will be 'perl', meaning "the same as for Perl
217 itself". Other allowed values include 'gpl', 'lgpl', 'bsd', 'MIT', and
218 'artistic'.
219 This value is always considered a summary, and it is normal for authors
221 to include a LICENSE file in the distribution, containing the full
222 license for the distribution.
223 You are also reminded that if the distribution is intended to be
225 uploaded to the CPAN, it must be an OSI-approved open source license.
226 Commercial software is not permitted on the CPAN.
227 license_from
229 license_from 'lib/My/Module.pm';
231 The "license_from" command retrieves the distribution license from a
233 particular file contained in the distribution package. Most often this
234 is done from the main module.
235 "license_from" will look inside the POD within the indicated file for a
237 licensing or copyright-related section and scan for a variety of
238 strings that identify the general class of license.
239 At this time it supports only the 6 values mentioned above in the
241 "license" command summary.
242 perl_version
244 perl_version '5.006';
246 The "perl_version" command is used to specify the minimum version of
248 the perl interpreter your distribution requires.
249 When specifying the version, you should try to use the normalised ver‐
251 sion string. Perl version segments are 3 digits long, so a dependency
252 on Perl 5.6 will become '5.006' and Perl 5.10 will become '5.010'.
253 perl_version_from
255 perl_version_from 'lib/My/Module.pm'
257 The "perl_version_from" command retrieves the minimum perl interpreter
259 version from a particular file contained in the distribution package.
260 Most often this is done from the main module.
261 The minimum version is detected by scanning the file for "use 5.xxx"
263 pragma calls in the module file.
264 requires
266 requires 'List::Util' => 0;
268 requires 'LWP' => '5.69';
269 The "requires" command indicates a normal run-time dependency of your
271 distribution on another module. Most distributions will have one or
272 more of these commands, indicating which CPAN (or otherwise) modules
273 your distribution needs.
274 A "requires" dependency can be verbalised as "If you wish to install
276 and use this distribution, you must first install these modules first".
277 Note that the dependency is on a module and not a distribution. This is
279 to ensure that your dependency stays correct, even if the module is
280 moved or merged into a different distribtion, as is occasionally the
281 case.
282 A dependency on version zero indicates any version of module is suffi‐
284 cient. Versions should generally be quoted for clarity.
285 build_requires
287 build_requires 'Test::More' => '0.47';
289 The "build_requires" command indicates a build-time dependency for the
291 distribution. The specification format is identical to that of the
292 "requires" command.
293 The "build_requires" command is distinct from the "requires" command in
295 that it indicates a module that is need only during the building and
296 testing of the distribution (often a period of only a few seconds) but
297 will not be needed after the distribution is installed.
298 The most common case by far for the use of "build_requires" is for var‐
300 ious testing modules to be specified in this way.
301 The "build_requires" command is used to allow the installer some flexi‐
303 bility in how it provides the module.
304 For example, the "include" command is sometimes used by some authors
306 along with "build_requires" to bundle a small well-tested module into
307 the distribution package itself rather than inflict yet another module
308 installation on the user.
309 As another example, when building a binary operating system packages
311 (such as Debian's .deb packages) from a CPAN distribution, the testing
312 is done once by the packager, and so the "build_requires" dependency
313 can be safely ignored by the binary package.
314 requires_external_bin
316 requires_external_bin 'cvs';
318 As part of its role as the dominant "glue" language, a lot of Perl mod‐
320 ules run commands or programs on the host system.
321 The "requires_external_bin" command is used to verify that a particular
323 command is available on the host system.
324 Unlike a missing Perl module, a missing external binary is unresolvable
326 at make-time, and so the Makefile.PL run will abort with a "NA" (Not
327 Applicable) result.
328 In future, this command will also add additional information to the
330 metadata for the dist, so that auto-packagers for particular operating
331 system are more-easily able to auto-discover the appropriate non-Perl
332 packages needed as a dependency.
333 install_script
335 install_script 'bin/scriptname'
337 The "install_script" command provides support for the installation of
339 scripts that will become available at the console on both Unix and Win‐
340 dows (by wrapping it up as a .bat file).
341 Note that is it normal to not put a .pl on the end of such scripts, so
343 that they feel more natural when being used.
344 In the example above, the bin/scriptname program could be run after the
346 installation just by doing the following.
347 > scriptname
349 Running scriptname 0.01...
350 >
352 no_index
354 no_index directory => 'examples';
356 no_index package => 'DB';
357 Quite often a distrubition will provide example or testing modules (.pm
359 files) as well as the actual library modules.
360 In almost all situations, you do not want these indexed in the master
362 Perl packages list, you just want them along for the ride.
363 The "no_index" command is used to indicate locations or modules where
365 there might be non-library .pm files that the CPAN indexer and websites
366 such as <http://search.cpan.org/> should explicitly ignore.
367 The most common situation is to ignore example or demo directories, but
369 a variety of different situations may require a "no_index" entry.
370 Another common use for "no_index" is to prevent the PAUSE indexer com‐
372 plaining when your module makes changes inside a "package DB" block.
373 This is used to interact with the debugger in some specific ways.
374 See the META.yml documentation for more details on what "no_index" val‐
376 ues are allowed.
377 The inc and t directories are automatically "no_index"'ed for you and
379 do not require a command.
380 To summarise, if you can see it on <http://search.cpan.org/> and you
382 shouldn't be able to, you need a "no_index" entry.
383 WriteAll
385 The "WriteAll" command is generally the last command; it writes out
387 META.yml and Makefile (or Build) so the user can run the "make", "make
388 test", "make install" process. (or the Build.PL equivalents).
389
391 All extensions belong to the Module::Install::* namespace, and inherit
392 from Module::Install::Base. There are three categories of extensions:
393 Standard Extensions
395 Methods defined by a standard extension may be called as plain func‐
397 tions inside Makefile.PL; a corresponding singleton object will be
398 spawned automatically. Other extensions may also invoke its methods
399 just like their own methods:
400 # delegates to $other_extension_obj->method_name(@args)
402 $self->method_name(@args);
403 At the first time an extension's method is invoked, a POD-stripped ver‐
405 sion of it will be included under the inc/Module/Install/ directory,
406 and becomes fixed -- i.e., even if the user had installed a different
407 version of the same extension, the included one will still be used
408 instead.
409 If the author wish to upgrade extensions in inc/ with installed ones,
411 simply run "perl Makefile.PL" again; Module::Install determines whether
412 you are an author by the existence of the inc/.author/ directory. End-
413 users can reinitialize everything and become the author by typing "make
414 realclean" and "perl Makefile.PL".
415 Private Extensions
417 Those extensions take the form of Module::Install::PRIVATE and Mod‐
419 ule::Install::PRIVATE::*.
420 Authors are encouraged to put all existing Makefile.PL magics into such
422 extensions (e.g. Module::Install::PRIVATE for common bits; Mod‐
423 ule::Install::PRIVATE::DISTNAME for functions specific to a distribu‐
424 tion).
425 Private extensions should not to be released on CPAN; simply put them
427 somewhere in your @INC, under the "Module/Install/" directory, and
428 start using their functions in Makefile.PL. Like standard extensions,
429 they will never be installed on the end-user's machine, and therefore
430 never conflict with other people's private extensions.
431 Administrative Extensions
433 Extensions under the Module::Install::Admin::* namespace are never
435 included with the distribution. Their methods are not directly acces‐
436 sible from Makefile.PL or other extensions; they are invoked like this:
437 # delegates to $other_admin_extension_obj->method_name(@args)
439 $self->admin->method_name(@args);
440 These methods only take effect during the initialization run, when inc/
442 is being populated; they are ignored for end-users. Again, to re-ini‐
443 tialize everything, just run "perl Makefile.PL" as the author.
444 Scripts (usually one-liners in Makefile) that wish to dispatch AUTOLOAD
446 functions into administrative extensions (instead of standard exten‐
447 sions) should use the Module::Install::Admin module directly. See Mod‐
448 ule::Install::Admin for details.
449 Extention List
451 Module::Install::AutoInstall
453 Provides "auto_install()" to automatically fetch and install pre‐
454 requisites.
455 Module::Install::Base
457 The base class for all extensions
458 Module::Install::Build
460 Provides integration with Module::Build via "&Build->write".
461 Module::Install::Bundle
463 Provides the "bundle" family of commands, allowing you to bundle
464 another CPAN distribution within your distribution.
465 Module::Install::Fetch
467 Handles install-time fetching of files from remote servers via FTP
468 and HTTP.
469 Module::Install::Include
471 Provides the "include" family of commands for embedding modules
472 that are only need at build-time in your distribution and won't be
473 installed.
474 Module::Install::Inline
476 Provides "&Inline->write" to replace Inline::MakeMaker's function‐
477 ality for making Inline-based modules (and cleaning up).
478 However, you should invoke this with "WriteAll( inline =" 1 )>.
480 Module::Install::Makefile
482 Provides "&Makefile->write" to generate a Makefile for you distri‐
483 bution.
484 Module::Install::Makefile::Name
486 Guessing the distribution name.
487 Module::Install::Makefile::Version
489 Guessing the distribution version.
490 Module::Install::Metadata
492 Provides "&Meta->write" to generate a META.yml file for your dis‐
493 tribution.
494 Module::Install::PAR
496 Makes pre-compiled module binary packages from the built blib
497 directory, and download existing ones to save recompiling.
498 Module::Install::Run
500 Determines if commands are available on the user's machine, and
501 runs them via IPC::Run3.
502 Module::Install::Scripts
504 Handles packaging and installation of scripts to various bin dirs.
505 Module::Install::Win32
507 Functions for installing modules on Win32 and finding/installing
508 nmake.exe for users that need it.
509 Module::Install::WriteAll
511 Provides the "WriteAll", which writes all the requires files, such
512 as META.yml and either Makefile or Build.
513 "WriteAll" takes four optional named parameters:
515 "check_nmake" (defaults to true)
517 If true, invokes functions with the same name.
518 "inline" (defaults to false)
520 If true, invokes "&Inline->write" Inline modules.
521 "meta" (defaults to true)
523 If true, writes a "META.yml" file.
524 "sign" (defaults to false)
526 If true, invokes "sign" command to digitally sign erm... some‐
527 thing.
528 Module::Install::Admin::Find
530 Package-time functions for finding extensions, installed packages
531 and files in subdirectories.
532 Module::Install::Admin::Manifest
534 Package-time functions for manipulating and updating the MANIFEST
535 file.
536 Module::Install::Admin::Metadata
538 Package-time functions for manipulating and updating the META.yml
539 file.
540 Module::Install::Admin::ScanDeps
542 Package-time scanning for non-core dependencies via Module::Scan‐
543 Deps and Module::CoreList.
544 Detailed information is provided for all (some) of the relevant modules
546 via their own POD documentation.
547
549 What are the benefits of using Module::Install?
550 Here is a brief overview of the reasons:
552 * Extremely easy for beginners to learn
554 * Does everything ExtUtils::MakeMaker does.
555 * Does it with a dramatically simpler syntax.
556 * Automatically scans for metadata for you.
557 * Requires no installation for end-users.
558 * Generates a stock Build.PL for Module::Build users.
559 * Guaranteed forward-compatibility.
560 * Automatically updates your MANIFEST.
561 * Distributing scripts is easy.
562 * Include prerequisite modules (less dependencies to install)
563 * Auto-installation of prerequisites.
564 * Support for Inline-based modules.
565 * Support for File::ShareDir shared data files
566 * Support for precompiled PAR binaries.
567 * Deals with Win32 install issues for you.
568 By greatly shrinking and simplifying the syntax, Module::Install keeps
570 the amount of work required to maintain your Makefile.PL files to an
571 absolute minimum.
572 And if you maintain more than one module than needs to do unusual
574 installation tricks, you can create a specific module to abstract away
575 this complexity.
576 Module::Install isn't at 1.00 yet, is it safe to use yet?
578 ...
580
582 The following are some real-life examples of Makefile.PL files using
583 Module::Install.
584 Method::Alias
586 Method::Alias is a trivially-small utility module, with almost the
588 smallest possible Makefile.PL.
589 use inc::Module::Install;
591 name 'Method-Alias';
593 all_from 'lib/Method/Alias.pm';
594 build_requires 'Test::More' => '0.42';
595 File::HomeDir
597 File::HomeDir locates your home directory on any platform. It needs an
599 installer that can handle different dependencies on different plat‐
600 forms.
601 use inc::Module::Install;
603 name 'File-HomeDir';
605 all_from 'lib/File/HomeDir.pm';
606 requires 'File::Spec' => '0.80';
607 build_requires 'Test::More' => '0.47';
608 if ( $MacPerl::Version ) {
610 # Needed on legacy Mac OS 9
611 requires 'Mac::Files' => 0;
612 }
613 if ( $^O eq 'MXWin32' ) {
615 # Needed on Windows platforms
616 requires 'Win32::TieRegistry' => 0;
617 }
618 auto_install;
620 WriteAll;
621
623 Module::Install::Philosophy
624 inc::Module::Install
626 Module::Install::AutoInstall
628 Module::Install::Base
630 Module::Install::Bundle
632 Module::Install::Build
634 Module::Install::MakeMaker
636 Module::Install::Share
638 Module::Install::Admin
640 Module::Install::Admin::Include
642 Module::Install::Admin::Manifest
644 CPAN::MakeMaker, Inline::MakeMaker
646 ExtUtils::MakeMaker, Module::Build
648
650 Brian Ingerson <INGY@cpan.org>
651 Audrey Tang <autrijus@autrijus.org>
653 Adam Kennedy <cpan@ali.as>
655
657 Copyright 2002, 2003, 2004, 2005, 2006 by Brian Ingerson, Audrey Tang,
658 Adam Kennedy.
659 This program is free software; you can redistribute it and/or modify it
661 under the same terms as Perl itself.
662 See <http://www.perl.com/perl/misc/Artistic.html>
664perl v5.8.8 2007-03-05 Module::Install(3)