| Module::Install::API - Command Reference for Module::Install |
Module::Install::API - Command Reference for Module::Install
the Module::Install manpage has lots of commands scattered in the extensions. Several common commands are described in the main the Module::Install manpage'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 the Module::Install manpage in your distributions, this is the document you should consult.
If you are a user (or a contributor) of distributions that use the Module::Install manpage, you may also want to check the Module::Install::FAQ manpage where you'll find some common glitches you may encounter.
Note that commands not listed here should be deemed private utility commands for the the Module::Install manpage 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 the Module::Install manpage'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 command 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 the ExtUtils::MakeMaker manpage 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
the ExtUtils::MakeMaker manpage 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
the ExtUtils::MakeMaker manpage 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 L<Module::Install> only supports perl
5.005 and newer).
The value set by perl_version or perl_version_from is passed to
the ExtUtils::MakeMaker manpage 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 the ExtUtils::MakeMaker manpage 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
the ExtUtils::MakeMaker manpage 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.
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 the ExtUtils::MakeMaker manpage 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 the ExtUtils::MakeMaker manpage as a BUILD_REQUIRES attribute, which may
fall back to PREREQ_PM if your the ExtUtils::MakeMaker manpage 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
the ExtUtils::MakeMaker manpage as a CONFIGURE_REQUIRES attribute, which
may fall back to PREREQ_PM if your the ExtUtils::MakeMaker manpage 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::MaybeXS' => '1.003003',
],
'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 featured 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.
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
the Inline manpage-based module. This writes Makefile, META.yml, and
MYMETA.yml (or MYMETA.json) if you set an experimental
environmental variable X_MYMETA.
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 the ExtUtils::MakeMaker manpage and generally want to stick to its way, you can. Use as much the Module::Install manpage'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.
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 the ExtUtils::MakeMaker manpage understands. See
the ExtUtils::MakeMaker manpage for the available attributes.
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.
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 the Module::Install::AuthorTests manpage or
the Module::Install::ExtraTests manpage), and if you have an xt directory,
the Module::Install manpage 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 the ExtUtils::MakeMaker manpage as a
test attribute.
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.
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
the ExtUtils::MakeMaker manpage 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.
These are to install files other than the ones under the lib
directory.
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
the ExtUtils::MakeMaker manpage as an EXE_FILES attribute.
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 the local::lib manpage
and the likes).
You can access these shared files via the File::ShareDir manpage'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.
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
the CPAN manpage) or cpanm --installdeps . (with the App::cpanminus manpage).
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).
the Module::Install manpage 0.96 and above installs distributions in the subdirectories by default as the ExtUtils::MakeMaker manpage does. You also can specify what to install one by one.
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
the ExtUtils::MakeMaker manpage 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. the Module::Install manpage 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 '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.
There are several commands to bundle modules/distributions in your distribution, but they are still broken in general. Don't use them for now.
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 the ExtUtils::MakeMaker manpage 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 '-I. -Iinclude'; cc_inc_paths qw/. include/;
inc command takes a string to be passed to the ExtUtils::MakeMaker manpage
as an INC attribute. cc_inc_paths is its alternative, and
takes an array of directories.
cc_optimize_flags '-O2';
cc_optimize_flags takes a string to be passed to
the ExtUtils::MakeMaker manpage as an OPTIMIZE attribute.
ppport;
ppport command is used to bundle ppport.h to a distribution.
requires_external_cc;
requires_external_cc command checks if the user has a working
compiler listed in the the Config manpage, and exits the Makefile.PL if
none is found.
exit 0 unless can_cc;
can_cc command tells if the use has a working compiler or not.
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
the ExtUtils::MakeMaker manpage as a clean attribute. realclean_files
does the same for a realclean attribute.
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.
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 'svn';
requires_external_bin command takes a executable path, and exits
the Makefile.PL if none is available.
Kenichi Ishigaki <ishigaki@cpan.org>
Copyright 2010 Kenichi Ishigaki.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| Module::Install::API - Command Reference for Module::Install |