README

NAME
    Module::Install - Standalone, extensible Perl module installer

SYNOPSIS
    In your Makefile.PL: (Recommended Usage)

      use inc::Module::Install;

      # Define metadata
      name           'Your-Module';
      all_from       'lib/Your/Module.pm';

      # Specific dependencies
      requires       'File::Spec'  => '0.80';
      test_requires  'Test::More'  => '0.42';
      recommends     'Text::CSV_XS'=> '0.50';
      no_index       'directory'   => 'demos';
      install_script 'myscript';

      WriteAll;

    Quickly upgrade a legacy ExtUtil::MakeMaker installer:

      use inc::Module::Install;
      WriteMakefile( ... );

WARNING
    Please note that while Module::Install pioneered many great ideas in its
    time, its primary benefits have been better achieved by the authoring
    tool Dist::Zilla, and its spinoffs Dist::Milla and Minilla. These tools
    allow the author to build and maintain distributions with DWIM
    convenience, while the distribution is installed directly by
    ExtUtils::MakeMaker or similar installation tools, avoiding the
    complexity of bundling the installer. Dist::Zilla additionally has a
    more robust plugin system which makes it easier to keep up with changes
    to the CPAN::Meta::Spec and add other new functionality. Use of
    Module::Install for new distributions is therefore discouraged by the
    maintainers.

DESCRIPTION
    Module::Install is a package for writing installers for CPAN (or
    CPAN-like) distributions that are clean, simple, minimalist, act in a
    strictly correct manner with ExtUtils::MakeMaker, and will run on any
    Perl installation version 5.005 or newer.

    The intent is to make it as easy as possible for CPAN authors (and
    especially for first-time CPAN authors) to have installers that follow
    all the best practices for distribution installation, but involve as
    much DWIM (Do What I Mean) as possible when writing them.

  Writing Module::Install Installers
    The quickest way to get started with Module::Install is to copy the
    "SYNOPSIS" from above and save it as your own Makefile.PL. Then modify
    the file to suit your own particular case, using the list of commands
    documented in "COMMON COMMANDS" below.

    If all you want to do is write an installer, go and do that now. You
    don't really need the rest of this description unless you are interested
    in the details.

How it Works
    The motivation behind Module::Install is that distributions need to
    interact with a large number of different versions of perl and module
    installers infrastructure, primarily CPAN.pm, CPANPLUS.pm,
    ExtUtils::MakeMaker and Module::Build.

    These have accumulated greatly varying feature and bug profiles over the
    years, and it is now very difficult to write an installer that will work
    properly using only the installed versions of these modules,

    For example, the CPAN.pm version shipped with Perl 5.005 is now 5+ years
    old and considered highly buggy, yet it still exists on quite a number
    of legacy machines.

    Rather than try to target one specific installer and/or make you add
    twisty workaround expressions to every piece of install code you write,
    Module::Install will copy part of itself into each module distribution
    it creates.

    This allows new improvements to be used in your installers regardless of
    the age of the system a distribution is being installed on, at the cost
    of a small increase in the size of your distribution.

  History
    This module was originally written by Brian Ingerson as a smart drop-in
    replacement for ExtUtils::MakeMaker.

    For more information, see Brian's *Creating Module Distributions with
    Module::Install* in June 2003 issue of The Perl Journal
    (<http://www.drdobbs.com/web-development/creating-module-distributions-w
    ith-modul/184416018>)

    For a lot more information, and some personal opinions on the module and
    its creation, see Module::Install::Philosophy.

