1Module::Install::API(3)User Contributed Perl DocumentatioMnodule::Install::API(3)
2
6 Module::Install::API - Command Reference for Module::Install
7
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 This API document lists and describes all the public supported
14 commands, grouped by the nature or importance of them.
15 If you are a module author and want to use Module::Install in your
17 distributions, this is the document you should consult.
18 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 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
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 all_from (Module::Install::Metadata)
40 all_from 'lib/Foo/Bar.pm';
41 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 name, name_from, module_name (Module::Install::Metadata)
49 name 'Foo-Bar';
50 name_from 'lib/Foo/Bar.pm';
51 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 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 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 abstract, abstract_from (Module::Install::Metadata)
68 abstract 'a short description of the distribution';
69 abstract_from 'lib/Foo/Bar.pm';
70 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 The value set by abstract or abstract_from is passed to
77 ExtUtils::MakeMaker as an "ABSTRACT" attribute.
78 version, version_from (Module::Install::Metadata)
80 version '0.01';
81 version_from 'lib/Foo/Bar.pm';
82 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 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 perl_version, perl_version_from (Module::Install::Metadata)
93 perl_version '5.008';
94 perl_version_from 'lib/Foo/Bar.pm';
95 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 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 author, author_from (Module::Install::Metadata)
105 author 'John Doe <john.doe at cpan.org>';
106 author_from 'lib/Foo/Bar.pm';
107 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 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 The value set by author or author_from is concatenated and passed to
117 ExtUtils::MakeMaker as an "AUTHOR" attribute.
118 license, license_from (Module::Install::Metadata)
120 license 'perl';
121 license_from 'lib/Foo/Bar.pm';
122 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 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 The value set by license or license_from is passed to
133 ExtUtils::MakeMaker as an "LICENSE" attribute (if applicable).
134 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
140 Most of these are described in the main pod, too.
141 requires (Module::Install::Metadata)
143 requires 'Foo::Bar';
144 requires 'Foo::Baz' => '1.00';
145 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 The values set by requires are passed to ExtUtils::MakeMaker as a
157 "PREREQ_PM" attribute.
158 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 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 As of this writing, "test_requires" is just an alias for
174 "build_requires", but this may change in the future.
175 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 configure_requires (Module::Install::Metadata)
181 configure_requires 'ExtUtils::Foo::Bar';
182 configure_requires 'ExtUtils::Foo::Baz' => '1.00';
183 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 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 recommends (Module::Install::Metadata)
195 recommends 'ExtUtils::Foo::Bar';
196 recommends 'ExtUtils::Foo::Baz' => '1.00';
197 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 features, feature (Module::Install::Metadata)
205 feature( 'share directory support',
206 -default => 1,
207 'File::ShareDir' => '1.00',
208 );
209 features(
211 'JSON support', [
212 -default => 0,
213 'JSON::MaybeXS' => '1.003003',
214 ],
215 'YAML support', [
216 'YAML' => '0',
217 ],
218 );
219 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 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 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 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 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
245 These are the commands to write actual meta files.
246 WriteAll (Module::Install::WriteAll)
248 use inc::Module::Install;
249 all_from 'lib/Foo/Bar.pm';
251 WriteAll;
253 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 WriteMakefile (Module::Install::MakeMaker)
261 use inc::Module::Install;
262 requires 'Foo::Baz'; # a la Module::Install
264 WriteMakefile( # a la ExtUtils::MakeMaker
266 NAME => 'Foo::Bar',
267 VERSION_FROM => 'lib/Foo/Bar.pm',
268 );
269 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 write_mymeta_yaml, write_mymeta_json (Module::Install::Metadata)
275 write_mymeta_yaml;
276 write_mymeta_json;
277 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
286 makemaker_args (Module::Install::Makefile)
287 makemaker_args(
288 PREREQ_FATAL => 1,
289 dist => { PREOP => 'pod2text lib/Foo/Bar.pm > README' },
290 );
291 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 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 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
305 These are to set test files.
306 tests (Module::Install::Metadata)
308 tests 't/*.t t/*/*.t';
309 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 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 The value set by tests is passed to ExtUtils::MakeMaker as a "test"
322 attribute.
323 tests_recurisve (Module::Install::Makefile)
325 tests_recursive;
326 tests_recursive('t');
327 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
333 installdirs (Module::Install::Metadata)
334 installdirs 'site';
335 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 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 install_as_* commands are aliases of the corresponding commands shown
349 in the comments above.
350
352 These are to install files other than the ones under the "lib"
353 directory.
354 install_script (Module::Install::Scripts)
356 install_script('foo');
357 install_script('script/foo');
358 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 The value set by install_script is passed to ExtUtils::MakeMaker as an
364 "EXE_FILES" attribute.
365 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 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 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
385 auto_install (Module::Install::AutoInstall)
386 auto_install;
387 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 "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
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 build_subdirs (Module::Install::Makefile)
406 build_subdirs 'win32' if $^O eq 'MSWin32';
407 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
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 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 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 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 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 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 homepage, bugtracker, and "repository" commands take a URL for the
446 corresponding resource.
447
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
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 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 inc (Module::Install::Makefile), cc_inc_paths (Module::Install::Compiler)
468 inc '-I. -Iinclude';
469 cc_inc_paths qw/. include/;
470 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 cc_optimize_flags (Module::Install::Compiler)
476 cc_optimize_flags '-O2';
477 cc_optimize_flags takes a string to be passed to ExtUtils::MakeMaker as
479 an "OPTIMIZE" attribute.
480 ppport (Module::Install::Compiler)
482 ppport;
483 ppport command is used to bundle "ppport.h" to a distribution.
485 requires_external_cc (Module::Install::External)
487 requires_external_cc;
488 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 can_cc (Module::Install::Can)
493 exit 0 unless can_cc;
494 can_cc command tells if the use has a working compiler or not.
496
498 clean_files, realclean_files (Module::Install::Makefile)
499 clean_files '*.o Foo-*';
500 realclean_files '*.o Foo-*';
501 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
508 can_use (Module::Install::Can)
509 if (can_use('Some::Module', '0.05')) {
510 Some::Module::do_something();
511 }
512 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 can_run (Module::Install::Can)
518 if (can_run('svn')) {
519 # do something with the C<svn> binary
520 }
521 can_run command takes a executable path, and checks if the executable
523 is available or not.
524 requires_external_bin (Module::Install::External)
526 requires_external_bin 'svn';
527 requires_external_bin command takes a executable path, and exits the
529 "Makefile.PL" if none is available.
530
532 Kenichi Ishigaki <ishigaki@cpan.org>
533
535 Copyright 2010 Kenichi Ishigaki.
536 This program is free software; you can redistribute it and/or modify it
538 under the same terms as Perl itself.
539perl v5.36.0 2023-01-20 Module::Install::API(3)