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 commmand 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' => '2.00',
214 'JSON::XS' => '2.00',
215 ],
216 'YAML support', [
217 'YAML' => '0',
218 ],
219 );
220 feature command takes a string to describe what the feature is for, and
222 an array of (optional) modules and their recommended versions if any.
223 features command takes an array of a description and an array of
224 modules.
225 As of this writing, both "feature" and "features" work only when
227 auto_install (see below) is set. These are used to allow distribution
228 users to choose what they install along with the distribution. This may
229 be useful if the distribution has lots of optional features that may
230 not work on all the platforms, or that require too many modules for
231 average users.
232 However, prompting users also hinders automated installation or smoke
234 testing, and is considered a bad practice (giving sane default values
235 is much preferred).
236 Though "feature"d modules are optional and can be chosen during the
238 installation, the chosen modules are treated the same as the ones set
239 by "requires" command. (They are not listed in the "recommends" section
240 in the "META.yml"). This may change in the future.
241 You can add "-default => [01]" in an array of required modules in the
243 feature(s), to set a default value for the prompt.
244
246 These are the commands to write actual meta files.
247 WriteAll (Module::Install::WriteAll)
249 use inc::Module::Install;
250 all_from 'lib/Foo/Bar.pm';
252 WriteAll;
254 WriteAll command is usually the last command in the "Makefile.PL". It
256 can take several attributes, but you usually don't need to care unless
257 you want to write a Makefile for an Inline-based module. This writes
258 "Makefile", "META.yml", and "MYMETA.yml" (or "MYMETA.json") if you set
259 an experimental environmental variable "X_MYMETA".
260 WriteMakefile (Module::Install::MakeMaker)
262 use inc::Module::Install;
263 requires 'Foo::Baz'; # a la Module::Install
265 WriteMakefile( # a la ExtUtils::MakeMaker
267 NAME => 'Foo::Bar',
268 VERSION_FROM => 'lib/Foo/Bar.pm',
269 );
270 If you're familiar with ExtUtils::MakeMaker and generally want to stick
272 to its way, you can. Use as much Module::Install's magic as you want,
273 and then fall back to the good and old way. It just works.
274 write_mymeta_yaml, write_mymeta_json (Module::Install::Metadata)
276 write_mymeta_yaml;
277 write_mymeta_json;
278 write_mymeta_yaml command and write_mymeta_json command are to write
280 "MYMETA.yml" and "MYMETA.json" respectively, which are new enhancement
281 for the CPAN toolchains that eventually will allow toolchain modules to
282 know what modules are required without parsing Makefile etc. These are
283 mainly for internal use (in the "WriteAll" command) but you can
284 explicitly write these commands in your Makefile.PL.
285
287 makemaker_args (Module::Install::Makefile)
288 makemaker_args(
289 PREREQ_FATAL => 1,
290 dist => { PREOP => 'pod2text lib/Foo/Bar.pm > README' },
291 );
292 makemaker_args command is used in "WriteMakefile" command, and takes
294 any attributes ExtUtils::MakeMaker understands. See ExtUtils::MakeMaker
295 for the available attributes.
296 preamble, postamble (Module::Install::Makefile)
298 preamble "# my preamble\n";
299 postamble qq{my_done ::\n\t\$(PERL) -e "print qq/done\\n/"\n};
300 preamble and postamble commands take a string to be embedded in the
302 "Makefile". You can add custom targets with this. See appropriate
303 manuals to learn how to write Makefile.
304
306 These are to set test files.
307 tests (Module::Install::Metadata)
309 tests 't/*.t t/*/*.t';
310 tests command takes a string to specify test files. You can use
312 wildcard characters, and if you want to run tests under several
313 directories, concatenates the specs with white spaces.
314 If you haven't set "tests" by any means (with explicit "tests" command,
316 or extensions like Module::Install::AuthorTests or
317 Module::Install::ExtraTests), and if you have an "xt" directory,
318 Module::Install silently adds those tests under the "xt" directory when
319 you are in the author mode, or you are doing release testing (with
320 "RELEASE_TESTING" environmental variable).
321 The value set by tests is passed to ExtUtils::MakeMaker as a "test"
323 attribute.
324 tests_recurisve (Module::Install::Makefile)
326 tests_recursive;
327 tests_recursive('t');
328 tests_recursive command may take a directory, and looks for test files
330 under it recursively. As of this writing, you can't use this command
331 with other test related commands.
332
334 installdirs (Module::Install::Metadata)
335 installdirs 'site';
336 installdirs command takes a directory type, and changes a directory to
338 install modules and so on, though you usually don't need to use this.
339 The value set by installdirs is passed to ExtUtils::MakeMaker as an
340 "INSTALLDIRS" attribute.
341 install_as_core, install_as_cpan, install_as_site, install_as_vendor
343 (Module::Install::Metadata)
344 install_as_core; # = installdirs 'perl';
345 install_as_cpan; # = installdirs 'site';
346 install_as_site; # = installdirs 'site';
347 install_as_vendor; # = installdirs 'vendor';
348 install_as_* commands are aliases of the corresponding commands shown
350 in the comments above.
351
353 These are to install files other than the ones under the "lib"
354 directory.
355 install_script (Module::Install::Scripts)
357 install_script('foo');
358 install_script('script/foo');
359 install_script command takes a script file name, and installs it into a
361 "script" directory for your Perl installation. If your script is in a
362 "script" directory, you can omit the "script/" part.
363 The value set by install_script is passed to ExtUtils::MakeMaker as an
365 "EXE_FILES" attribute.
366 install_share (Module::Install::Share)
368 install_share;
369 install_share('templates');
370 install_share('dist', 'templates');
371 install_share('module', 'My::WebApp', 'share');
372 install_share command may take a directory type (either "dist" or
374 "module"), a module name if necessary, and a directory ("share" by
375 default), and installs files under the directory into a "share"
376 directory for the type, which is usually in a directory your perl is
377 installed in (but this may not be true if you're using local::lib and
378 the likes).
379 You can access these shared files via File::ShareDir's "dist_file" or
381 "module_file" according to the type. Note also that a shared directory
382 is usually read-only. You can't use this as a private temporary
383 directory.
384
386 auto_install (Module::Install::AutoInstall)
387 auto_install;
388 The auto_install command is used to allow users to install dependencies
390 of a local project when you run "make" after "<perl Makefile.PL">. In
391 the past this was the only sane way to pull extra dependencies without
392 installing the actual module, although now there are some alternatives
393 (which however do not completely replace "auto_install"). For example
394 you can use "cpan ." (with newer CPAN) or "cpanm --installdeps ." (with
395 App::cpanminus).
396 "auto_install" also enables feature(s) commands to choose what you
398 install (keep in mind that using "feature()" in CPAN distributions is
399 generally considered a bad practice).
400
402 Module::Install 0.96 and above installs distributions in the
403 subdirectories by default as ExtUtils::MakeMaker does. You also can
404 specify what to install one by one.
405 build_subdirs (Module::Install::Makefile)
407 build_subdirs 'win32' if $^O eq 'MSWin32';
408 build_subdirs command takes subdirectories where projects you want to
410 install are in. The values set by build_subdirs are passed to
411 ExtUtils::MakeMaker as a "DIR" attribute.
412
414 These are to provide optional meta data mainly used by the PAUSE
415 indexer and the CPAN search site. See also the META-spec page
416 (<http://module-build.sourceforge.net/META-spec.html>) for details.
417 no_index (Module::Install::Metadata)
419 no_index file => 'lib/My/Test/Module.pm';
420 no_index directory => 'templates';
421 no_index package => 'Test::Foo::Bar';
422 no_index namespace => 'Test::Foo::Bar';
423 no_index command takes a hash to describe what should be excluded from
425 the PAUSE index etc. Module::Install provides several "no_index"
426 directories by default, including "inc", "share", "(x)t", "test",
427 example(s), "demo".
428 resources (Module::Install::Metadata)
430 resources
431 license => "http://dev.perl.org/licenses",
432 homepage => "http://yourproject.host.org",
433 bugtracker => "http://rt.cpan.org/NoAuth/Bugs.html?Dist=Foo-Bar",
434 repository => "http://yourhost.com/myscm",
435 MailingList => "http://yourhost.com/listinfo/foo-bar";
436 resources command takes a hash that contains various URLs for the
438 related resources. Keys in lower-case are reserved. These resources are
439 written in the "META.yml".
440 homepage, bugtracker, repository (Module::Install::Metadata)
442 homepage 'http://example.com';
443 bugtracker 'http://rt.cpan.org';
444 repository 'http://github.com/foo/bar';
445 homepage, bugtracker, and "repository" commands take a URL for the
447 corresponding resource.
448
450 There are several commands to bundle modules/distributions in your
451 distribution, but they are still broken in general. Don't use them for
452 now.
453
455 libs (Module::Install::Makefile), cc_lib_paths, cc_lib_links
456 (Module::Install::Compiler)
457 libs '-lz';
458 libs [qw/-lz -Llibs/];
459 cc_lib_paths 'libs';
460 cc_lib_links qw/z iconv/;
461 libs command takes a string, or an array reference of strings to be
463 passed to ExtUtils::MakeMaker as a "LIBS" attribute. cc_lib_paths and
464 cc_lib_links are its alternatives, both of which take an array of
465 strings. "cc_lib_paths" is for upper-cased "-L" (directories), and
466 "cc_lib_links" is for lower-cased "-l" (libraries).
467 inc (Module::Install::Makefile), cc_inc_paths (Module::Install::Compiler)
469 inc '-I. -Iinclude';
470 cc_inc_paths qw/. include/;
471 inc command takes a string to be passed to ExtUtils::MakeMaker as an
473 "INC" attribute. cc_inc_paths is its alternative, and takes an array of
474 directories.
475 cc_optimize_flags (Module::Install::Compiler)
477 cc_optimize_flags '-O2';
478 cc_optimize_flags takes a string to be passed to ExtUtils::MakeMaker as
480 an "OPTIMIZE" attribute.
481 ppport (Module::Install::Compiler)
483 ppport;
484 ppport command is used to bundle "ppport.h" to a distribution.
486 requires_external_cc (Module::Install::External)
488 requires_external_cc;
489 requires_external_cc command checks if the user has a working compiler
491 listed in the Config, and exits the "Makefile.PL" if none is found.
492 can_cc (Module::Install::Can)
494 exit 0 unless can_cc;
495 can_cc command tells if the use has a working compiler or not.
497
499 clean_files, realclean_files (Module::Install::Makefile)
500 clean_files '*.o Foo-*';
501 realclean_files '*.o Foo-*';
502 clean_files command takes a string or an array of strings, concatenates
504 them with spaces, and passes the result to ExtUtils::MakeMaker as a
505 "clean" attribute. realclean_files does the same for a "realclean"
506 attribute.
507
509 can_use (Module::Install::Can)
510 if (can_use('Some::Module', '0.05')) {
511 Some::Module::do_something();
512 }
513 can_use command takes a module name, and optionally a version, and
515 checks if the module (with the version if appropriate) is installed or
516 not.
517 can_run (Module::Install::Can)
519 if (can_run('svn')) {
520 # do something with the C<svn> binary
521 }
522 can_run command takes a executable path, and checks if the executable
524 is available or not.
525 requires_external_bin (Module::Install::External)
527 requires_external_bin 'svn';
528 requires_external_bin command takes a executable path, and exits the
530 "Makefile.PL" if none is available.
531
533 Kenichi Ishigaki <ishigaki@cpan.org>
534
536 Copyright 2010 Kenichi Ishigaki.
537 This program is free software; you can redistribute it and/or modify it
539 under the same terms as Perl itself.
540perl v5.16.3 2012-03-01 Module::Install::API(3)