COMMON COMMANDS
    The following are the most common commands generally used in installers.

    It is far from an exhaustive list, as many of the plugins provide
    commands to work in more details that you would normally need.

  name
      name 'My-Module';

    The name command is compulsory command, generally the first.

    It provides the name of your distribution, which for a module like
    Your::Module would normally be "Your-Module".

    This naming scheme is not hard and fast and you should note that
    distributions are actually a separate naming scheme from modules.

    For example the LWP modules come in a distribution called "libwww-perl".

  all_from
      all_from 'lib/My/Module.pm';

    For most simple Perl distributions that feature one dominant module or
    class as the base, you can get the most Do What I Mean functionality by
    using the all_from command, which will try to extract as much metadata
    as possible from the Perl code and POD in that primary module.

    Functionally, "all_from" is equivalent to "abstract_from" +
    "author_from" + "version_from" + "license_from" + "perl_version_from".
    See below for details.

    If any of these values are set already before "all_from" is used, they
    will kept and not be overwritten.

  abstract
      abstract 'This distribution does something';

    All distributions have an abstract, a short description of the
    distribution as a whole. It is usually around 30-70 characters long.

    The "abstract" command is used to explicitly set the abstract for the
    distribution, at least as far as the metadata file for the distribution
    is concerned.

  abstract_from
      abstract_from 'lib/My/Module.pm';

    The "abstract_from" command retrieves the abstract from a particular
    file contained in the distribution package. Most often this is done from
    the main module, where "Module::Install" will read the POD and use
    whatever is in the "=head1 NAME" section (with module name stripped if
    needed)

    "abstract_from" is set as part of "all_from".

  author
      author 'Adam Kennedy <adamk@cpan.org>';

    The distribution metadata contains information on the primary author or
    the distribution, or the primary maintainer if the original author is no
    longer involved. It should generally be specified in the form of an
    email address.

    It you don't want to give away a real email address, you should use the
    "CPANID@cpan.org" address you receive automatically when you got your
    PAUSE account.

    The "author" command is used to explicitly set this value.

  author_from
      author_from 'lib/My/Module.pm';

    The "author_from" command retrieves the author from a particular file
    contained in the distribution package. Most often this is done using the
    main module, where Module::Install will read the POD and use whatever it
    can find in the "=head1 AUTHOR" section.

  version
      version '0.01';

    The "version" command is used to specify the version of the
    distribution, as distinct from the version of any single module within
    the distribution.

    Of course, in almost all cases you want it to match the version of the
    primary module within the distribution, which you can do using
    "version_from".

  version_from
      version_from 'lib/My/Module.pm';

    The "version_from" command retrieves the distribution version from a
    particular file contained in the distribution package. Most often this
    is done from the main module.

    "version_from" will look for the first time you set $VERSION and use the
    same value, using a technique consistent with various other module
    version scanning tools.

  license
      license 'perl';

    The "license" command specifies the license for the distribution.

    Most often this value will be 'perl', meaning *"the same as for Perl
    itself"*. Other allowed values include 'gpl', 'lgpl', 'bsd', 'MIT', and
    'artistic'.

    This value is always considered a summary, and it is normal for authors
    to include a LICENSE file in the distribution, containing the full
    license for the distribution.

    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.

  license_from
      license_from 'lib/My/Module.pm';

    The "license_from" command retrieves the distribution license from a
    particular file contained in the distribution package. Most often this
    is done from the main module.

    "license_from" will look inside the POD within the indicated file for a
    licensing or copyright-related section and scan for a variety of strings
    that identify the general class of license.

    At this time it supports only the 6 values mentioned above in the
    "license" command summary.

  perl_version
      perl_version '5.006';

    The "perl_version" command is used to specify the minimum version of the
    perl interpreter your distribution requires.

    When specifying the version, you should try to use the normalized
    version string. Perl version segments are 3 digits long, so a dependency
    on Perl 5.6 will become '5.006' and Perl 5.10.2 will become '5.010002'.

  perl_version_from
      perl_version_from 'lib/My/Module.pm'

    The "perl_version_from" command retrieves the minimum perl interpreter
    version from a particular file contained in the distribution package.
    Most often this is done from the main module.

    The minimum version is detected by scanning the file for "use 5.xxx"
    pragma calls in the module file.

  recommends
      recommends 'Text::CSV_XS' => '0.50'

    The "recommends" command indicates an optional run-time module that
    provides extra functionality. Recommended dependencies are not needed to
    build or test your distribution, but are considered "nice to have".

    As with "requires", the dependency is on a module and not a
    distribution. A version of zero indicates that any version of the module
    is recommended.

  requires
      requires 'List::Util' => 0;
      requires 'LWP'        => '5.69';

    The "requires" command indicates a normal run-time dependency of your
    distribution on another module. Most distributions will have one or more
    of these commands, indicating which CPAN (or otherwise) modules your
    distribution needs.

    A "requires" dependency can be verbalised as *"If you wish to install
    and use this distribution, you must first install these modules first"*.

    Note that the dependency is on a module and not a distribution. This is
    to ensure that your dependency stays correct, even if the module is
    moved or merged into a different distribution, as is occasionally the
    case.

    A dependency on version zero indicates any version of module is
    sufficient. Versions should generally be quoted for clarity.

  test_requires
      test_requires 'Test::More' => '0.47';

    The "test_requires" command indicates a test script dependency for the
    distribution. The specification format is identical to that of the
    "requires" command.

    The "test_requires" command is distinct from the "requires" command in
    that it indicates a module that is needed only during the testing of the
    distribution (often a period of only a few seconds) but will not be
    needed after the distribution is installed.

    The "testrequires" command is used to allow the installer some
    flexibility in how it provides the module, and to allow downstream
    packagers (Debian, FreeBSD, ActivePerl etc) to retain only the
    dependencies needed for run-time operation.

    The "include" command is sometimes used by some authors along with
    "test_requires" to bundle a small well-tested module into the
    distribution package itself rather than inflict yet another module
    installation on users installing from CPAN directly.

  configure_requires
      configure_requires 'File::Spec' => '0.80';

    The "configure_requires" command indicates a configure-time dependency
    for the distribution. The specification format is identical to that of
    the "requires" command.

    The "configure_requires" command is used to get around the conundrum of
    how to use a CPAN module in your Makefile.PL, when you have to load
    Makefile.PL (and thus the CPAN module) in order to know that you need
    it.

    Traditionally, this circular logic could not be broken and so
    Makefile.PL scripts needed to rely on lowest-common-denominator
    approaches, or to bundle those dependencies using something like the
    "include" command.

    The "configure_requires" command creates an entry in the special
    configure_requires: key in the distribution's META.yml file.

    Although most of META.yml is considered advisory only, a CPAN client
    will treat the contents of configure_requires: as authoritative, and
    install the listed modules before it executes the Makefile.PL (from
    which it then determines the other dependencies).

    Please note that support for configure_requires: in CPAN clients is not
    100% complete at time of writing, and still cannot be relied upon.

    Because Module::Install itself only supports 5.005, it will silently add
    the equivalent of a "configure_requires( perl => '5.005' );" command to
    your distribution.

  requires_external_bin
      requires_external_bin 'cvs';

    As part of its role as the dominant "glue" language, a lot of Perl
    modules run commands or programs on the host system.

    The "requires_external_bin" command is used to verify that a particular
    command is available on the host system.

    Unlike a missing Perl module, a missing external binary is unresolvable
    at make-time, and so the Makefile.PL run will abort with a "NA" (Not
    Applicable) result.

    In future, this command will also add additional information to the
    metadata for the dist, so that auto-packagers for particular operating
    system are more-easily able to auto-discover the appropriate non-Perl
    packages needed as a dependency.

  install_script
      # The following are equivalent
      install_script 'script/scriptname'

    The "install_script" command provides support for the installation of
    scripts that will become available at the console on both Unix and
    Windows (in the later case by wrapping it up as a .bat file).

    Note that is it normal practice to not put a .pl on the end of such
    scripts, so that they feel more natural when being used.

    In the example above, the script/scriptname program could be run after
    the installation just by doing the following.

      > scriptname
      Running scriptname 0.01...

      >

    By convention, scripts should be placed in a /script directory within
    your distribution. To support less typing, if a script is located in the
    script directory, you need refer to it by name only.

      # The following are equivalent
      install_script 'foo';
      install_script 'script/foo';

  no_index
      no_index directory => 'examples';
      no_index package   => 'DB';

    Quite often a distribution will provide example scripts or testing
    modules (.pm files) as well as the actual library modules.

    In almost all situations, you do not want these indexed in the CPAN
    index, the master Perl packages list, or displayed on
    <https://metacpan.org/> or <http://search.cpan.org/> websites, you just
    want them along for the ride.

    The "no_index" command is used to indicate directories or files where
    there might be non-library .pm files or other files that the CPAN
    indexer and websites such as <https://metacpan.org/> or
    <http://search.cpan.org/> should explicitly ignore.

    The most common situation is to ignore example or demo directories, but
    a variety of different situations may require a "no_index" entry.

    Another common use for "no_index" is to prevent the PAUSE indexer
    complaining when your module makes changes inside a "package DB" block.
    This is used to interact with the debugger in some specific ways.

    See the META.yml documentation for more details on what "no_index"
    values are allowed.

    The inc, t and share (if "install_share" is used) directories are
    automatically "no_index"'ed for you if found and do not require an
    explicit command.

    To summarize, if you can see it on <https://metacpan.org/> or
    <http://search.cpan.org/> and you shouldn't be able to, you need a
    "no_index" entry to remove it.

  installdirs, install_as_*
      installdirs 'site'; # the default

      install_as_core;    # alias for installdirs 'perl'
      install_as_cpan;    # alias for installdirs 'site'
      install_as_site;    # alias for installdirs 'site'
      install_as_vendor;  # alias for installdirs 'vendor'

    The "installdirs" and "install_as" commands specify the location where
    the module should be installed; this is the equivalent to
    ExtUtils::MakeMaker's "INSTALLDIRS" option. For almost all regular
    modules, the default is recommended, and need not be changed. Dual-life
    (core and CPAN) modules, as well as vendor-specific modules, may need to
    use the other options.

    If unsure, do not use this option.

  WriteAll
    The "WriteAll" command is generally the last command in the file; it
    writes out META.yml and Makefile so the user can run the "make", "make
    test", "make install" install sequence.

