1Module::Install(3)    User Contributed Perl Documentation   Module::Install(3)
2
3
4

NAME

6       Module::Install - Standalone, extensible Perl module installer
7

SYNOPSIS

9       In your Makefile.PL: (Recommended Usage)
10
11         use inc::Module::Install;
12
13         # Define metadata
14         name           'Your-Module';
15         all_from       'lib/Your/Module.pm';
16
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';
23
24         WriteAll;
25
26       Quickly upgrade a legacy ExtUtil::MakeMaker installer:
27
28         use inc::Module::Install;
29         WriteMakefile( ... );
30

DESCRIPTION

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
37       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
42   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
48       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

How it Works

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
58       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
62       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
66       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
71       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
75   History
76       This module was originally written by Brian Ingerson as a smart drop-in
77       replacement for ExtUtils::MakeMaker.
78
79       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
83       For a lot more information, and some personal opinions on the module
84       and its creation, see Module::Install::Philosophy.
85

COMMON COMMANDS

87       The following are the most common commands generally used in
88       installers.
89
90       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
93   name
94         name 'My-Module';
95
96       The name command is compulsory command, generally the first.
97
98       It provides the name of your distribution, which for a module like
99       Your::Module would normally be "Your-Module".
100
101       This naming scheme is not hard and fast and you should note that
102       distributions are actually a separate naming scheme from modules.
103
104       For example the LWP modules come in a distribution called
105       "libwww-perl".
106
107   all_from
108         all_from 'lib/My/Module.pm';
109
110       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
115       Functionally, "all_from" is equivalent to "abstract_from" +
116       "author_from" + "version_from" + "license_from" + "perl_version_from".
117       See below for details.
118
119       If any of these values are set already before "all_from" is used, they
120       will kept and not be overwritten.
121
122   abstract
123         abstract 'This distribution does something';
124
125       All distributions have an abstract, a short description of the
126       distribution as a whole. It is usually around 30-70 characters long.
127
128       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
132   abstract_from
133         abstract_from 'lib/My/Module.pm';
134
135       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
141       "abstract_from" is set as part of "all_from".
142
143   author
144         author 'Adam Kennedy <adamk@cpan.org>';
145
146       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
151       It you don't want to give away a real email address, you should use the
152       "CPANID@cpan.org" address you receive automatically when you got your
153       PAUSE account.
154
155       The "author" command is used to explicitly set this value.
156
157   author_from
158         author_from 'lib/My/Module.pm';
159
160       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
165   version
166         version '0.01';
167
168       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
172       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
176   version_from
177         version_from 'lib/My/Module.pm';
178
179       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
183       "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
187   license
188         license 'perl';
189
190       The "license" command specifies the license for the distribution.
191
192       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
196       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
200       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
204   license_from
205         license_from 'lib/My/Module.pm';
206
207       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
211       "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
215       At this time it supports only the 6 values mentioned above in the
216       "license" command summary.
217
218   perl_version
219         perl_version '5.006';
220
221       The "perl_version" command is used to specify the minimum version of
222       the perl interpreter your distribution requires.
223
224       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
229   perl_version_from
230         perl_version_from 'lib/My/Module.pm'
231
232       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
236       The minimum version is detected by scanning the file for "use 5.xxx"
237       pragma calls in the module file.
238
239   recommends
240         recommends 'Text::CSV_XS' => '0.50'
241
242       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
246       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
250   requires
251         requires 'List::Util' => 0;
252         requires 'LWP'        => '5.69';
253
254       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
259       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
262       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
267       A dependency on version zero indicates any version of module is
268       sufficient. Versions should generally be quoted for clarity.
269
270   test_requires
271         test_requires 'Test::More' => '0.47';
272
273       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
277       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
282       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
287       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
292   configure_requires
293         configure_requires 'File::Spec' => '0.80';
294
295       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
299       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
304       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
309       The "configure_requires" command creates an entry in the special
310       configure_requires: key in the distribution's META.yml file.
311
312       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
317       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
320       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
324   requires_external_bin
325         requires_external_bin 'cvs';
326
327       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
330       The "requires_external_bin" command is used to verify that a particular
331       command is available on the host system.
332
333       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
337       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
342   install_script
343         # The following are equivalent
344         install_script 'script/scriptname'
345
346       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
350       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
353       In the example above, the script/scriptname program could be run after
354       the installation just by doing the following.
355
356         > scriptname
357         Running scriptname 0.01...
358
359         >
360
361       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
365         # The following are equivalent
366         install_script 'foo';
367         install_script 'script/foo';
368
369   no_index
370         no_index directory => 'examples';
371         no_index package   => 'DB';
372
373       Quite often a distrubition will provide example scripts or testing
374       modules (.pm files) as well as the actual library modules.
375
376       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
381       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
386       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
389       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
393       See the META.yml documentation for more details on what "no_index"
394       values are allowed.
395
396       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
400       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
403   installdirs, install_as_*
404         installdirs 'site'; # the default
405
406         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
411       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
418       If unsure, do not use this option.
419
420   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

EXTENSIONS

426       All extensions belong to the Module::Install::* namespace, and inherit
427       from Module::Install::Base.  There are three categories of extensions:
428
429   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
435           # delegates to $other_extension_obj->method_name(@args)
436           $self->method_name(@args);
437
438       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
444       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
450   Private Extensions
451       Those extensions take the form of Module::Install::PRIVATE and
452       Module::Install::PRIVATE::*.
453
454       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
459       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
465   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
471           # delegates to $other_admin_extension_obj->method_name(@args)
472           $self->admin->method_name(@args);
473
474       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
478       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

EXTENSIONS

484       Detailed information is provided for all (some) of the relevant modules
485       via their own POD documentation.
486
487   Module::Install::AutoInstall
488       Provides "auto_install()" to automatically fetch and install
489       prerequisites.
490
491       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
495       Support may be dropped at a future time, with some alternative process
496       providing the equivalent functionality.
497
498   Module::Install::Base
499       The base class for all extensions
500
501   Module::Install::Build
502       Provides integration with Module::Build via "&Build->write".
503
504   Module::Install::Bundle
505       Provides the "bundle" family of commands, allowing you to bundle
506       another CPAN distribution within your distribution.
507
508   Module::Install::Fetch
509       Handles install-time fetching of files from remote servers via FTP and
510       HTTP.
511
512   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
517   Module::Install::Inline
518       Provides "&Inline->write" to replace Inline::MakeMaker's functionality
519       for making Inline-based modules (and cleaning up).
520
521       However, you should invoke this with "WriteAll( inline => 1 )".
522
523   Module::Install::Makefile
524       Provides "&Makefile->write" to generate a Makefile for you
525       distribution.
526
527   Module::Install::Metadata
528       Provides "&Meta->write" to generate a META.yml file for your
529       distribution.
530
531   Module::Install::PAR
532       Makes pre-compiled module binary packages from the built blib
533       directory, and download existing ones to save recompiling.
534
535   Module::Install::Run
536       Determines if commands are available on the user's machine, and runs
537       them via IPC::Run3.
538
539   Module::Install::Scripts
540       Handles packaging and installation of scripts to various bin dirs.
541
542   Module::Install::Win32
543       Functions for installing modules on Win32 and finding/installing
544       nmake.exe for users that need it.
545
546   Module::Install::WriteAll
547       Provides the "WriteAll", which writes all the requires files, such as
548       META.yml and either Makefile or Build.
549
550       "WriteAll" takes four optional named parameters:
551
552       "check_nmake" (defaults to true)
553           If true, invokes functions with the same name.
554
555           The use of this param is no longer recommended.
556
557       "inline" (defaults to false)
558           If true, invokes "&Inline->write" Inline modules.
559
560       "meta" (defaults to true)
561           If true, writes a "META.yml" file.
562
563       "sign" (defaults to false)
564           If true, invokes "sign" command to digitally sign erm... something.
565
566   Module::Install::Admin::Find
567       Package-time functions for finding extensions, installed packages and
568       files in subdirectories.
569
570   Module::Install::Admin::Manifest
571       Package-time functions for manipulating and updating the MANIFEST file.
572
573   Module::Install::Admin::Metadata
574       Package-time functions for manipulating and updating the META.yml file.
575
576   Module::Install::Admin::ScanDeps
577       Package-time scanning for non-core dependencies via Module::ScanDeps
578       and Module::CoreList.
579

