=pod

=head1 NAME

Module::Install - Standalone, extensible Perl module installer

=head1 VERSION

This document describes version 0.54 of Module::Install, released
January 11, 2006.

=head1 SYNOPSIS

In your F<Makefile.PL>: (Recommended Usage)

    # Load the Module::Install bundled in ./inc/
    use inc::Module::Install;
    
    # Name of your distribution
    name            'Your-Module';
    
    # Get most of the details from the primary module
    # (The filename argument below is optional if it is placed
    # consistently with the "name" above.)
    all_from        'lib/Your/Module.pm';
    
    requires        'Carp'              => 0;
    requires        'File::Spec'        => '0.80';
    
    build_requires  'Test::More'        => '0.42';
    
    recommends      'Your::OtherModule' => '0.01';
    
    # Do not index our example modules
    no_index        directory           => 'demos';
    
    # Auto-install all dependencies from CPAN
    auto_install;
    
    # Generate the Makefile
    WriteAll;

Quickly upgrade a legacy L<ExtUtil::MakeMaker> installer:

    # Drop-in replacement to ExtUtils::MakeMaker
    use inc::Module::Install;
    WriteMakefile( ... );

A dummy F<Build.PL> so we can work with L<Module::Build> as well:

    # Dear Distribution Packager. This use of require is intentional. 
    # Module::Install detects Build.PL usage and acts accordingly.
    require 'Makefile.PL';

=head1 DESCRIPTION

B<Module::Install> is a package for writing installers for CPAN distributions
that are clean, simple and minimalistic, act in a strictly correct manner
with B<both> the L<ExtUtils::MakeMaker> and L<Module::Build> build systems,
and run on any Perl installation version 5.004 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.

=head2 Writing Module::Install Installers

The quickest way to get started with Module::Install is simply to cut
and paste the L</SYNOPSIS> from above and create your F<Makefile.PL>
using it, when modify the file to suit your particular case using the
list of commands documented in L</COMMANDS> below.

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

=head1 How it Works

The motivation behind B<Module::Install> is that distributions need
to interact with a large number of different versions of Perl module
installers (primarily L<CPAN.pm>, L<CPANPLUS.pm>, L<ExtUtils::MakeMaker>
and L<Module::Build>) which have B<greatly> varying feature and bug
profiles.

For example, the L<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 your code, B<Module::Install>
will copy part of itself into each module distribution it creates.

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

=head2 History

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