EXTENSIONS
    All extensions belong to the Module::Install::* namespace, and inherit
    from Module::Install::Base. There are three categories of extensions:

  Standard Extensions
    Methods defined by a standard extension may be called as plain functions
    inside Makefile.PL; a corresponding singleton object will be spawned
    automatically. Other extensions may also invoke its methods just like
    their own methods:

        # delegates to $other_extension_obj->method_name(@args)
        $self->method_name(@args);

    At the first time an extension's method is invoked, a POD-stripped
    version of it will be included under the inc/Module/Install/ directory,
    and becomes *fixed* -- i.e., even if the user had installed a different
    version of the same extension, the included one will still be used
    instead.

    If the author wish to upgrade extensions in inc/ with installed ones,
    simply run "perl Makefile.PL" again; Module::Install determines whether
    you are an author by the existence of the inc/.author/ directory.
    End-users can reinitialize everything and become the author by typing
    "make realclean" and "perl Makefile.PL".

  Private Extensions
    Those extensions take the form of Module::Install::PRIVATE and
    Module::Install::PRIVATE::*.

    Authors are encouraged to put all existing Makefile.PL magics into such
    extensions (e.g. Module::Install::PRIVATE for common bits;
    Module::Install::PRIVATE::DISTNAME for functions specific to a
    distribution).

    Private extensions should not to be released on CPAN; simply put them
    somewhere in your @INC, under the "Module/Install/" directory, and start
    using their functions in Makefile.PL. Like standard extensions, they
    will never be installed on the end-user's machine, and therefore never
    conflict with other people's private extensions.

  Administrative Extensions
    Extensions under the Module::Install::Admin::* namespace are never
    included with the distribution. Their methods are not directly
    accessible from Makefile.PL or other extensions; they are invoked like
    this:

        # delegates to $other_admin_extension_obj->method_name(@args)
        $self->admin->method_name(@args);

    These methods only take effect during the *initialization* run, when
    inc/ is being populated; they are ignored for end-users. Again, to
    re-initialize everything, just run "perl Makefile.PL" as the author.

    Scripts (usually one-liners in Makefile) that wish to dispatch AUTOLOAD
    functions into administrative extensions (instead of standard
    extensions) should use the Module::Install::Admin module directly. See
    Module::Install::Admin for details.

