NAME¶
Module::Install::API - Command Reference for Module::Install
DESCRIPTION¶
Module::Install has lots of commands scattered in the extensions. Several common
commands are described in the main Module::Install's pod, but you usually need
to know more to do what you want.
This API document lists and describes all the public
supported commands,
grouped by the nature or importance of them.
If you are a module author and want to use Module::Install in your
distributions, this is the document you should consult.
If you are a user (or a contributor) of distributions that use Module::Install,
you may also want to check Module::Install::FAQ where you'll find some common
glitches you may encounter.
Note that commands not listed here should be deemed private utility commands for
the Module::Install developers, or
unsupported commands with various
reasons (some are experimental and half-baked, some are broken (by design or
by implementation), some are simply deprecated, and so on). You may find some
of them are used rather widely, but their use is discouraged. You have been
warned.
Most of these are also described in the main Module::Install's pod. Basically,
(almost) all you have to know is the
all_from command that tries to
extract all the necessary basic meta data from a module file, but you can also
specify one by one what is not written in the module and can't be extracted
(you usually want to write these specific commands before
"all_from()" not to be warned by the lack of information).
all_from 'lib/Foo/Bar.pm';
all_from command takes a module file path, and will try to extract meta
data from the module including a distribution name, a module version, the
minimum required perl version for the module, authors information, a license,
a short description of the module. See the following commands for the
extraction detail.
name 'Foo-Bar';
name_from 'lib/Foo/Bar.pm';
name commmand takes a distribution name. It usually differs slightly from
a module name (a module name is separated by double colons; a distribution
name is separated by hyphens). Just replacing all the double colons of your
main module with hyphens would be enough for you.
name_from takes a module file path, and looks for the topmost
"package" declaration to extract a module name, and then converts it
to a distribution name.
You may optionally set
module_name to specify a main module name (if you
choose other naming scheme for your distribution). This value is directly
passed to ExtUtils::MakeMaker in the backend as a "NAME" attribute
(Module::Install usually creates this from the distribution name set by
name or
name_from).
abstract 'a short description of the distribution';
abstract_from 'lib/Foo/Bar.pm';
abstract command takes a string to describe what that module/distribution
is for.
abstract_from takes a module file path and looks for a string
that follows the module's name and a hyphen to separate in the
"NAME" section of the pod.
The value set by
abstract or
abstract_from is passed to
ExtUtils::MakeMaker as an "ABSTRACT" attribute.
version '0.01';
version_from 'lib/Foo/Bar.pm';
version command takes a version string for the distribution.
version_from takes a module file path, and looks for the $VERSION of
the module.
The value set by
version or
version_from is passed to
ExtUtils::MakeMaker as a "VERSION" attribute.
version_from
(and
all_from) also sets a "VERSION_FROM" attribute to check
version integrity of the distribution.
perl_version '5.008';
perl_version_from 'lib/Foo/Bar.pm';
perl_version command takes a minimum required perl version for the
distribution.
perl_version_from takes a module file path, and looks for
a "use <perl_version>" (or "require
<perl_version>") statement (note that now Module::Install only
supports perl 5.005 and newer).
The value set by
perl_version or
perl_version_from is passed to
ExtUtils::MakeMaker as a "MIN_PERL_VERSION" attribute (if
applicable).
author 'John Doe <john.doe at cpan.org>';
author_from 'lib/Foo/Bar.pm';
author command takes a string to describe author(s). You can set multiple
authors with one
author command, or with multiple
authors (you
can also use
authors alias if you prefer).
author_from takes a module file path, and looks for an "AUTHOR"
(or "AUTHORS") section in the pod (and also license/copyright
sections if it can't find any author(s) section) to extract an author.
The value set by
author or
author_from is concatenated and passed
to ExtUtils::MakeMaker as an "AUTHOR" attribute.
license 'perl';
license_from 'lib/Foo/Bar.pm';
license command takes an abbreviated license name including
"perl", "artistic", "apache",
"(l)gpl", "bsd", "mit", "mozilla",
"open_source", and so on. If you don't (want to) specify a
particular license, it will be "unknown".
license_from takes a module file path, and looks for a
"LICENSE" (or "LICENCE") section in the pod (and also
"COPYRIGHT" section if it can't find any) to extract a license.
The value set by
license or
license_from is passed to
ExtUtils::MakeMaker as an "LICENSE" attribute (if applicable).
You are also reminded that if the distribution is intended to be uploaded to the
CPAN, it
must be an OSI-approved open source license. Commercial
software is not permitted on the CPAN.
COMMANDS TO PROVIDE DEPENDENCIES¶
Most of these are described in the main pod, too.
requires 'Foo::Bar';
requires 'Foo::Baz' => '1.00';
requires command takes a module name on which your distribution depends,
and its minimum required version if any. You may add arbitrary numbers of
"requires". You even can add multiple numbers of dependencies on the
same module with different required versions (which will be sorted out later,
though). Note that this dependency is on the basis of a module, not of a
distribution. This usually doesn't matter, and you just need to call for a
module you really need (then you'll get the whole distribution it belongs to),
but sometimes you may need to call for all the modules that the required
module implicitly requires.
The values set by
requires are passed to ExtUtils::MakeMaker as a
"PREREQ_PM" attribute.
build_requires 'ExtUtils::Foo::Bar';
build_requires 'ExtUtils::Foo::Baz' => '1.00';
test_requires 'Test::Foo::Bar';
test_requires 'Test::Foo::Baz' => '1.00';
build_requires command also takes a module name and a minimum required
version if any. The difference from the "requires" command is that
build_requires is to call for modules you'll require while building the
distribution, or in the tests, and that in theory are not required at
run-time. This distinction is more for other system package managers than for
the CPAN, from where you usually want to install everything for future reuse
(unless you are too lazy to test distributions).
As of this writing, "test_requires" is just an alias for
"build_requires", but this may change in the future.
The values set by
build_requires and
test_requires are passed to
ExtUtils::MakeMaker as a "BUILD_REQUIRES" attribute, which may fall
back to "PREREQ_PM" if your ExtUtils::MakeMaker is not new enough.
configure_requires 'ExtUtils::Foo::Bar';
configure_requires 'ExtUtils::Foo::Baz' => '1.00';
configure_requires command also takes a module name and a minimum
required version if any. The difference from the "requires" command
is that
configure_requires is to call for modules you'll require to run
"perl Makefile.PL". This attribute only makes sense for the latest
CPAN toolchains that parse "META.yml" before running "perl
Makefile.PL".
The values set by
configure_requires are passed to ExtUtils::MakeMaker as
a "CONFIGURE_REQUIRES" attribute, which may fall back to
"PREREQ_PM" if your ExtUtils::MakeMaker is not new enough.
recommends 'ExtUtils::Foo::Bar';
recommends 'ExtUtils::Foo::Baz' => '1.00';
recommends command also takes a module name and a minimum required
version if any. As of this writing, "recommends" is purely advisory,
only written in the "META.yml". Recommended modules will
not
usually be installed by the current CPAN toolchains (other system package
managers may possibly prompt you to install them).
feature( 'share directory support',
-default => 1,
'File::ShareDir' => '1.00',
);
features(
'JSON support', [
-default => 0,
'JSON' => '2.00',
'JSON::XS' => '2.00',
],
'YAML support', [
'YAML' => '0',
],
);
feature command takes a string to describe what the feature is for, and
an array of (optional) modules and their recommended versions if any.
features command takes an array of a description and an array of
modules.
As of this writing, both "feature" and "features" work only
when
auto_install (see below) is set. These are used to allow
distribution users to choose what they install along with the distribution.
This may be useful if the distribution has lots of optional features that may
not work on all the platforms, or that require too many modules for average
users.
However, prompting users also hinders automated installation or smoke testing,
and is considered a bad practice (giving sane default values is much
preferred).
Though "feature"d modules are optional and can be chosen during the
installation, the chosen modules are treated the same as the ones set by
"requires" command. (They are not listed in the
"recommends" section in the "META.yml"). This may change
in the future.
You can add "-default => [01]" in an array of required modules in
the feature(s), to set a default value for the prompt.
These are the commands to write actual meta files.
WriteAll (Module::Install::WriteAll)¶
use inc::Module::Install;
all_from 'lib/Foo/Bar.pm';
WriteAll;
WriteAll command is usually the last command in the
"Makefile.PL". It can take several attributes, but you usually don't
need to care unless you want to write a Makefile for an Inline-based module.
This writes "Makefile", "META.yml", and
"MYMETA.yml" (or "MYMETA.json") if you set an experimental
environmental variable "X_MYMETA".
WriteMakefile (Module::Install::MakeMaker)¶
use inc::Module::Install;
requires 'Foo::Baz'; # a la Module::Install
WriteMakefile( # a la ExtUtils::MakeMaker
NAME => 'Foo::Bar',
VERSION_FROM => 'lib/Foo/Bar.pm',
);
If you're familiar with ExtUtils::MakeMaker and generally want to stick to its
way, you can. Use as much Module::Install's magic as you want, and then fall
back to the good and old way. It just works.
write_mymeta_yaml;
write_mymeta_json;
write_mymeta_yaml command and
write_mymeta_json command are to
write "MYMETA.yml" and "MYMETA.json" respectively, which
are new enhancement for the CPAN toolchains that eventually will allow
toolchain modules to know what modules are required without parsing Makefile
etc. These are mainly for internal use (in the "WriteAll" command)
but you can explicitly write these commands in your Makefile.PL.
COMMANDS TO TWEAK MAKEFILE¶
makemaker_args (Module::Install::Makefile)¶
makemaker_args(
PREREQ_FATAL => 1,
dist => { PREOP => 'pod2text lib/Foo/Bar.pm > README' },
);
makemaker_args command is used in "WriteMakefile" command, and
takes any attributes ExtUtils::MakeMaker understands. See ExtUtils::MakeMaker
for the available attributes.
preamble, postamble (Module::Install::Makefile)¶
preamble "# my preamble\n";
postamble qq{my_done ::\n\t\$(PERL) -e "print qq/done\\n/"\n};
preamble and
postamble commands take a string to be embedded in
the "Makefile". You can add custom targets with this. See
appropriate manuals to learn how to write Makefile.
COMMANDS FOR TESTS¶
These are to set test files.
tests 't/*.t t/*/*.t';
tests command takes a string to specify test files. You can use wildcard
characters, and if you want to run tests under several directories,
concatenates the specs with white spaces.
If you haven't set "tests" by any means (with explicit
"tests" command, or extensions like Module::Install::AuthorTests or
Module::Install::ExtraTests), and if you have an "xt" directory,
Module::Install silently adds those tests under the "xt" directory
when you are in the author mode, or you are doing release testing (with
"RELEASE_TESTING" environmental variable).
The value set by
tests is passed to ExtUtils::MakeMaker as a
"test" attribute.
tests_recurisve (Module::Install::Makefile)¶
tests_recursive;
tests_recursive('t');
tests_recursive command may take a directory, and looks for test files
under it recursively. As of this writing, you can't use this command with
other test related commands.
COMMANDS TO TWEAK DIRECTORIES TO INSTALL¶
installdirs 'site';
installdirs command takes a directory type, and changes a directory to
install modules and so on, though you usually don't need to use this. The
value set by
installdirs is passed to ExtUtils::MakeMaker as an
"INSTALLDIRS" attribute.
install_as_core; # = installdirs 'perl';
install_as_cpan; # = installdirs 'site';
install_as_site; # = installdirs 'site';
install_as_vendor; # = installdirs 'vendor';
install_as_* commands are aliases of the corresponding commands shown in
the comments above.
COMMANDS TO INSTALL SUBORDINATE FILES¶
These are to install files other than the ones under the "lib"
directory.
install_script (Module::Install::Scripts)¶
install_script('foo');
install_script('script/foo');
install_script command takes a script file name, and installs it into a
"script" directory for your Perl installation. If your script is in
a "script" directory, you can omit the "script/" part.
The value set by
install_script is passed to ExtUtils::MakeMaker as an
"EXE_FILES" attribute.
install_share (Module::Install::Share)¶
install_share;
install_share('templates');
install_share('dist', 'templates');
install_share('module', 'My::WebApp', 'share');
install_share command may take a directory type (either "dist"
or "module"), a module name if necessary, and a directory
("share" by default), and installs files under the directory into a
"share" directory for the type, which is usually in a directory your
perl is installed in (but this may not be true if you're using local::lib and
the likes).
You can access these shared files via File::ShareDir's "dist_file" or
"module_file" according to the type. Note also that a shared
directory is usually read-only. You can't use this as a private temporary
directory.
COMMANDS FOR AUTO INSTALLATION¶
auto_install (Module::Install::AutoInstall)¶
auto_install;
The
auto_install command is used to allow users to install dependencies
of a local project when you run "make" after "<perl
Makefile.PL">. In the past this was the only sane way to pull extra
dependencies without installing the actual module, although now there are some
alternatives (which however do
not completely replace
"auto_install"). For example you can use "cpan ." (with
newer CPAN) or "cpanm --installdeps ." (with App::cpanminus).
"auto_install" also enables feature(s) commands to choose what you
install (keep in mind that using "feature()" in CPAN distributions
is generally considered a bad practice).
COMMANDS TO SUBDIRECTORY INSTALLATION¶
Module::Install 0.96 and above installs distributions in the subdirectories by
default as ExtUtils::MakeMaker does. You also can specify what to install one
by one.
build_subdirs (Module::Install::Makefile)¶
build_subdirs 'win32' if $^O eq 'MSWin32';
build_subdirs command takes subdirectories where projects you want to
install are in. The values set by
build_subdirs are passed to
ExtUtils::MakeMaker as a "DIR" attribute.
These are to provide optional meta data mainly used by the PAUSE indexer and the
CPAN search site. See also the META-spec page
(<
http://module-build.sourceforge.net/META-spec.html>) for details.
no_index file => 'lib/My/Test/Module.pm';
no_index directory => 'templates';
no_index package => 'Test::Foo::Bar';
no_index namespace => 'Test::Foo::Bar';
no_index command takes a hash to describe what should be excluded from
the PAUSE index etc. Module::Install provides several "no_index"
directories by default, including "inc", "share",
"(x)t", "test", example(s), "demo".
resources
license => "http://dev.perl.org/licenses",
homepage => "http://yourproject.host.org",
bugtracker => "http://rt.cpan.org/NoAuth/Bugs.html?Dist=Foo-Bar",
repository => "http://yourhost.com/myscm",
MailingList => "http://yourhost.com/listinfo/foo-bar";
resources command takes a hash that contains various URLs for the related
resources. Keys in lower-case are reserved. These resources are written in the
"META.yml".
homepage, bugtracker, repository (Module::Install::Metadata)¶
homepage 'http://example.com';
bugtracker 'http://rt.cpan.org';
repository 'http://github.com/foo/bar';
homepage,
bugtracker, and "repository" commands take a
URL for the corresponding resource.
COMMANDS TO BUNDLE DISTRIBUTIONS¶
There are several commands to bundle modules/distributions in your distribution,
but they are still broken in general. Don't use them for now.
COMMANDS FOR XS SUPPORT¶
libs (Module::Install::Makefile), cc_lib_paths, cc_lib_links (Module::Install::Compiler)¶
libs '-lz';
libs [qw/-lz -Llibs/];
cc_lib_paths 'libs';
cc_lib_links qw/z iconv/;
libs command takes a string, or an array reference of strings to be
passed to ExtUtils::MakeMaker as a "LIBS" attribute.
cc_lib_paths and
cc_lib_links are its alternatives, both of
which take an array of strings. "cc_lib_paths" is for upper-cased
"-L" (directories), and "cc_lib_links" is for lower-cased
"-l" (libraries).
inc (Module::Install::Makefile), cc_inc_paths (Module::Install::Compiler)¶
inc '-I. -Iinclude';
cc_inc_paths qw/. include/;
inc command takes a string to be passed to ExtUtils::MakeMaker as an
"INC" attribute.
cc_inc_paths is its alternative, and takes
an array of directories.
cc_optimize_flags (Module::Install::Compiler)¶
cc_optimize_flags '-O2';
cc_optimize_flags takes a string to be passed to ExtUtils::MakeMaker as
an "OPTIMIZE" attribute.
ppport (Module::Install::Compiler)¶
ppport;
ppport command is used to bundle "ppport.h" to a distribution.
requires_external_cc (Module::Install::External)¶
requires_external_cc;
requires_external_cc command checks if the user has a working compiler
listed in the Config, and exits the "Makefile.PL" if none is found.
can_cc (Module::Install::Can)¶
exit 0 unless can_cc;
can_cc command tells if the use has a working compiler or not.
COMMANDS FOR CLEANUP¶
clean_files, realclean_files (Module::Install::Makefile)¶
clean_files '*.o Foo-*';
realclean_files '*.o Foo-*';
clean_files command takes a string or an array of strings, concatenates
them with spaces, and passes the result to ExtUtils::MakeMaker as a
"clean" attribute.
realclean_files does the same for a
"realclean" attribute.
UTILITY COMMANDS¶
can_use (Module::Install::Can)¶
if (can_use('Some::Module', '0.05')) {
Some::Module::do_something();
}
can_use command takes a module name, and optionally a version, and checks
if the module (with the version if appropriate) is installed or not.
can_run (Module::Install::Can)¶
if (can_run('svn')) {
# do something with the C<svn> binary
}
can_run command takes a executable path, and checks if the executable is
available or not.
requires_external_bin (Module::Install::External)¶
requires_external_bin 'svn';
requires_external_bin command takes a executable path, and exits the
"Makefile.PL" if none is available.
AUTHOR¶
Kenichi Ishigaki <ishigaki@cpan.org>
COPYRIGHT¶
Copyright 2010 Kenichi Ishigaki.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.