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

NAME

6       Module::Install::API - Command Reference for Module::Install
7

DESCRIPTION

9       Module::Install has lots of commands scattered in the extensions.
10       Several common commands are described in the main Module::Install's
11       pod, but you usually need to know more to do what you want.
12
13       This API document lists and describes all the public supported
14       commands, grouped by the nature or importance of them.
15
16       If you are a module author and want to use Module::Install in your
17       distributions, this is the document you should consult.
18
19       If you are a user (or a contributor) of distributions that use
20       Module::Install, you may also want to check Module::Install::FAQ where
21       you'll find some common glitches you may encounter.
22
23       Note that commands not listed here should be deemed private utility
24       commands for the Module::Install developers, or unsupported commands
25       with various reasons (some are experimental and half-baked, some are
26       broken (by design or by implementation), some are simply deprecated,
27       and so on). You may find some of them are used rather widely, but their
28       use is discouraged. You have been warned.
29

COMMANDS TO PROVIDE BASIC META DATA

31       Most of these are also described in the main Module::Install's pod.
32       Basically, (almost) all you have to know is the all_from command that
33       tries to extract all the necessary basic meta data from a module file,
34       but you can also specify one by one what is not written in the module
35       and can't be extracted (you usually want to write these specific
36       commands before "all_from()" not to be warned by the lack of
37       information).
38
39   all_from (Module::Install::Metadata)
40         all_from 'lib/Foo/Bar.pm';
41
42       all_from command takes a module file path, and will try to extract meta
43       data from the module including a distribution name, a module version,
44       the minimum required perl version for the module, authors information,
45       a license, a short description of the module. See the following
46       commands for the extraction detail.
47
48   name, name_from, module_name (Module::Install::Metadata)
49         name 'Foo-Bar';
50         name_from 'lib/Foo/Bar.pm';
51
52       name command takes a distribution name. It usually differs slightly
53       from a module name (a module name is separated by double colons; a
54       distribution name is separated by hyphens). Just replacing all the
55       double colons of your main module with hyphens would be enough for you.
56
57       name_from takes a module file path, and looks for the topmost "package"
58       declaration to extract a module name, and then converts it to a
59       distribution name.
60
61       You may optionally set module_name to specify a main module name (if
62       you choose other naming scheme for your distribution). This value is
63       directly passed to ExtUtils::MakeMaker in the backend as a "NAME"
64       attribute (Module::Install usually creates this from the distribution
65       name set by name or name_from).
66
67   abstract, abstract_from (Module::Install::Metadata)
68         abstract 'a short description of the distribution';
69         abstract_from 'lib/Foo/Bar.pm';
70
71       abstract command takes a string to describe what that
72       module/distribution is for. abstract_from takes a module file path and
73       looks for a string that follows the module's name and a hyphen to
74       separate in the "NAME" section of the pod.
75
76       The value set by abstract or abstract_from is passed to
77       ExtUtils::MakeMaker as an "ABSTRACT" attribute.
78
79   version, version_from (Module::Install::Metadata)
80         version '0.01';
81         version_from 'lib/Foo/Bar.pm';
82
83       version command takes a version string for the distribution.
84       version_from takes a module file path, and looks for the $VERSION of
85       the module.
86
87       The value set by version or version_from is passed to
88       ExtUtils::MakeMaker as a "VERSION" attribute. version_from (and
89       all_from) also sets a "VERSION_FROM" attribute to check version
90       integrity of the distribution.
91
92   perl_version, perl_version_from (Module::Install::Metadata)
93         perl_version '5.008';
94         perl_version_from 'lib/Foo/Bar.pm';
95
96       perl_version command takes a minimum required perl version for the
97       distribution. perl_version_from takes a module file path, and looks for
98       a "use <perl_version>" (or "require <perl_version>") statement (note
99       that now Module::Install only supports perl 5.005 and newer).
100
101       The value set by perl_version or perl_version_from is passed to
102       ExtUtils::MakeMaker as a "MIN_PERL_VERSION" attribute (if applicable).
103
104   author, author_from (Module::Install::Metadata)
105         author 'John Doe <john.doe at cpan.org>';
106         author_from 'lib/Foo/Bar.pm';
107
108       author command takes a string to describe author(s). You can set
109       multiple authors with one author command, or with multiple authors (you
110       can also use authors alias if you prefer).
111
112       author_from takes a module file path, and looks for an "AUTHOR" (or
113       "AUTHORS") section in the pod (and also license/copyright sections if
114       it can't find any author(s) section) to extract an author.
115
116       The value set by author or author_from is concatenated and passed to
117       ExtUtils::MakeMaker as an "AUTHOR" attribute.
118
119   license, license_from (Module::Install::Metadata)
120         license 'perl';
121         license_from 'lib/Foo/Bar.pm';
122
123       license command takes an abbreviated license name including "perl",
124       "artistic", "apache", "(l)gpl", "bsd", "mit", "mozilla", "open_source",
125       and so on. If you don't (want to) specify a particular license, it will
126       be "unknown".
127
128       license_from takes a module file path, and looks for a "LICENSE" (or
129       "LICENCE") section in the pod (and also "COPYRIGHT" section if it can't
130       find any) to extract a license.
131
132       The value set by license or license_from is passed to
133       ExtUtils::MakeMaker as an "LICENSE" attribute (if applicable).
134
135       You are also reminded that if the distribution is intended to be
136       uploaded to the CPAN, it must be an OSI-approved open source license.
137       Commercial software is not permitted on the CPAN.
138

COMMANDS TO PROVIDE DEPENDENCIES

140       Most of these are described in the main pod, too.
141
142   requires (Module::Install::Metadata)
143         requires 'Foo::Bar';
144         requires 'Foo::Baz' => '1.00';
145
146       requires command takes a module name on which your distribution
147       depends, and its minimum required version if any. You may add arbitrary
148       numbers of "requires". You even can add multiple numbers of
149       dependencies on the same module with different required versions (which
150       will be sorted out later, though). Note that this dependency is on the
151       basis of a module, not of a distribution. This usually doesn't matter,
152       and you just need to call for a module you really need (then you'll get
153       the whole distribution it belongs to), but sometimes you may need to
154       call for all the modules that the required module implicitly requires.
155
156       The values set by requires are passed to ExtUtils::MakeMaker as a
157       "PREREQ_PM" attribute.
158
159   build_requires, test_requires (Module::Install::Metadata)
160         build_requires 'ExtUtils::Foo::Bar';
161         build_requires 'ExtUtils::Foo::Baz' => '1.00';
162         test_requires  'Test::Foo::Bar';
163         test_requires  'Test::Foo::Baz' => '1.00';
164
165       build_requires command also takes a module name and a minimum required
166       version if any. The difference from the "requires" command is that
167       build_requires is to call for modules you'll require while building the
168       distribution, or in the tests, and that in theory are not required at
169       run-time. This distinction is more for other system package managers
170       than for the CPAN, from where you usually want to install everything
171       for future reuse (unless you are too lazy to test distributions).
172
173       As of this writing, "test_requires" is just an alias for
174       "build_requires", but this may change in the future.
175
176       The values set by build_requires and test_requires are passed to
177       ExtUtils::MakeMaker as a "BUILD_REQUIRES" attribute, which may fall
178       back to "PREREQ_PM" if your ExtUtils::MakeMaker is not new enough.
179
180   configure_requires (Module::Install::Metadata)
181         configure_requires 'ExtUtils::Foo::Bar';
182         configure_requires 'ExtUtils::Foo::Baz' => '1.00';
183
184       configure_requires command also takes a module name and a minimum
185       required version if any. The difference from the "requires" command is
186       that configure_requires is to call for modules you'll require to run
187       "perl Makefile.PL". This attribute only makes sense for the latest CPAN
188       toolchains that parse "META.yml" before running "perl Makefile.PL".
189
190       The values set by configure_requires are passed to ExtUtils::MakeMaker
191       as a "CONFIGURE_REQUIRES" attribute, which may fall back to "PREREQ_PM"
192       if your ExtUtils::MakeMaker is not new enough.
193
194   recommends (Module::Install::Metadata)
195         recommends 'ExtUtils::Foo::Bar';
196         recommends 'ExtUtils::Foo::Baz' => '1.00';
197
198       recommends command also takes a module name and a minimum required
199       version if any. As of this writing, "recommends" is purely advisory,
200       only written in the "META.yml". Recommended modules will not usually be
201       installed by the current CPAN toolchains (other system package managers
202       may possibly prompt you to install them).
203
204   features, feature (Module::Install::Metadata)
205         feature( 'share directory support',
206           -default => 1,
207           'File::ShareDir' => '1.00',
208         );
209
210         features(
211           'JSON support', [
212             -default => 0,
213             'JSON::MaybeXS' => '1.003003',
214           ],
215           'YAML support', [
216             'YAML' => '0',
217           ],
218         );
219
220       feature command takes a string to describe what the feature is for, and
221       an array of (optional) modules and their recommended versions if any.
222       features command takes an array of a description and an array of
223       modules.
224
225       As of this writing, both "feature" and "features" work only when
226       auto_install (see below) is set. These are used to allow distribution
227       users to choose what they install along with the distribution. This may
228       be useful if the distribution has lots of optional features that may
229       not work on all the platforms, or that require too many modules for
230       average users.
231
232       However, prompting users also hinders automated installation or smoke
233       testing, and is considered a bad practice (giving sane default values
234       is much preferred).
235
236       Though "feature"d modules are optional and can be chosen during the
237       installation, the chosen modules are treated the same as the ones set
238       by "requires" command. (They are not listed in the "recommends" section
239       in the "META.yml"). This may change in the future.
240
241       You can add "-default => [01]" in an array of required modules in the
242       feature(s), to set a default value for the prompt.
243

COMMANDS TO WRITE METADATA

245       These are the commands to write actual meta files.
246
247   WriteAll (Module::Install::WriteAll)
248         use inc::Module::Install;
249
250         all_from 'lib/Foo/Bar.pm';
251
252         WriteAll;
253
254       WriteAll command is usually the last command in the "Makefile.PL". It
255       can take several attributes, but you usually don't need to care unless
256       you want to write a Makefile for an Inline-based module. This writes
257       "Makefile", "META.yml", and "MYMETA.yml" (or "MYMETA.json") if you set
258       an experimental environmental variable "X_MYMETA".
259
260   WriteMakefile (Module::Install::MakeMaker)
261         use inc::Module::Install;
262
263         requires 'Foo::Baz';  # a la Module::Install
264
265         WriteMakefile(        # a la ExtUtils::MakeMaker
266           NAME => 'Foo::Bar',
267           VERSION_FROM => 'lib/Foo/Bar.pm',
268         );
269
270       If you're familiar with ExtUtils::MakeMaker and generally want to stick
271       to its way, you can. Use as much Module::Install's magic as you want,
272       and then fall back to the good and old way. It just works.
273
274   write_mymeta_yaml, write_mymeta_json (Module::Install::Metadata)
275         write_mymeta_yaml;
276         write_mymeta_json;
277
278       write_mymeta_yaml command and write_mymeta_json command are to write
279       "MYMETA.yml" and "MYMETA.json" respectively, which are new enhancement
280       for the CPAN toolchains that eventually will allow toolchain modules to
281       know what modules are required without parsing Makefile etc. These are
282       mainly for internal use (in the "WriteAll" command) but you can
283       explicitly write these commands in your Makefile.PL.
284

COMMANDS TO TWEAK MAKEFILE

286   makemaker_args (Module::Install::Makefile)
287         makemaker_args(
288           PREREQ_FATAL => 1,
289           dist => { PREOP => 'pod2text lib/Foo/Bar.pm > README' },
290         );
291
292       makemaker_args command is used in "WriteMakefile" command, and takes
293       any attributes ExtUtils::MakeMaker understands. See ExtUtils::MakeMaker
294       for the available attributes.
295
296   preamble, postamble (Module::Install::Makefile)
297         preamble "# my preamble\n";
298         postamble qq{my_done ::\n\t\$(PERL) -e "print qq/done\\n/"\n};
299
300       preamble and postamble commands take a string to be embedded in the
301       "Makefile". You can add custom targets with this. See appropriate
302       manuals to learn how to write Makefile.
303

COMMANDS FOR TESTS

305       These are to set test files.
306
307   tests (Module::Install::Metadata)
308         tests 't/*.t t/*/*.t';
309
310       tests command takes a string to specify test files. You can use
311       wildcard characters, and if you want to run tests under several
312       directories, concatenates the specs with white spaces.
313
314       If you haven't set "tests" by any means (with explicit "tests" command,
315       or extensions like Module::Install::AuthorTests or
316       Module::Install::ExtraTests), and if you have an "xt" directory,
317       Module::Install silently adds those tests under the "xt" directory when
318       you are in the author mode, or you are doing release testing (with
319       "RELEASE_TESTING" environmental variable).
320
321       The value set by tests is passed to ExtUtils::MakeMaker as a "test"
322       attribute.
323
324   tests_recurisve (Module::Install::Makefile)
325         tests_recursive;
326         tests_recursive('t');
327
328       tests_recursive command may take a directory, and looks for test files
329       under it recursively. As of this writing, you can't use this command
330       with other test related commands.
331

COMMANDS TO TWEAK DIRECTORIES TO INSTALL

333   installdirs (Module::Install::Metadata)
334         installdirs 'site';
335
336       installdirs command takes a directory type, and changes a directory to
337       install modules and so on, though you usually don't need to use this.
338       The value set by installdirs is passed to ExtUtils::MakeMaker as an
339       "INSTALLDIRS" attribute.
340
341   install_as_core, install_as_cpan, install_as_site, install_as_vendor
342       (Module::Install::Metadata)
343         install_as_core;   # = installdirs 'perl';
344         install_as_cpan;   # = installdirs 'site';
345         install_as_site;   # = installdirs 'site';
346         install_as_vendor; # = installdirs 'vendor';
347
348       install_as_* commands are aliases of the corresponding commands shown
349       in the comments above.
350

COMMANDS TO INSTALL SUBORDINATE FILES

352       These are to install files other than the ones under the "lib"
353       directory.
354
355   install_script (Module::Install::Scripts)
356         install_script('foo');
357         install_script('script/foo');
358
359       install_script command takes a script file name, and installs it into a
360       "script" directory for your Perl installation. If your script is in a
361       "script" directory, you can omit the "script/" part.
362
363       The value set by install_script is passed to ExtUtils::MakeMaker as an
364       "EXE_FILES" attribute.
365
366   install_share (Module::Install::Share)
367         install_share;
368         install_share('templates');
369         install_share('dist', 'templates');
370         install_share('module', 'My::WebApp', 'share');
371
372       install_share command may take a directory type (either "dist" or
373       "module"), a module name if necessary, and a directory ("share" by
374       default), and installs files under the directory into a "share"
375       directory for the type, which is usually in a directory your perl is
376       installed in (but this may not be true if you're using local::lib and
377       the likes).
378
379       You can access these shared files via File::ShareDir's "dist_file" or
380       "module_file" according to the type. Note also that a shared directory
381       is usually read-only. You can't use this as a private temporary
382       directory.
383

COMMANDS FOR AUTO INSTALLATION

385   auto_install (Module::Install::AutoInstall)
386         auto_install;
387
388       The auto_install command is used to allow users to install dependencies
389       of a local project when you run "make" after "<perl Makefile.PL">. In
390       the past this was the only sane way to pull extra dependencies without
391       installing the actual module, although now there are some alternatives
392       (which however do not completely replace "auto_install"). For example
393       you can use "cpan ." (with newer CPAN) or "cpanm --installdeps ." (with
394       App::cpanminus).
395
396       "auto_install" also enables feature(s) commands to choose what you
397       install (keep in mind that using "feature()" in CPAN distributions is
398       generally considered a bad practice).
399

COMMANDS TO SUBDIRECTORY INSTALLATION

401       Module::Install 0.96 and above installs distributions in the
402       subdirectories by default as ExtUtils::MakeMaker does. You also can
403       specify what to install one by one.
404
405   build_subdirs (Module::Install::Makefile)
406         build_subdirs 'win32' if $^O eq 'MSWin32';
407
408       build_subdirs command takes subdirectories where projects you want to
409       install are in. The values set by build_subdirs are passed to
410       ExtUtils::MakeMaker as a "DIR" attribute.
411

COMMANDS TO PROVIDE OTHER OPTIONAL META DATA

413       These are to provide optional meta data mainly used by the PAUSE
414       indexer and the CPAN search site. See also the META-spec page
415       (<http://module-build.sourceforge.net/META-spec.html>) for details.
416
417   no_index (Module::Install::Metadata)
418         no_index file      => 'lib/My/Test/Module.pm';
419         no_index directory => 'templates';
420         no_index package   => 'Test::Foo::Bar';
421         no_index namespace => 'Test::Foo::Bar';
422
423       no_index command takes a hash to describe what should be excluded from
424       the PAUSE index etc. Module::Install provides several "no_index"
425       directories by default, including "inc", "share", "(x)t", "test",
426       example(s), "demo".
427
428   resources (Module::Install::Metadata)
429         resources
430           license     => "http://dev.perl.org/licenses",
431           homepage    => "http://yourproject.host.org",
432           bugtracker  => "http://rt.cpan.org/NoAuth/Bugs.html?Dist=Foo-Bar",
433           repository  => "http://yourhost.com/myscm",
434           MailingList => "http://yourhost.com/listinfo/foo-bar";
435
436       resources command takes a hash that contains various URLs for the
437       related resources. Keys in lower-case are reserved. These resources are
438       written in the "META.yml".
439
440   homepage, bugtracker, repository (Module::Install::Metadata)
441         homepage   'http://example.com';
442         bugtracker 'http://rt.cpan.org';
443         repository 'http://github.com/foo/bar';
444
445       homepage, bugtracker, and "repository" commands take a URL for the
446       corresponding resource.
447

COMMANDS TO BUNDLE DISTRIBUTIONS

449       There are several commands to bundle modules/distributions in your
450       distribution, but they are still broken in general. Don't use them for
451       now.
452

COMMANDS FOR XS SUPPORT

454   libs (Module::Install::Makefile), cc_lib_paths, cc_lib_links
455       (Module::Install::Compiler)
456         libs '-lz';
457         libs [qw/-lz -Llibs/];
458         cc_lib_paths 'libs';
459         cc_lib_links qw/z iconv/;
460
461       libs command takes a string, or an array reference of strings to be
462       passed to ExtUtils::MakeMaker as a "LIBS" attribute.  cc_lib_paths and
463       cc_lib_links are its alternatives, both of which take an array of
464       strings. "cc_lib_paths" is for upper-cased "-L" (directories), and
465       "cc_lib_links" is for lower-cased "-l" (libraries).
466
467   inc (Module::Install::Makefile), cc_inc_paths (Module::Install::Compiler)
468         inc '-I. -Iinclude';
469         cc_inc_paths qw/. include/;
470
471       inc command takes a string to be passed to ExtUtils::MakeMaker as an
472       "INC" attribute. cc_inc_paths is its alternative, and takes an array of
473       directories.
474
475   cc_optimize_flags (Module::Install::Compiler)
476         cc_optimize_flags '-O2';
477
478       cc_optimize_flags takes a string to be passed to ExtUtils::MakeMaker as
479       an "OPTIMIZE" attribute.
480
481   ppport (Module::Install::Compiler)
482         ppport;
483
484       ppport command is used to bundle "ppport.h" to a distribution.
485
486   requires_external_cc (Module::Install::External)
487         requires_external_cc;
488
489       requires_external_cc command checks if the user has a working compiler
490       listed in the Config, and exits the "Makefile.PL" if none is found.
491
492   can_cc (Module::Install::Can)
493         exit 0 unless can_cc;
494
495       can_cc command tells if the use has a working compiler or not.
496

COMMANDS FOR CLEANUP

498   clean_files, realclean_files (Module::Install::Makefile)
499         clean_files '*.o Foo-*';
500         realclean_files '*.o Foo-*';
501
502       clean_files command takes a string or an array of strings, concatenates
503       them with spaces, and passes the result to ExtUtils::MakeMaker as a
504       "clean" attribute. realclean_files does the same for a "realclean"
505       attribute.
506

UTILITY COMMANDS

508   can_use (Module::Install::Can)
509         if (can_use('Some::Module', '0.05')) {
510           Some::Module::do_something();
511         }
512
513       can_use command takes a module name, and optionally a version, and
514       checks if the module (with the version if appropriate) is installed or
515       not.
516
517   can_run (Module::Install::Can)
518         if (can_run('svn')) {
519           # do something with the C<svn> binary
520         }
521
522       can_run command takes a executable path, and checks if the executable
523       is available or not.
524
525   requires_external_bin (Module::Install::External)
526         requires_external_bin 'svn';
527
528       requires_external_bin command takes a executable path, and exits the
529       "Makefile.PL" if none is available.
530

AUTHOR

532       Kenichi Ishigaki <ishigaki@cpan.org>
533
535       Copyright 2010 Kenichi Ishigaki.
536
537       This program is free software; you can redistribute it and/or modify it
538       under the same terms as Perl itself.
539
540
541
542perl v5.32.0                      2020-07-28           Module::Install::API(3)
Impressum