EXTENSIONS
    Detailed information is provided for all (some) of the relevant modules
    via their own POD documentation.

  Module::Install::AutoInstall
    Provides "auto_install()" to automatically fetch and install
    prerequisites.

  Module::Install::Base
    The base class for all extensions

  Module::Install::Bundle
    Provides the "bundle" family of commands, allowing you to bundle another
    CPAN distribution within your distribution.

  Module::Install::Fetch
    Handles install-time fetching of files from remote servers via FTP and
    HTTP.

  Module::Install::Include
    Provides the "include" family of commands for embedding modules that are
    only need at build-time in your distribution and won't be installed.

  Module::Install::Inline
    Provides "&Inline->write" to replace Inline::MakeMaker's functionality
    for making Inline-based modules (and cleaning up).

    However, you should invoke this with "WriteAll( inline => 1 )".

  Module::Install::Makefile
    Provides "&Makefile->write" to generate a Makefile for you distribution.

  Module::Install::Metadata
    Provides "&Meta->write" to generate a META.yml file for your
    distribution.

  Module::Install::PAR
    Makes pre-compiled module binary packages from the built blib directory,
    and download existing ones to save recompiling.

  Module::Install::Run
    Determines if commands are available on the user's machine, and runs
    them via IPC::Run3.

  Module::Install::Scripts
    Handles packaging and installation of scripts to various bin dirs.

  Module::Install::Win32
    Functions for installing modules on Win32 and finding/installing
    nmake.exe for users that need it.

  Module::Install::WriteAll
    Provides the "WriteAll", which writes all the requires files, such as
    META.yml and Makefile.

    "WriteAll" takes four optional named parameters:

    "check_nmake" (defaults to true)
        If true, invokes functions with the same name.

        *The use of this param is no longer recommended.*

    "inline" (defaults to false)
        If true, invokes "&Inline->write" Inline modules.

    "meta" (defaults to true)
        If true, writes a "META.yml" file.

    "sign" (defaults to false)
        If true, invokes "sign" command to digitally sign erm... something.

  Module::Install::Admin::Find
    Package-time functions for finding extensions, installed packages and
    files in subdirectories.

  Module::Install::Admin::Manifest
    Package-time functions for manipulating and updating the MANIFEST file.

  Module::Install::Admin::Metadata
    Package-time functions for manipulating and updating the META.yml file.

  Module::Install::Admin::ScanDeps
    Package-time scanning for non-core dependencies via Module::ScanDeps and
    Module::CoreList.

FAQ
  What are the benefits of using Module::Install?
    Here is a brief overview of the reasons:

    *   Extremely easy for beginners to learn

    *   Does everything ExtUtils::MakeMaker does.

    *   Does it with a dramatically simpler syntax.

    *   Automatically scans for metadata for you.

    *   Requires no installation for end-users.

    *   Guaranteed forward-compatibility.

    *   Automatically updates your MANIFEST.

    *   Distributing scripts is easy.

    *   Include prerequisite modules (less dependencies to install)

    *   Auto-installation of prerequisites.

    *   Support for Inline-based modules.

    *   Support for File::ShareDir shared data files

    *   Support for precompiled PAR binaries.

    *   Deals with Win32 install issues for you.

    By greatly shrinking and simplifying the syntax, Module::Install keeps
    the amount of work required to maintain your Makefile.PL files to an
    absolute minimum.

    And if you maintain more than one module than needs to do unusual
    installation tricks, you can create a specific module to abstract away
    this complexity.

  Module::Install isn't at 1.00 yet, is it safe to use yet?
    As long as you are going to periodically do incremental releases to get
    any bug fixes and new functionality, yes.

    If you don't plan to do incremental releases, it might be a good idea to
    continue to wait for a while.

COOKBOOK / EXAMPLES
    The following are some real-life examples of Makefile.PL files using
    Module::Install.

  Method::Alias
    Method::Alias is a trivially-small utility module, with almost the
    smallest possible Makefile.PL.

      use inc::Module::Install;

      name          'Method-Alias';
      all_from      'lib/Method/Alias.pm';
      test_requires 'Test::More' => '0.42';

  File::HomeDir
    File::HomeDir locates your home directory on any platform. It needs an
    installer that can handle different dependencies on different platforms.

      use inc::Module::Install;

      name          'File-HomeDir';
      all_from      'lib/File/HomeDir.pm';
      requires      'File::Spec' => '0.80';
      test_requires 'Test::More' => '0.47';

      if ( $MacPerl::Version ) {
          # Needed on legacy Mac OS 9
          requires 'Mac::Files' => 0;
      }

      if ( $^O eq 'MXWin32' ) {
          # Needed on Windows platforms
          requires 'Win32::TieRegistry' => 0;
      }

      WriteAll;

TO DO
    Implement Module::Install::Compiled and Module::Install::Admin::Compiled
    to integrate the Module::Compiled "perl 6 to perl 5" functionality with
    Module::Install. Because this would add SIGNIFICANT dependencies (i.e.
    pugs!) this should almost certainly be distributed as a separate
    distribution.

    Go over POD docs in detail.

    Test recursive Makefile directories

    The test suite needs a great deal more test scripts.

    Dependencies on shared libraries (libxml/libxml.dll etc) and binary
    files so that debian/Win32/etc autopackaging applications can create the
    appropriate package-level dependencies there.

    EU::MM 6.06_03+ supports META.yml natively. Maybe probe for that?

SEE ALSO
    Module::Install::Philosophy

    inc::Module::Install

    Module::Install::AutoInstall

    Module::Install::Base

    Module::Install::Bundle

    Module::Install::MakeMaker

    Module::Install::Share

    Module::Install::Admin

    Module::Install::Admin::Include

    Module::Install::Admin::Manifest

    CPAN::MakeMaker, Inline::MakeMaker

    ExtUtils::MakeMaker

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Install>

    For other issues, contact the (topmost) author.

AUTHORS
    Adam Kennedy <adamk@cpan.org>

    Audrey Tang <autrijus@autrijus.org>

    Brian Ingerson <ingy@cpan.org>

COPYRIGHT
    Copyright 2002 - 2012 Brian Ingerson, Audrey Tang and Adam Kennedy.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.