For more information, see Brian's I<Creating Module Distributions with
Module::Install> in June 2003 issue of The Perl Journal
(L<http://www.tpj.com/issues/>).

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

=head1 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.

=head2 name

  name 'My-Module';

The B<name> command is a compulsory (and generally the first) command.

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

=head2 all_from

  all_from 'lib/My/Module.pm';

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

C<all_from> is equivalent to C<abstract_from> + C<author_from> +
C<version_from> + C<license_from> + C<perl_version_from>.

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

=head2 abstract

  abstract 'This distribution does something';

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

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

=head2 abstract_from

  abstract_from 'lib/My/Module.pm';

The C<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 it will read the POD and use whatever
is in the C<=head1 NAME> section (with module name removed as needed)

C<abstract_from> is set as part of C<all_from>.

=head2 author

  author 'Adam Kennedy <cpan@ali.as>';

The distribution metadata contains information on the author of the
primary author/maintainer of the distribution, in the form of an
email address.

The C<author> command is used to explicitly set this value.

=head2 author_from

  author_from 'lib/My/Module.pm';

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

=head2 version

  version '0.01';

The C<version> command is used to specify the version of the
distribution, as distinct from the version of any 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
C<version_from>.

=head2 version_from

  version_from 'lib/My/Module.pm';

The C<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.

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

=head2 license

  license 'perl';
  
The C<license> command specifies the license for the distribution.

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

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

=head2 license_from

  license_from 'lib/My/Module.pm';

The C<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.

C<license_from> will look inside the POD within the 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 5 values mentioned above in the
C<license> command summary.

=head2 perl_version

  perl_version '5.006';

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

=head2 perl_version_from

  perl_version_from 'lib/My/Module.pm'

The C<perl_version_from> command retrieves the minimum F<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 C<use 5.xxx>
pragma calls in the module file.

=head2 requires

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

The C<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 C<requires> dependency can be verbalised as I<"If you wish to install
and use this distribution, you must first install these modules first">.

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

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

=head2 build_requires

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

The C<build_requires> command indicates a build-time dependency for
the distribution. The specification format is identical to that of
the C<requires> command.

The C<build_requires> command is distinct from the C<requires> command
in that it indicates a module that is need B<only> during the building
and testing of the distribution (often a period of only a few seconds)
but will B<not> be needed after the distribution is installed.

The most common case by far is for testing modules to be specified
this way.

The C<build_requires> command is used to allow the installer some
flexibility in how it provides the module.

For example, the C<include> command is sometimes used to bundle a
small testing module into the distribution package itself rather than
inflict another module installation on the user.

In addition, when building a binary operating system packages (such as
Debian .deb packages) from a CPAN distribution, the testing is done once
by the packager, and so the C<build_requires> dependency can be safely
ignored by the binary package.

=head2 no_index

  no_index directory => 'examples';

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

In almost all situations, you do B<not> want these indexed in the master
Perl packages list, you just want them along for the ride.

The C<no_index> command is used to indicate locations where there might
be non-library .pm files that the CPAN indexer and websites such as
L<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 C<no_index> entry.

The F<inc> and F<t> directories are automatically C<no_index>'ed for
you and do not require a command.

=head2 WriteAll

The C<WriteAll> command is generally the last command; it writes out
F<META.yml> and F<Makefile> (or F<Build>) so the user can run the
C<make>, C<make test>, C<make install> process. (or the F<Build.PL>
equivalents).

=head1 EXTENSIONS

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

=head2 Standard Extensions

Methods defined by a standard extension may be called as plain functions
inside F<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 F<inc/Module/Install/>
directory, and becomes I<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 F<inc/> with installed ones,
simply run C<perl Makefile.PL> again; B<Module::Install> determines
whether you are an author by the existence of the F<inc/.author/>
directory.  End-users can reinitialize everything and become the author
by typing C<make realclean> and C<perl Makefile.PL>.

=head2 Private Extensions

Those extensions take the form of B<Module::Install::PRIVATE> and
B<Module::Install::PRIVATE::*>.

Authors are encouraged to put all existing F<Makefile.PL> magics into
such extensions (e.g. F<Module::Install::PRIVATE> for common bits;
F<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 C<@INC>, under the C<Module/Install/> directory, and
start using their functions in F<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.

=head2 Administrative Extensions

Extensions under the B<Module::Install::Admin::*> namespace are never
included with the distribution.  Their methods are not directly
accessible from F<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 I<initialization> run, when
F<inc/> is being populated; they are ignored for end-users.  Again,
to re-initialize everything, just run C<perl Makefile.PL> as the author.

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

=head2 Extention List

=over 4

=item Module::Install::AutoInstall

Provides C<auto_install()> to automatically fetch and install
prerequisites.

=item Module::Install::Base

The base class for all extensions

=item Module::Install::Build

Provides integration with L<Module::Build> via C<&Build-E<gt>write>.

=item Module::Install::Bundle

Provides the C<bundle> family of commands, allowing you to bundle
another CPAN distribution within your distribution.

=item Module::Install::Fetch

Handles install-time fetching of files from remote servers via
FTP and HTTP.

=item Module::Install::Include

Provides the C<include> family of commands for embedding modules
that are only need at build-time in your distribution and won't
be installed.

=item Module::Install::Inline

Provides C<&Inline-E<gt>write> to replace B<Inline::MakeMaker>'s
functionality for making B<Inline>-based modules (and cleaning up).

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

=item Module::Install::Makefile

Provides C<&Makefile-E<gt>write> to generate a F<Makefile> for you
distribution.

=item Module::Install::Makefile::Name

Guessing the distribution name.

=item Module::Install::Makefile::Version

Guessing the distribution version.

=item Module::Install::Metadata

Provides C<&Meta-E<gt>write> to generate a F<META.yml> file for your
distribution.

=item Module::Install::PAR

Makes pre-compiled module binary packages from the built F<blib>
directory, and download existing ones to save recompiling.

=item Module::Install::Run

Determines if commands are available on the user's machine, and runs
them via B<IPC::Run3>.

=item Module::Install::Scripts

Handles packaging and installation of scripts to various bin dirs.

=item Module::Install::Win32

Functions for installing modules on Win32 and finding/installing
F<nmake.exe> for users that need it.

=item Module::Install::WriteAll

Provides the C<WriteAll>, which writes all the requires files,
such as F<META.yml> and either F<Makefile> or F<Build>.

C<WriteAll> takes four optional named parameters:

=over 4

=item C<check_nmake> (defaults to true)

If true, invokes functions with the same name.

=item C<inline> (defaults to false)

If true, invokes C<&Inline-E<gt>write> L<Inline> modules.

=item C<meta> (defaults to true)

If true, writes a C<META.yml> file.

=item C<sign> (defaults to false)

If true, invokes C<sign> command to digitally sign erm... something.

=back

=item Module::Install::Admin::Find

Package-time functions for finding extensions, installed packages
and files in subdirectories.

=item Module::Install::Admin::Manifest

Package-time functions for manipulating and updating the
F<MANIFEST> file.

=item Module::Install::Admin::Metadata

Package-time functions for manipulating and updating the
F<META.yml> file.

=item Module::Install::Admin::ScanDeps

Package-time scanning for non-core dependencies via B<Module::ScanDeps>
and B<Module::CoreList>.

=back

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

=head1 FAQ

=head2 What are the benefits of using B<Module::Install>?

Here is a brief overview of the reasons:

=over 4

=item * Extremely easy to beginners to learn

=item * Does everything ExtUtils::MakeMaker does.

=item * Does it with a dramatically simpler syntax.

=item * Automatically scans for metadata for you.

=item * Requires no installation for end-users.

=item * Generate stock Makefile.PL for Module::Build users.

=item * Guaranteed forward-compatibility.

=item * Automatically updates your MANIFEST.

=item * Distributing scripts is easy.

=item * Include prerequisite modules (less dependencies to install)

=item * Auto-installation of prerequisites.

=item * Support for Inline-based modules.

=item * Support for File::ShareDir shared data files

=item * Support for precompiled PAR binaries.

=item * Deals with Win32 install issues for you.

=cut

By greatly shrinking and simplifying the syntax B<Module::Install>
keeps the amount of work required to maintain your F<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.

=head1 COOKBOOK / EXAMPLES

The following are some real-life examples of F<Makefile.PL> files
using B<Module::Install>.

=head2 Method::Alias

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

  use inc::Module::Install;
  name           'Method-Alias';
  all_from       'lib/Method/Alias.pm';
  build_requires 'Test::More' => '0.42';

=head2 File::HomeDir

L<File::HomeDir> locates your home directorie on any platform. It needs
an installed 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';
  build_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;
  }
  
  auto_install;
  WriteAll;

=head1 SEE ALSO

L<Module::Install-Philosophy>

L<inc::Module::Install>

L<Module::Install::AutoInstall>

L<Module::Install::Base>

L<Module::Install::Bundle>

L<Module::Install::Build>

L<Module::Install::Directives>

L<Module::Install::Fetch>

L<Module::Install::Include>

L<Module::Install::MakeMaker>

L<Module::Install::Makefile>

L<Module::Install::Makefile::CleanFiles>

L<Module::Install::Makefile::Name>

L<Module::Install::Makefile::Version>

L<Module::Install::Metadata>

L<Module::Install::PAR>

L<Module::Install::Run>

L<Module::Install::Scripts>

L<Module::Install::Win32>

L<Module::Install::WriteAll>

L<Module::Install::Admin>

L<Module::Install::Admin::Bundle>

L<Module::Install::Admin::Find>

L<Module::Install::Admin::Include>

L<Module::Install::Admin::Makefile>

L<Module::Install::Admin::Manifest>

L<Module::Install::Admin::Metadata>

L<Module::Install::Admin::ScanDeps>

L<Module::Install::Admin::WriteAll>

L<CPAN::MakeMaker>, L<Inline::MakeMaker>

L<ExtUtils::MakeMaker>, L<Module::Build>

=head1 AUTHORS

Brian Ingerson E<lt>INGY@cpan.orgE<gt>

Audrey Tang E<lt>autrijus@autrijus.orgE<gt>

Adam Kennedy E<lt>cpan@ali.asE<gt>

=head1 COPYRIGHT

Copyright 2002, 2003, 2004, 2005, 2006 by
Brian Ingerson, Audrey Tang, Adam Kennedy.

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

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut
