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

FAQ

571   What are the benefits of using Module::Install?
572       Here is a brief overview of the reasons:
573
574       ·   Extremely easy for beginners to learn
575
576       ·   Does everything ExtUtils::MakeMaker does.
577
578       ·   Does it with a dramatically simpler syntax.
579
580       ·   Automatically scans for metadata for you.
581
582       ·   Requires no installation for end-users.
583
584       ·   Guaranteed forward-compatibility.
585
586       ·   Automatically updates your MANIFEST.
587
588       ·   Distributing scripts is easy.
589
590       ·   Include prerequisite modules (less dependencies to install)
591
592       ·   Auto-installation of prerequisites.
593
594       ·   Support for Inline-based modules.
595
596       ·   Support for File::ShareDir shared data files
597
598       ·   Support for precompiled PAR binaries.
599
600       ·   Deals with Win32 install issues for you.
601
602       By greatly shrinking and simplifying the syntax, Module::Install keeps
603       the amount of work required to maintain your Makefile.PL files to an
604       absolute minimum.
605
606       And if you maintain more than one module than needs to do unusual
607       installation tricks, you can create a specific module to abstract away
608       this complexity.
609
610   Module::Install isn't at 1.00 yet, is it safe to use yet?
611       As long as you are going to periodically do incremental releases to get
612       any bug fixes and new functionality, yes.
613
614       If you don't plan to do incremental releases, it might be a good idea
615       to continue to wait for a while.
616

COOKBOOK / EXAMPLES

618       The following are some real-life examples of Makefile.PL files using
619       Module::Install.
620
621   Method::Alias
622       Method::Alias is a trivially-small utility module, with almost the
623       smallest possible Makefile.PL.
624
625         use inc::Module::Install;
626
627         name          'Method-Alias';
628         all_from      'lib/Method/Alias.pm';
629         test_requires 'Test::More' => '0.42';
630
631   File::HomeDir
632       File::HomeDir locates your home directory on any platform. It needs an
633       installer that can handle different dependencies on different
634       platforms.
635
636         use inc::Module::Install;
637
638         name          'File-HomeDir';
639         all_from      'lib/File/HomeDir.pm';
640         requires      'File::Spec' => '0.80';
641         test_requires 'Test::More' => '0.47';
642
643         if ( $MacPerl::Version ) {
644             # Needed on legacy Mac OS 9
645             requires 'Mac::Files' => 0;
646         }
647
648         if ( $^O eq 'MXWin32' ) {
649             # Needed on Windows platforms
650             requires 'Win32::TieRegistry' => 0;
651         }
652
653         WriteAll;
654

TO DO

656       Implement Module::Install::Compiled and
657       Module::Install::Admin::Compiled to integrate the Module::Compiled
658       "perl 6 to perl 5" functionality with Module::Install.  Because this
659       would add SIGNIFICANT dependencies (i.e. pugs!) this should almost
660       certainly be distributed as a separate distribution.
661
662       Go over POD docs in detail.
663
664       Test recursive Makefile directories
665
666       The test suite needs a great deal more test scripts.
667
668       Dependencies on shared libraries (libxml/libxml.dll etc) and binary
669       files so that debian/Win32/etc autopackaging applications can create
670       the appropriate package-level dependencies there.
671
672       EU::MM 6.06_03+ supports META.yml natively.  Maybe probe for that?
673

SEE ALSO

675       Module::Install::Philosophy
676
677       inc::Module::Install
678
679       Module::Install::AutoInstall
680
681       Module::Install::Base
682
683       Module::Install::Bundle
684
685       Module::Install::MakeMaker
686
687       Module::Install::Share
688
689       Module::Install::Admin
690
691       Module::Install::Admin::Include
692
693       Module::Install::Admin::Manifest
694
695       CPAN::MakeMaker, Inline::MakeMaker
696
697       ExtUtils::MakeMaker
698

SUPPORT

700       Bugs should be reported via the CPAN bug tracker at
701
702       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install>
703
704       For other issues, contact the (topmost) author.
705

AUTHORS

707       Adam Kennedy <adamk@cpan.org>
708
709       Audrey Tang <autrijus@autrijus.org>
710
711       Brian Ingerson <ingy@cpan.org>
712
714       Copyright 2002 - 2012 Brian Ingerson, Audrey Tang and Adam Kennedy.
715
716       This program is free software; you can redistribute it and/or modify it
717       under the same terms as Perl itself.
718
719
720
721perl v5.16.3                      2012-03-01                Module::Install(3)
Impressum