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

WARNING

32       Please note that while Module::Install pioneered many great ideas in
33       its time, its primary benefits have been better achieved by the
34       authoring tool Dist::Zilla, and its spinoffs Dist::Milla and Minilla.
35       These tools allow the author to build and maintain distributions with
36       DWIM convenience, while the distribution is installed directly by
37       ExtUtils::MakeMaker or similar installation tools, avoiding the
38       complexity of bundling the installer.  Dist::Zilla additionally has a
39       more robust plugin system which makes it easier to keep up with changes
40       to the CPAN::Meta::Spec and add other new functionality. Use of
41       Module::Install for new distributions is therefore discouraged by the
42       maintainers.
43

DESCRIPTION

45       Module::Install is a package for writing installers for CPAN (or CPAN-
46       like) distributions that are clean, simple, minimalist, act in a
47       strictly correct manner with ExtUtils::MakeMaker, and will run on any
48       Perl installation version 5.005 or newer.
49
50       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
55   Writing Module::Install Installers
56       The quickest way to get started with Module::Install is to copy the
57       "SYNOPSIS" from above and save it as your own Makefile.PL. Then modify
58       the file to suit your own particular case, using the list of commands
59       documented in "COMMON COMMANDS" below.
60
61       If all you want to do is write an installer, go and do that now. You
62       don't really need the rest of this description unless you are
63       interested in the details.
64

How it Works

66       The motivation behind Module::Install is that distributions need to
67       interact with a large number of different versions of perl and module
68       installers infrastructure, primarily CPAN.pm, CPANPLUS.pm,
69       ExtUtils::MakeMaker and Module::Build.
70
71       These have accumulated greatly varying feature and bug profiles over
72       the years, and it is now very difficult to write an installer that will
73       work properly using only the installed versions of these modules,
74
75       For example, the CPAN.pm version shipped with Perl 5.005 is now 5+
76       years old and considered highly buggy, yet it still exists on quite a
77       number of legacy machines.
78
79       Rather than try to target one specific installer and/or make you add
80       twisty workaround expressions to every piece of install code you write,
81       Module::Install will copy part of itself into each module distribution
82       it creates.
83
84       This allows new improvements to be used in your installers regardless
85       of the age of the system a distribution is being installed on, at the
86       cost of a small increase in the size of your distribution.
87
88   History
89       This module was originally written by Brian Ingerson as a smart drop-in
90       replacement for ExtUtils::MakeMaker.
91
92       For more information, see Brian's Creating Module Distributions with
93       Module::Install in June 2003 issue of The Perl Journal
94       (<http://www.drdobbs.com/web-development/creating-module-distributions-with-modul/184416018>)
95
96       For a lot more information, and some personal opinions on the module
97       and its creation, see Module::Install::Philosophy.
98

COMMON COMMANDS

100       The following are the most common commands generally used in
101       installers.
102
103       It is far from an exhaustive list, as many of the plugins provide
104       commands to work in more details that you would normally need.
105
106   name
107         name 'My-Module';
108
109       The name command is compulsory command, generally the first.
110
111       It provides the name of your distribution, which for a module like
112       Your::Module would normally be "Your-Module".
113
114       This naming scheme is not hard and fast and you should note that
115       distributions are actually a separate naming scheme from modules.
116
117       For example the LWP modules come in a distribution called
118       "libwww-perl".
119
120   all_from
121         all_from 'lib/My/Module.pm';
122
123       For most simple Perl distributions that feature one dominant module or
124       class as the base, you can get the most Do What I Mean functionality by
125       using the all_from command, which will try to extract as much metadata
126       as possible from the Perl code and POD in that primary module.
127
128       Functionally, "all_from" is equivalent to "abstract_from" +
129       "author_from" + "version_from" + "license_from" + "perl_version_from".
130       See below for details.
131
132       If any of these values are set already before "all_from" is used, they
133       will kept and not be overwritten.
134
135   abstract
136         abstract 'This distribution does something';
137
138       All distributions have an abstract, a short description of the
139       distribution as a whole. It is usually around 30-70 characters long.
140
141       The "abstract" command is used to explicitly set the abstract for the
142       distribution, at least as far as the metadata file for the distribution
143       is concerned.
144
145   abstract_from
146         abstract_from 'lib/My/Module.pm';
147
148       The "abstract_from" command retrieves the abstract from a particular
149       file contained in the distribution package. Most often this is done
150       from the main module, where "Module::Install" will read the POD and use
151       whatever is in the "=head1 NAME" section (with module name stripped if
152       needed)
153
154       "abstract_from" is set as part of "all_from".
155
156   author
157         author 'Adam Kennedy <adamk@cpan.org>';
158
159       The distribution metadata contains information on the primary author or
160       the distribution, or the primary maintainer if the original author is
161       no longer involved. It should generally be specified in the form of an
162       email address.
163
164       It you don't want to give away a real email address, you should use the
165       "CPANID@cpan.org" address you receive automatically when you got your
166       PAUSE account.
167
168       The "author" command is used to explicitly set this value.
169
170   author_from
171         author_from 'lib/My/Module.pm';
172
173       The "author_from" command retrieves the author from a particular file
174       contained in the distribution package. Most often this is done using
175       the main module, where Module::Install will read the POD and use
176       whatever it can find in the "=head1 AUTHOR" section.
177
178   version
179         version '0.01';
180
181       The "version" command is used to specify the version of the
182       distribution, as distinct from the version of any single module within
183       the distribution.
184
185       Of course, in almost all cases you want it to match the version of the
186       primary module within the distribution, which you can do using
187       "version_from".
188
189   version_from
190         version_from 'lib/My/Module.pm';
191
192       The "version_from" command retrieves the distribution version from a
193       particular file contained in the distribution package. Most often this
194       is done from the main module.
195
196       "version_from" will look for the first time you set $VERSION and use
197       the same value, using a technique consistent with various other module
198       version scanning tools.
199
200   license
201         license 'perl';
202
203       The "license" command specifies the license for the distribution.
204
205       Most often this value will be 'perl', meaning "the same as for Perl
206       itself". Other allowed values include 'gpl', 'lgpl', 'bsd', 'MIT', and
207       'artistic'.
208
209       This value is always considered a summary, and it is normal for authors
210       to include a LICENSE file in the distribution, containing the full
211       license for the distribution.
212
213       You are also reminded that if the distribution is intended to be
214       uploaded to the CPAN, it must be an OSI-approved open source license.
215       Commercial software is not permitted on the CPAN.
216
217   license_from
218         license_from 'lib/My/Module.pm';
219
220       The "license_from" command retrieves the distribution license from a
221       particular file contained in the distribution package. Most often this
222       is done from the main module.
223
224       "license_from" will look inside the POD within the indicated file for a
225       licensing or copyright-related section and scan for a variety of
226       strings that identify the general class of license.
227
228       At this time it supports only the 6 values mentioned above in the
229       "license" command summary.
230
231   perl_version
232         perl_version '5.006';
233
234       The "perl_version" command is used to specify the minimum version of
235       the perl interpreter your distribution requires.
236
237       When specifying the version, you should try to use the normalized
238       version string. Perl version segments are 3 digits long, so a
239       dependency on Perl 5.6 will become '5.006' and Perl 5.10.2 will become
240       '5.010002'.
241
242   perl_version_from
243         perl_version_from 'lib/My/Module.pm'
244
245       The "perl_version_from" command retrieves the minimum perl interpreter
246       version from a particular file contained in the distribution package.
247       Most often this is done from the main module.
248
249       The minimum version is detected by scanning the file for "use 5.xxx"
250       pragma calls in the module file.
251
252   recommends
253         recommends 'Text::CSV_XS' => '0.50'
254
255       The "recommends" command indicates an optional run-time module that
256       provides extra functionality.  Recommended dependencies are not needed
257       to build or test your distribution, but are considered "nice to have".
258
259       As with "requires", the dependency is on a module and not a
260       distribution.  A version of zero indicates that any version of the
261       module is recommended.
262
263   requires
264         requires 'List::Util' => 0;
265         requires 'LWP'        => '5.69';
266
267       The "requires" command indicates a normal run-time dependency of your
268       distribution on another module. Most distributions will have one or
269       more of these commands, indicating which CPAN (or otherwise) modules
270       your distribution needs.
271
272       A "requires" dependency can be verbalised as "If you wish to install
273       and use this distribution, you must first install these modules first".
274
275       Note that the dependency is on a module and not a distribution. This is
276       to ensure that your dependency stays correct, even if the module is
277       moved or merged into a different distribution, as is occasionally the
278       case.
279
280       A dependency on version zero indicates any version of module is
281       sufficient. Versions should generally be quoted for clarity.
282
283   test_requires
284         test_requires 'Test::More' => '0.47';
285
286       The "test_requires" command indicates a test script dependency for the
287       distribution. The specification format is identical to that of the
288       "requires" command.
289
290       The "test_requires" command is distinct from the "requires" command in
291       that it indicates a module that is needed only during the testing of
292       the distribution (often a period of only a few seconds) but will not be
293       needed after the distribution is installed.
294
295       The "testrequires" command is used to allow the installer some
296       flexibility in how it provides the module, and to allow downstream
297       packagers (Debian, FreeBSD, ActivePerl etc) to retain only the
298       dependencies needed for run-time operation.
299
300       The "include" command is sometimes used by some authors along with
301       "test_requires" to bundle a small well-tested module into the
302       distribution package itself rather than inflict yet another module
303       installation on users installing from CPAN directly.
304
305   configure_requires
306         configure_requires 'File::Spec' => '0.80';
307
308       The "configure_requires" command indicates a configure-time dependency
309       for the distribution. The specification format is identical to that of
310       the "requires" command.
311
312       The "configure_requires" command is used to get around the conundrum of
313       how to use a CPAN module in your Makefile.PL, when you have to load
314       Makefile.PL (and thus the CPAN module) in order to know that you need
315       it.
316
317       Traditionally, this circular logic could not be broken and so
318       Makefile.PL scripts needed to rely on lowest-common-denominator
319       approaches, or to bundle those dependencies using something like the
320       "include" command.
321
322       The "configure_requires" command creates an entry in the special
323       configure_requires: key in the distribution's META.yml file.
324
325       Although most of META.yml is considered advisory only, a CPAN client
326       will treat the contents of configure_requires: as authoritative, and
327       install the listed modules before it executes the Makefile.PL (from
328       which it then determines the other dependencies).
329
330       Please note that support for configure_requires: in CPAN clients is not
331       100% complete at time of writing, and still cannot be relied upon.
332
333       Because Module::Install itself only supports 5.005, it will silently
334       add the equivalent of a "configure_requires( perl => '5.005' );"
335       command to your distribution.
336
337   requires_external_bin
338         requires_external_bin 'cvs';
339
340       As part of its role as the dominant "glue" language, a lot of Perl
341       modules run commands or programs on the host system.
342
343       The "requires_external_bin" command is used to verify that a particular
344       command is available on the host system.
345
346       Unlike a missing Perl module, a missing external binary is unresolvable
347       at make-time, and so the Makefile.PL run will abort with a "NA" (Not
348       Applicable) result.
349
350       In future, this command will also add additional information to the
351       metadata for the dist, so that auto-packagers for particular operating
352       system are more-easily able to auto-discover the appropriate non-Perl
353       packages needed as a dependency.
354
355   install_script
356         # The following are equivalent
357         install_script 'script/scriptname'
358
359       The "install_script" command provides support for the installation of
360       scripts that will become available at the console on both Unix and
361       Windows (in the later case by wrapping it up as a .bat file).
362
363       Note that is it normal practice to not put a .pl on the end of such
364       scripts, so that they feel more natural when being used.
365
366       In the example above, the script/scriptname program could be run after
367       the installation just by doing the following.
368
369         > scriptname
370         Running scriptname 0.01...
371
372         >
373
374       By convention, scripts should be placed in a /script directory within
375       your distribution. To support less typing, if a script is located in
376       the script directory, you need refer to it by name only.
377
378         # The following are equivalent
379         install_script 'foo';
380         install_script 'script/foo';
381
382   no_index
383         no_index directory => 'examples';
384         no_index package   => 'DB';
385
386       Quite often a distribution will provide example scripts or testing
387       modules (.pm files) as well as the actual library modules.
388
389       In almost all situations, you do not want these indexed in the CPAN
390       index, the master Perl packages list, or displayed on
391       <https://metacpan.org/> or <http://search.cpan.org/> websites, you just
392       want them along for the ride.
393
394       The "no_index" command is used to indicate directories or files where
395       there might be non-library .pm files or other files that the CPAN
396       indexer and websites such as <https://metacpan.org/> or
397       <http://search.cpan.org/> should explicitly ignore.
398
399       The most common situation is to ignore example or demo directories, but
400       a variety of different situations may require a "no_index" entry.
401
402       Another common use for "no_index" is to prevent the PAUSE indexer
403       complaining when your module makes changes inside a "package DB" block.
404       This is used to interact with the debugger in some specific ways.
405
406       See the META.yml documentation for more details on what "no_index"
407       values are allowed.
408
409       The inc, t and share (if "install_share" is used) directories are
410       automatically "no_index"'ed for you if found and do not require an
411       explicit command.
412
413       To summarize, if you can see it on <https://metacpan.org/> or
414       <http://search.cpan.org/> and you shouldn't be able to, you need a
415       "no_index" entry to remove it.
416
417   installdirs, install_as_*
418         installdirs 'site'; # the default
419
420         install_as_core;    # alias for installdirs 'perl'
421         install_as_cpan;    # alias for installdirs 'site'
422         install_as_site;    # alias for installdirs 'site'
423         install_as_vendor;  # alias for installdirs 'vendor'
424
425       The "installdirs" and "install_as" commands specify the location where
426       the module should be installed; this is the equivalent to
427       ExtUtils::MakeMaker's "INSTALLDIRS" option.  For almost all regular
428       modules, the default is recommended, and need not be changed.  Dual-
429       life (core and CPAN) modules, as well as vendor-specific modules, may
430       need to use the other options.
431
432       If unsure, do not use this option.
433
434   WriteAll
435       The "WriteAll" command is generally the last command in the file; it
436       writes out META.yml and Makefile so the user can run the "make", "make
437       test", "make install" install sequence.
438

EXTENSIONS

440       All extensions belong to the Module::Install::* namespace, and inherit
441       from Module::Install::Base.  There are three categories of extensions:
442
443   Standard Extensions
444       Methods defined by a standard extension may be called as plain
445       functions inside Makefile.PL; a corresponding singleton object will be
446       spawned automatically.  Other extensions may also invoke its methods
447       just like their own methods:
448
449           # delegates to $other_extension_obj->method_name(@args)
450           $self->method_name(@args);
451
452       At the first time an extension's method is invoked, a POD-stripped
453       version of it will be included under the inc/Module/Install/ directory,
454       and becomes fixed -- i.e., even if the user had installed a different
455       version of the same extension, the included one will still be used
456       instead.
457
458       If the author wish to upgrade extensions in inc/ with installed ones,
459       simply run "perl Makefile.PL" again; Module::Install determines whether
460       you are an author by the existence of the inc/.author/ directory.  End-
461       users can reinitialize everything and become the author by typing "make
462       realclean" and "perl Makefile.PL".
463
464   Private Extensions
465       Those extensions take the form of Module::Install::PRIVATE and
466       Module::Install::PRIVATE::*.
467
468       Authors are encouraged to put all existing Makefile.PL magics into such
469       extensions (e.g. Module::Install::PRIVATE for common bits;
470       Module::Install::PRIVATE::DISTNAME for functions specific to a
471       distribution).
472
473       Private extensions should not to be released on CPAN; simply put them
474       somewhere in your @INC, under the "Module/Install/" directory, and
475       start using their functions in Makefile.PL.  Like standard extensions,
476       they will never be installed on the end-user's machine, and therefore
477       never conflict with other people's private extensions.
478
479   Administrative Extensions
480       Extensions under the Module::Install::Admin::* namespace are never
481       included with the distribution.  Their methods are not directly
482       accessible from Makefile.PL or other extensions; they are invoked like
483       this:
484
485           # delegates to $other_admin_extension_obj->method_name(@args)
486           $self->admin->method_name(@args);
487
488       These methods only take effect during the initialization run, when inc/
489       is being populated; they are ignored for end-users.  Again, to re-
490       initialize everything, just run "perl Makefile.PL" as the author.
491
492       Scripts (usually one-liners in Makefile) that wish to dispatch AUTOLOAD
493       functions into administrative extensions (instead of standard
494       extensions) should use the Module::Install::Admin module directly.  See
495       Module::Install::Admin for details.
496

EXTENSIONS

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

FAQ

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

COOKBOOK / EXAMPLES

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

TO DO

670       Implement Module::Install::Compiled and
671       Module::Install::Admin::Compiled to integrate the Module::Compiled
672       "perl 6 to perl 5" functionality with Module::Install.  Because this
673       would add SIGNIFICANT dependencies (i.e. pugs!) this should almost
674       certainly be distributed as a separate distribution.
675
676       Go over POD docs in detail.
677
678       Test recursive Makefile directories
679
680       The test suite needs a great deal more test scripts.
681
682       Dependencies on shared libraries (libxml/libxml.dll etc) and binary
683       files so that debian/Win32/etc autopackaging applications can create
684       the appropriate package-level dependencies there.
685
686       EU::MM 6.06_03+ supports META.yml natively.  Maybe probe for that?
687

SEE ALSO

689       Module::Install::Philosophy
690
691       inc::Module::Install
692
693       Module::Install::AutoInstall
694
695       Module::Install::Base
696
697       Module::Install::Bundle
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
718       For other issues, contact the (topmost) author.
719

AUTHORS

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