.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Module::Install::API 3pm" .TH Module::Install::API 3pm "2018-01-01" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Module::Install::API \- Command Reference for Module::Install .SH "DESCRIPTION" .IX Header "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. .PP This \s-1API\s0 document lists and describes all the public \fIsupported\fR commands, grouped by the nature or importance of them. .PP If you are a module author and want to use Module::Install in your distributions, this is the document you should consult. .PP 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. .PP Note that commands not listed here should be deemed private utility commands for the Module::Install developers, or \fIunsupported\fR 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. .SH "COMMANDS TO PROVIDE BASIC META DATA" .IX Header "COMMANDS TO PROVIDE BASIC META DATA" Most of these are also described in the main Module::Install's pod. Basically, (almost) all you have to know is the \fBall_from\fR 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 \f(CW\*(C`all_from()\*(C'\fR not to be warned by the lack of information). .SS "all_from (Module::Install::Metadata)" .IX Subsection "all_from (Module::Install::Metadata)" .Vb 1 \& all_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBall_from\fR 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. .SS "name, name_from, module_name (Module::Install::Metadata)" .IX Subsection "name, name_from, module_name (Module::Install::Metadata)" .Vb 2 \& name \*(AqFoo\-Bar\*(Aq; \& name_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBname\fR 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. .PP \&\fBname_from\fR takes a module file path, and looks for the topmost \&\f(CW\*(C`package\*(C'\fR declaration to extract a module name, and then converts it to a distribution name. .PP You may optionally set \fBmodule_name\fR 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 \&\f(CW\*(C`NAME\*(C'\fR attribute (Module::Install usually creates this from the distribution name set by \fBname\fR or \fBname_from\fR). .SS "abstract, abstract_from (Module::Install::Metadata)" .IX Subsection "abstract, abstract_from (Module::Install::Metadata)" .Vb 2 \& abstract \*(Aqa short description of the distribution\*(Aq; \& abstract_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBabstract\fR command takes a string to describe what that module/distribution is for. \fBabstract_from\fR takes a module file path and looks for a string that follows the module's name and a hyphen to separate in the \f(CW\*(C`NAME\*(C'\fR section of the pod. .PP The value set by \fBabstract\fR or \fBabstract_from\fR is passed to ExtUtils::MakeMaker as an \f(CW\*(C`ABSTRACT\*(C'\fR attribute. .SS "version, version_from (Module::Install::Metadata)" .IX Subsection "version, version_from (Module::Install::Metadata)" .Vb 2 \& version \*(Aq0.01\*(Aq; \& version_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBversion\fR command takes a version string for the distribution. \&\fBversion_from\fR takes a module file path, and looks for the \&\f(CW$VERSION\fR of the module. .PP The value set by \fBversion\fR or \fBversion_from\fR is passed to ExtUtils::MakeMaker as a \f(CW\*(C`VERSION\*(C'\fR attribute. \fBversion_from\fR (and \fBall_from\fR) also sets a \f(CW\*(C`VERSION_FROM\*(C'\fR attribute to check version integrity of the distribution. .SS "perl_version, perl_version_from (Module::Install::Metadata)" .IX Subsection "perl_version, perl_version_from (Module::Install::Metadata)" .Vb 2 \& perl_version \*(Aq5.008\*(Aq; \& perl_version_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBperl_version\fR command takes a minimum required perl version for the distribution. \fBperl_version_from\fR takes a module file path, and looks for a \f(CW\*(C`use \*(C'\fR (or \f(CW\*(C`require \*(C'\fR) statement (note that now Module::Install only supports perl 5.005 and newer). .PP The value set by \fBperl_version\fR or \fBperl_version_from\fR is passed to ExtUtils::MakeMaker as a \f(CW\*(C`MIN_PERL_VERSION\*(C'\fR attribute (if applicable). .SS "author, author_from (Module::Install::Metadata)" .IX Subsection "author, author_from (Module::Install::Metadata)" .Vb 2 \& author \*(AqJohn Doe \*(Aq; \& author_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBauthor\fR command takes a string to describe author(s). You can set multiple authors with one \fBauthor\fR command, or with multiple \&\fBauthor\fRs (you can also use \fBauthors\fR alias if you prefer). .PP \&\fBauthor_from\fR takes a module file path, and looks for an \f(CW\*(C`AUTHOR\*(C'\fR (or \f(CW\*(C`AUTHORS\*(C'\fR) section in the pod (and also license/copyright sections if it can't find any author(s) section) to extract an author. .PP The value set by \fBauthor\fR or \fBauthor_from\fR is concatenated and passed to ExtUtils::MakeMaker as an \f(CW\*(C`AUTHOR\*(C'\fR attribute. .SS "license, license_from (Module::Install::Metadata)" .IX Subsection "license, license_from (Module::Install::Metadata)" .Vb 2 \& license \*(Aqperl\*(Aq; \& license_from \*(Aqlib/Foo/Bar.pm\*(Aq; .Ve .PP \&\fBlicense\fR command takes an abbreviated license name including \&\f(CW\*(C`perl\*(C'\fR, \f(CW\*(C`artistic\*(C'\fR, \f(CW\*(C`apache\*(C'\fR, \f(CW\*(C`(l)gpl\*(C'\fR, \f(CW\*(C`bsd\*(C'\fR, \f(CW\*(C`mit\*(C'\fR, \&\f(CW\*(C`mozilla\*(C'\fR, \f(CW\*(C`open_source\*(C'\fR, and so on. If you don't (want to) specify a particular license, it will be \f(CW\*(C`unknown\*(C'\fR. .PP \&\fBlicense_from\fR takes a module file path, and looks for a \f(CW\*(C`LICENSE\*(C'\fR (or \f(CW\*(C`LICENCE\*(C'\fR) section in the pod (and also \f(CW\*(C`COPYRIGHT\*(C'\fR section if it can't find any) to extract a license. .PP The value set by \fBlicense\fR or \fBlicense_from\fR is passed to ExtUtils::MakeMaker as an \f(CW\*(C`LICENSE\*(C'\fR attribute (if applicable). .PP You are also reminded that if the distribution is intended to be uploaded to the \s-1CPAN,\s0 it \fBmust\fR be an OSI-approved open source license. Commercial software is not permitted on the \s-1CPAN.\s0 .SH "COMMANDS TO PROVIDE DEPENDENCIES" .IX Header "COMMANDS TO PROVIDE DEPENDENCIES" Most of these are described in the main pod, too. .SS "requires (Module::Install::Metadata)" .IX Subsection "requires (Module::Install::Metadata)" .Vb 2 \& requires \*(AqFoo::Bar\*(Aq; \& requires \*(AqFoo::Baz\*(Aq => \*(Aq1.00\*(Aq; .Ve .PP \&\fBrequires\fR command takes a module name on which your distribution depends, and its minimum required version if any. You may add arbitrary numbers of \f(CW\*(C`requires\*(C'\fR. 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. .PP The values set by \fBrequires\fR are passed to ExtUtils::MakeMaker as a \f(CW\*(C`PREREQ_PM\*(C'\fR attribute. .SS "build_requires, test_requires (Module::Install::Metadata)" .IX Subsection "build_requires, test_requires (Module::Install::Metadata)" .Vb 4 \& build_requires \*(AqExtUtils::Foo::Bar\*(Aq; \& build_requires \*(AqExtUtils::Foo::Baz\*(Aq => \*(Aq1.00\*(Aq; \& test_requires \*(AqTest::Foo::Bar\*(Aq; \& test_requires \*(AqTest::Foo::Baz\*(Aq => \*(Aq1.00\*(Aq; .Ve .PP \&\fBbuild_requires\fR command also takes a module name and a minimum required version if any. The difference from the \f(CW\*(C`requires\*(C'\fR command is that \fBbuild_requires\fR 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 \s-1CPAN,\s0 from where you usually want to install everything for future reuse (unless you are too lazy to test distributions). .PP As of this writing, \f(CW\*(C`test_requires\*(C'\fR is just an alias for \&\f(CW\*(C`build_requires\*(C'\fR, but this may change in the future. .PP The values set by \fBbuild_requires\fR and \fBtest_requires\fR are passed to ExtUtils::MakeMaker as a \f(CW\*(C`BUILD_REQUIRES\*(C'\fR attribute, which may fall back to \f(CW\*(C`PREREQ_PM\*(C'\fR if your ExtUtils::MakeMaker is not new enough. .SS "configure_requires (Module::Install::Metadata)" .IX Subsection "configure_requires (Module::Install::Metadata)" .Vb 2 \& configure_requires \*(AqExtUtils::Foo::Bar\*(Aq; \& configure_requires \*(AqExtUtils::Foo::Baz\*(Aq => \*(Aq1.00\*(Aq; .Ve .PP \&\fBconfigure_requires\fR command also takes a module name and a minimum required version if any. The difference from the \f(CW\*(C`requires\*(C'\fR command is that \fBconfigure_requires\fR is to call for modules you'll require to run \f(CW\*(C`perl Makefile.PL\*(C'\fR. This attribute only makes sense for the latest \s-1CPAN\s0 toolchains that parse \f(CW\*(C`META.yml\*(C'\fR before running \f(CW\*(C`perl Makefile.PL\*(C'\fR. .PP The values set by \fBconfigure_requires\fR are passed to ExtUtils::MakeMaker as a \f(CW\*(C`CONFIGURE_REQUIRES\*(C'\fR attribute, which may fall back to \f(CW\*(C`PREREQ_PM\*(C'\fR if your ExtUtils::MakeMaker is not new enough. .SS "recommends (Module::Install::Metadata)" .IX Subsection "recommends (Module::Install::Metadata)" .Vb 2 \& recommends \*(AqExtUtils::Foo::Bar\*(Aq; \& recommends \*(AqExtUtils::Foo::Baz\*(Aq => \*(Aq1.00\*(Aq; .Ve .PP \&\fBrecommends\fR command also takes a module name and a minimum required version if any. As of this writing, \f(CW\*(C`recommends\*(C'\fR is purely advisory, only written in the \f(CW\*(C`META.yml\*(C'\fR. Recommended modules will \&\fBnot\fR usually be installed by the current \s-1CPAN\s0 toolchains (other system package managers may possibly prompt you to install them). .SS "features, feature (Module::Install::Metadata)" .IX Subsection "features, feature (Module::Install::Metadata)" .Vb 4 \& feature( \*(Aqshare directory support\*(Aq, \& \-default => 1, \& \*(AqFile::ShareDir\*(Aq => \*(Aq1.00\*(Aq, \& ); \& \& features( \& \*(AqJSON support\*(Aq, [ \& \-default => 0, \& \*(AqJSON::MaybeXS\*(Aq => \*(Aq1.003003\*(Aq, \& ], \& \*(AqYAML support\*(Aq, [ \& \*(AqYAML\*(Aq => \*(Aq0\*(Aq, \& ], \& ); .Ve .PP \&\fBfeature\fR command takes a string to describe what the feature is for, and an array of (optional) modules and their recommended versions if any. \fBfeatures\fR command takes an array of a description and an array of modules. .PP As of this writing, both \f(CW\*(C`feature\*(C'\fR and \f(CW\*(C`features\*(C'\fR work only when \&\fBauto_install\fR (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. .PP However, prompting users also hinders automated installation or smoke testing, and is considered a bad practice (giving sane default values is much preferred). .PP Though \f(CW\*(C`feature\*(C'\fRd modules are optional and can be chosen during the installation, the chosen modules are treated the same as the ones set by \f(CW\*(C`requires\*(C'\fR command. (They are not listed in the \&\f(CW\*(C`recommends\*(C'\fR section in the \f(CW\*(C`META.yml\*(C'\fR). This may change in the future. .PP You can add \f(CW\*(C`\-default => [01]\*(C'\fR in an array of required modules in the \f(CWfeature(s)\fR, to set a default value for the prompt. .SH "COMMANDS TO WRITE METADATA" .IX Header "COMMANDS TO WRITE METADATA" These are the commands to write actual meta files. .SS "WriteAll (Module::Install::WriteAll)" .IX Subsection "WriteAll (Module::Install::WriteAll)" .Vb 1 \& use inc::Module::Install; \& \& all_from \*(Aqlib/Foo/Bar.pm\*(Aq; \& \& WriteAll; .Ve .PP \&\fBWriteAll\fR command is usually the last command in the \&\f(CW\*(C`Makefile.PL\*(C'\fR. 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 \f(CW\*(C`Makefile\*(C'\fR, \f(CW\*(C`META.yml\*(C'\fR, and \&\f(CW\*(C`MYMETA.yml\*(C'\fR (or \f(CW\*(C`MYMETA.json\*(C'\fR) if you set an experimental environmental variable \f(CW\*(C`X_MYMETA\*(C'\fR. .SS "WriteMakefile (Module::Install::MakeMaker)" .IX Subsection "WriteMakefile (Module::Install::MakeMaker)" .Vb 1 \& use inc::Module::Install; \& \& requires \*(AqFoo::Baz\*(Aq; # a la Module::Install \& \& WriteMakefile( # a la ExtUtils::MakeMaker \& NAME => \*(AqFoo::Bar\*(Aq, \& VERSION_FROM => \*(Aqlib/Foo/Bar.pm\*(Aq, \& ); .Ve .PP 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. .SS "write_mymeta_yaml, write_mymeta_json (Module::Install::Metadata)" .IX Subsection "write_mymeta_yaml, write_mymeta_json (Module::Install::Metadata)" .Vb 2 \& write_mymeta_yaml; \& write_mymeta_json; .Ve .PP \&\fBwrite_mymeta_yaml\fR command and \fBwrite_mymeta_json\fR command are to write \f(CW\*(C`MYMETA.yml\*(C'\fR and \f(CW\*(C`MYMETA.json\*(C'\fR respectively, which are new enhancement for the \s-1CPAN\s0 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 \f(CW\*(C`WriteAll\*(C'\fR command) but you can explicitly write these commands in your Makefile.PL. .SH "COMMANDS TO TWEAK MAKEFILE" .IX Header "COMMANDS TO TWEAK MAKEFILE" .SS "makemaker_args (Module::Install::Makefile)" .IX Subsection "makemaker_args (Module::Install::Makefile)" .Vb 4 \& makemaker_args( \& PREREQ_FATAL => 1, \& dist => { PREOP => \*(Aqpod2text lib/Foo/Bar.pm > README\*(Aq }, \& ); .Ve .PP \&\fBmakemaker_args\fR command is used in \f(CW\*(C`WriteMakefile\*(C'\fR command, and takes any attributes ExtUtils::MakeMaker understands. See ExtUtils::MakeMaker for the available attributes. .SS "preamble, postamble (Module::Install::Makefile)" .IX Subsection "preamble, postamble (Module::Install::Makefile)" .Vb 2 \& preamble "# my preamble\en"; \& postamble qq{my_done ::\en\et\e$(PERL) \-e "print qq/done\e\en/"\en}; .Ve .PP \&\fBpreamble\fR and \fBpostamble\fR commands take a string to be embedded in the \f(CW\*(C`Makefile\*(C'\fR. You can add custom targets with this. See appropriate manuals to learn how to write Makefile. .SH "COMMANDS FOR TESTS" .IX Header "COMMANDS FOR TESTS" These are to set test files. .SS "tests (Module::Install::Metadata)" .IX Subsection "tests (Module::Install::Metadata)" .Vb 1 \& tests \*(Aqt/*.t t/*/*.t\*(Aq; .Ve .PP \&\fBtests\fR 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. .PP If you haven't set \f(CW\*(C`tests\*(C'\fR by any means (with explicit \f(CW\*(C`tests\*(C'\fR command, or extensions like Module::Install::AuthorTests or Module::Install::ExtraTests), and if you have an \f(CW\*(C`xt\*(C'\fR directory, Module::Install silently adds those tests under the \f(CW\*(C`xt\*(C'\fR directory when you are in the author mode, or you are doing release testing (with \f(CW\*(C`RELEASE_TESTING\*(C'\fR environmental variable). .PP The value set by \fBtests\fR is passed to ExtUtils::MakeMaker as a \&\f(CW\*(C`test\*(C'\fR attribute. .SS "tests_recurisve (Module::Install::Makefile)" .IX Subsection "tests_recurisve (Module::Install::Makefile)" .Vb 2 \& tests_recursive; \& tests_recursive(\*(Aqt\*(Aq); .Ve .PP \&\fBtests_recursive\fR 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. .SH "COMMANDS TO TWEAK DIRECTORIES TO INSTALL" .IX Header "COMMANDS TO TWEAK DIRECTORIES TO INSTALL" .SS "installdirs (Module::Install::Metadata)" .IX Subsection "installdirs (Module::Install::Metadata)" .Vb 1 \& installdirs \*(Aqsite\*(Aq; .Ve .PP \&\fBinstalldirs\fR 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 \fBinstalldirs\fR is passed to ExtUtils::MakeMaker as an \f(CW\*(C`INSTALLDIRS\*(C'\fR attribute. .SS "install_as_core, install_as_cpan, install_as_site, install_as_vendor (Module::Install::Metadata)" .IX Subsection "install_as_core, install_as_cpan, install_as_site, install_as_vendor (Module::Install::Metadata)" .Vb 4 \& install_as_core; # = installdirs \*(Aqperl\*(Aq; \& install_as_cpan; # = installdirs \*(Aqsite\*(Aq; \& install_as_site; # = installdirs \*(Aqsite\*(Aq; \& install_as_vendor; # = installdirs \*(Aqvendor\*(Aq; .Ve .PP \&\fBinstall_as_*\fR commands are aliases of the corresponding commands shown in the comments above. .SH "COMMANDS TO INSTALL SUBORDINATE FILES" .IX Header "COMMANDS TO INSTALL SUBORDINATE FILES" These are to install files other than the ones under the \f(CW\*(C`lib\*(C'\fR directory. .SS "install_script (Module::Install::Scripts)" .IX Subsection "install_script (Module::Install::Scripts)" .Vb 2 \& install_script(\*(Aqfoo\*(Aq); \& install_script(\*(Aqscript/foo\*(Aq); .Ve .PP \&\fBinstall_script\fR command takes a script file name, and installs it into a \f(CW\*(C`script\*(C'\fR directory for your Perl installation. If your script is in a \f(CW\*(C`script\*(C'\fR directory, you can omit the \f(CW\*(C`script/\*(C'\fR part. .PP The value set by \fBinstall_script\fR is passed to ExtUtils::MakeMaker as an \f(CW\*(C`EXE_FILES\*(C'\fR attribute. .SS "install_share (Module::Install::Share)" .IX Subsection "install_share (Module::Install::Share)" .Vb 4 \& install_share; \& install_share(\*(Aqtemplates\*(Aq); \& install_share(\*(Aqdist\*(Aq, \*(Aqtemplates\*(Aq); \& install_share(\*(Aqmodule\*(Aq, \*(AqMy::WebApp\*(Aq, \*(Aqshare\*(Aq); .Ve .PP \&\fBinstall_share\fR command may take a directory type (either \f(CW\*(C`dist\*(C'\fR or \&\f(CW\*(C`module\*(C'\fR), a module name if necessary, and a directory (\f(CW\*(C`share\*(C'\fR by default), and installs files under the directory into a \f(CW\*(C`share\*(C'\fR 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). .PP You can access these shared files via File::ShareDir's \&\f(CW\*(C`dist_file\*(C'\fR or \f(CW\*(C`module_file\*(C'\fR according to the type. Note also that a shared directory is usually read-only. You can't use this as a private temporary directory. .SH "COMMANDS FOR AUTO INSTALLATION" .IX Header "COMMANDS FOR AUTO INSTALLATION" .SS "auto_install (Module::Install::AutoInstall)" .IX Subsection "auto_install (Module::Install::AutoInstall)" .Vb 1 \& auto_install; .Ve .PP The \fBauto_install\fR command is used to allow users to install dependencies of a local project when you run \f(CW\*(C`make\*(C'\fR after \f(CW\*(C`. 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 \fBnot\fR completely replace \&\f(CW\*(C`auto_install\*(C'\fR). For example you can use \f(CW\*(C`cpan .\*(C'\fR (with newer \&\s-1CPAN\s0) or \f(CW\*(C`cpanm \-\-installdeps .\*(C'\fR (with App::cpanminus). .PP \&\f(CW\*(C`auto_install\*(C'\fR also enables \f(CWfeature(s)\fR commands to choose what you install (keep in mind that using \f(CW\*(C`feature()\*(C'\fR in \s-1CPAN\s0 distributions is generally considered a bad practice). .SH "COMMANDS TO SUBDIRECTORY INSTALLATION" .IX Header "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. .SS "build_subdirs (Module::Install::Makefile)" .IX Subsection "build_subdirs (Module::Install::Makefile)" .Vb 1 \& build_subdirs \*(Aqwin32\*(Aq if $^O eq \*(AqMSWin32\*(Aq; .Ve .PP \&\fBbuild_subdirs\fR command takes subdirectories where projects you want to install are in. The values set by \fBbuild_subdirs\fR are passed to ExtUtils::MakeMaker as a \f(CW\*(C`DIR\*(C'\fR attribute. .SH "COMMANDS TO PROVIDE OTHER OPTIONAL META DATA" .IX Header "COMMANDS TO PROVIDE OTHER OPTIONAL META DATA" These are to provide optional meta data mainly used by the \s-1PAUSE\s0 indexer and the \s-1CPAN\s0 search site. See also the META-spec page () for details. .SS "no_index (Module::Install::Metadata)" .IX Subsection "no_index (Module::Install::Metadata)" .Vb 4 \& no_index file => \*(Aqlib/My/Test/Module.pm\*(Aq; \& no_index directory => \*(Aqtemplates\*(Aq; \& no_index package => \*(AqTest::Foo::Bar\*(Aq; \& no_index namespace => \*(AqTest::Foo::Bar\*(Aq; .Ve .PP \&\fBno_index\fR command takes a hash to describe what should be excluded from the \s-1PAUSE\s0 index etc. Module::Install provides several \&\f(CW\*(C`no_index\*(C'\fR directories by default, including \f(CW\*(C`inc\*(C'\fR, \f(CW\*(C`share\*(C'\fR, \&\f(CW\*(C`(x)t\*(C'\fR, \f(CW\*(C`test\*(C'\fR, \f(CWexample(s)\fR, \f(CW\*(C`demo\*(C'\fR. .SS "resources (Module::Install::Metadata)" .IX Subsection "resources (Module::Install::Metadata)" .Vb 6 \& 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"; .Ve .PP \&\fBresources\fR command takes a hash that contains various URLs for the related resources. Keys in lower-case are reserved. These resources are written in the \f(CW\*(C`META.yml\*(C'\fR. .SS "homepage, bugtracker, repository (Module::Install::Metadata)" .IX Subsection "homepage, bugtracker, repository (Module::Install::Metadata)" .Vb 3 \& homepage \*(Aqhttp://example.com\*(Aq; \& bugtracker \*(Aqhttp://rt.cpan.org\*(Aq; \& repository \*(Aqhttp://github.com/foo/bar\*(Aq; .Ve .PP \&\fBhomepage\fR, \fBbugtracker\fR, and \f(CW\*(C`repository\*(C'\fR commands take a \s-1URL\s0 for the corresponding resource. .SH "COMMANDS TO BUNDLE DISTRIBUTIONS" .IX Header "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. .SH "COMMANDS FOR XS SUPPORT" .IX Header "COMMANDS FOR XS SUPPORT" .SS "libs (Module::Install::Makefile), cc_lib_paths, cc_lib_links (Module::Install::Compiler)" .IX Subsection "libs (Module::Install::Makefile), cc_lib_paths, cc_lib_links (Module::Install::Compiler)" .Vb 4 \& libs \*(Aq\-lz\*(Aq; \& libs [qw/\-lz \-Llibs/]; \& cc_lib_paths \*(Aqlibs\*(Aq; \& cc_lib_links qw/z iconv/; .Ve .PP \&\fBlibs\fR command takes a string, or an array reference of strings to be passed to ExtUtils::MakeMaker as a \f(CW\*(C`LIBS\*(C'\fR attribute. \&\fBcc_lib_paths\fR and \fBcc_lib_links\fR are its alternatives, both of which take an array of strings. \f(CW\*(C`cc_lib_paths\*(C'\fR is for upper-cased \&\f(CW\*(C`\-L\*(C'\fR (directories), and \f(CW\*(C`cc_lib_links\*(C'\fR is for lower-cased \f(CW\*(C`\-l\*(C'\fR (libraries). .SS "inc (Module::Install::Makefile), cc_inc_paths (Module::Install::Compiler)" .IX Subsection "inc (Module::Install::Makefile), cc_inc_paths (Module::Install::Compiler)" .Vb 2 \& inc \*(Aq\-I. \-Iinclude\*(Aq; \& cc_inc_paths qw/. include/; .Ve .PP \&\fBinc\fR command takes a string to be passed to ExtUtils::MakeMaker as an \f(CW\*(C`INC\*(C'\fR attribute. \fBcc_inc_paths\fR is its alternative, and takes an array of directories. .SS "cc_optimize_flags (Module::Install::Compiler)" .IX Subsection "cc_optimize_flags (Module::Install::Compiler)" .Vb 1 \& cc_optimize_flags \*(Aq\-O2\*(Aq; .Ve .PP \&\fBcc_optimize_flags\fR takes a string to be passed to ExtUtils::MakeMaker as an \f(CW\*(C`OPTIMIZE\*(C'\fR attribute. .SS "ppport (Module::Install::Compiler)" .IX Subsection "ppport (Module::Install::Compiler)" .Vb 1 \& ppport; .Ve .PP \&\fBppport\fR command is used to bundle \f(CW\*(C`ppport.h\*(C'\fR to a distribution. .SS "requires_external_cc (Module::Install::External)" .IX Subsection "requires_external_cc (Module::Install::External)" .Vb 1 \& requires_external_cc; .Ve .PP \&\fBrequires_external_cc\fR command checks if the user has a working compiler listed in the Config, and exits the \f(CW\*(C`Makefile.PL\*(C'\fR if none is found. .SS "can_cc (Module::Install::Can)" .IX Subsection "can_cc (Module::Install::Can)" .Vb 1 \& exit 0 unless can_cc; .Ve .PP \&\fBcan_cc\fR command tells if the use has a working compiler or not. .SH "COMMANDS FOR CLEANUP" .IX Header "COMMANDS FOR CLEANUP" .SS "clean_files, realclean_files (Module::Install::Makefile)" .IX Subsection "clean_files, realclean_files (Module::Install::Makefile)" .Vb 2 \& clean_files \*(Aq*.o Foo\-*\*(Aq; \& realclean_files \*(Aq*.o Foo\-*\*(Aq; .Ve .PP \&\fBclean_files\fR command takes a string or an array of strings, concatenates them with spaces, and passes the result to ExtUtils::MakeMaker as a \f(CW\*(C`clean\*(C'\fR attribute. \fBrealclean_files\fR does the same for a \f(CW\*(C`realclean\*(C'\fR attribute. .SH "UTILITY COMMANDS" .IX Header "UTILITY COMMANDS" .SS "can_use (Module::Install::Can)" .IX Subsection "can_use (Module::Install::Can)" .Vb 3 \& if (can_use(\*(AqSome::Module\*(Aq, \*(Aq0.05\*(Aq)) { \& Some::Module::do_something(); \& } .Ve .PP \&\fBcan_use\fR command takes a module name, and optionally a version, and checks if the module (with the version if appropriate) is installed or not. .SS "can_run (Module::Install::Can)" .IX Subsection "can_run (Module::Install::Can)" .Vb 3 \& if (can_run(\*(Aqsvn\*(Aq)) { \& # do something with the C binary \& } .Ve .PP \&\fBcan_run\fR command takes a executable path, and checks if the executable is available or not. .SS "requires_external_bin (Module::Install::External)" .IX Subsection "requires_external_bin (Module::Install::External)" .Vb 1 \& requires_external_bin \*(Aqsvn\*(Aq; .Ve .PP \&\fBrequires_external_bin\fR command takes a executable path, and exits the \f(CW\*(C`Makefile.PL\*(C'\fR if none is available. .SH "AUTHOR" .IX Header "AUTHOR" Kenichi Ishigaki .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2010 Kenichi Ishigaki. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.