Provided by: libmodule-install-perl_1.19-2_all bug

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.

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 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 (Module::Install::Metadata)
         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, name_from, module_name (Module::Install::Metadata)
         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 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, abstract_from (Module::Install::Metadata)
         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, version_from (Module::Install::Metadata)
         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, perl_version_from (Module::Install::Metadata)
         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, author_from (Module::Install::Metadata)
         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, license_from (Module::Install::Metadata)
         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 (Module::Install::Metadata)
         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, test_requires (Module::Install::Metadata)
         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 (Module::Install::Metadata)
         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 (Module::Install::Metadata)
         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).

   features, feature (Module::Install::Metadata)
         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 "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.

COMMANDS TO WRITE METADATA

       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 (Module::Install::Metadata)
         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 (Module::Install::Metadata)
         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 (Module::Install::Metadata)
         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, install_as_cpan, install_as_site, install_as_vendor
       (Module::Install::Metadata)
         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.

COMMANDS TO PROVIDE OTHER OPTIONAL META DATA

       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 (Module::Install::Metadata)
         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 (Module::Install::Metadata)
         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.