FAQ

581   What are the benefits of using Module::Install?
582       Here is a brief overview of the reasons:
583
584       ·   Extremely easy for beginners to learn
585
586       ·   Does everything ExtUtils::MakeMaker does.
587
588       ·   Does it with a dramatically simpler syntax.
589
590       ·   Automatically scans for metadata for you.
591
592       ·   Requires no installation for end-users.
593
594       ·   Guaranteed forward-compatibility.
595
596       ·   Automatically updates your MANIFEST.
597
598       ·   Distributing scripts is easy.
599
600       ·   Include prerequisite modules (less dependencies to install)
601
602       ·   Auto-installation of prerequisites.
603
604       ·   Support for Inline-based modules.
605
606       ·   Support for File::ShareDir shared data files
607
608       ·   Support for precompiled PAR binaries.
609
610       ·   Deals with Win32 install issues for you.
611
612       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
616       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
620   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
624       You should also strongly avoid the use of "auto_install".
625
626       If you don't plan to do incremental releases, it might be a good idea
627       to continue to wait for a while.
628

COOKBOOK / EXAMPLES

630       The following are some real-life examples of Makefile.PL files using
631       Module::Install.
632
633   Method::Alias
634       Method::Alias is a trivially-small utility module, with almost the
635       smallest possible Makefile.PL.
636
637         use inc::Module::Install;
638
639         name          'Method-Alias';
640         all_from      'lib/Method/Alias.pm';
641         test_requires 'Test::More' => '0.42';
642
643   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
648         use inc::Module::Install;
649
650         name          'File-HomeDir';
651         all_from      'lib/File/HomeDir.pm';
652         requires      'File::Spec' => '0.80';
653         test_requires 'Test::More' => '0.47';
654
655         if ( $MacPerl::Version ) {
656             # Needed on legacy Mac OS 9
657             requires 'Mac::Files' => 0;
658         }
659
660         if ( $^O eq 'MXWin32' ) {
661             # Needed on Windows platforms
662             requires 'Win32::TieRegistry' => 0;
663         }
664
665         WriteAll;
666

TO DO

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 separate distribution.
673
674       Go over POD docs in detail.
675
676       Test recursive Makefile directories
677
678       The test suite needs a great deal more test scripts.
679
680       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
684       EU::MM 6.06_03+ supports META.yml natively.  Maybe probe for that?
685

SEE ALSO

687       Module::Install::Philosophy
688
689       inc::Module::Install
690
691       Module::Install::AutoInstall
692
693       Module::Install::Base
694
695       Module::Install::Bundle
696
697       Module::Install::Build
698
699       Module::Install::MakeMaker
700
701       Module::Install::Share
702
703       Module::Install::Admin
704
705       Module::Install::Admin::Include
706
707       Module::Install::Admin::Manifest
708
709       CPAN::MakeMaker, Inline::MakeMaker
710
711       ExtUtils::MakeMaker
712

SUPPORT

714       Bugs should be reported via the CPAN bug tracker at
715
716       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install
717       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install>
718
719       For other issues, contact the (topmost) author.
720

AUTHORS

722       Adam Kennedy <adamk@cpan.org>
723
724       Audrey Tang <autrijus@autrijus.org>
725
726       Brian Ingerson <ingy@cpan.org>
727
729       Copyright 2002 - 2010 Brian Ingerson, Audrey Tang and Adam Kennedy.
730
731       This program is free software; you can redistribute it and/or modify it
732       under the same terms as Perl itself.
733
734
735
736perl v5.12.0                      2010-03-10                Module::Install(3)
Impressum