=pod

=head1 NAME

Module::Install - Standalone, extensible Perl module installer

=head1 VERSION

This document describes version 0.45 of Module::Install, released
December 16, 2005.

=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
    all_from        'lib/Your/Module.pm';

    # Modules that this distribution depend on
    requires        'Carp';
    requires        'File::Spec' => '0.80';

    # Modules needed for building and testing
    build_requires  'Test::More' => '0.42';

    # Optional module dependencies
    recommends      'Your::OtherModule' => '0.01';
    
    # Auto-installs all dependencies from CPAN.
    # You want to use this most of the time, especially
    # if you use the 'recommend' or 'feature' commands
    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 COMMANDS

The following are the most common commands available for use in an
installer.

=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';

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.

=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';

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)

=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';

The C<author_from> command retrievs 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 WriteAll

The C<WriteAll> command is generally the last command; it writes out
F<META.yml> and F<Makefile> so the user can type C<make install>.

=head1 EXTENSIONS

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

=over 4

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

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

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

=back

B<Module::Install> comes with several standard extensions:

=over 4

=item Module::Install::AutoInstall

Provides C<auto_install()> to automatically fetch and install
prerequisites via B<CPANPLUS.pm> or B<CPAN.pm>, specified either by
the C<features> metadata or by method arguments. 

=item Module::Install::Base

The base class of all extensions, providing C<new>, C<initialized>,
C<admin>, C<load> and the C<AUTOLOAD> dispatcher.

=item Module::Install::Build

Provides C<&Build-E<gt>write> to generate a B<Module::Build> compliant
F<Build> file, as well as other B<Module::Build> support functions.

=item Module::Install::Bundle

Provides C<bundle>, C<bundle_deps> and C<bundle_all>, allowing you
to bundle a CPAN distribution within your distribution.  When your
end-users install your distribution, the bundled distribution will be
installed along with yours, unless a newer version of the bundled
distribution already exists on their local filesystem.

=item Module::Install::Fetch

Handles fetching files from remote servers via FTP and HTTP.

=item Module::Install::Include

Provides the C<include($pkg)> function to include pod-stripped
package(s) from C<@INC> to F<inc/>, and the C<auto_include()>
function to include all modules specified in C<build_requires>,

Also provides the C<include_deps($pkg)> function to include every
non-core modules needed by C<$pkg>, and the C<auto_include_deps()>
function that does the same thing as C<auto_include()>, plus all
recursive dependencies that are subsequently required by modules in
C<build_requires>.

=item Module::Install::Inline

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

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

=item Module::Install::MakeMaker

Simple wrapper class for C<ExtUtils::MakeMaker::WriteMakefile>.

=item Module::Install::Makefile

Provides C<&Makefile-E<gt>write> to generate a B<ExtUtils::MakeMaker>
compliant F<Makefile>; preferred over B<Module::Install::MakeMaker>.
It adds several extra C<make> targets, as well as being more intelligent
at guessing unspecified arguments.

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

Guess the distribution name.

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

Guess the distribution version.

=item Module::Install::Metadata

Provides C<&Meta-E<gt>write> to generate a B<YAML>-compliant F<META.yml>
file, and C<&Meta-E<gt>read> to parse it for C<&Makefile>, C<&Build> and
C<&AutoInstall> to use.

=item Module::Install::PAR

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

=item Module::Install::Run

Determines if a command is available on the user's machine, and run
external commands via B<IPC::Run3>.

=item Module::Install::Scripts

Handles packaging and installation of scripts, instead of modules.

=item Module::Install::Win32

Functions related for installing modules on Win32, e.g. automatically
fetching and installing F<nmake.exe> for users that need it.

=item Module::Install::WriteAll

This extension offers C<WriteAll>, which writes F<META.yml> and
either F<Makefile> or F<Build> depending on the name of the invoked
program.

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> instead of C<&Makefile-E<gt>write>.

=item C<meta> (defaults to true)

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

=item C<sign> (defaults to false)

If true, invokes functions with the same name.

=back

=back

B<Module::Install> also comes with several administrative extensions:

=over

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

Functions for finding extensions, installed packages and files in
subdirectories.

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

Functions for manipulating and updating the F<MANIFEST> file.

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

Functions for manipulating and updating the F<META.yml> file.

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

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

=back

Please consult their own POD documentations for detailed information.

=head1 METHODS

=over 4

=item import(@args)

If this module was not loaded from F<inc/>, calls the C<init>
method of B<Module::Install::Admin> to include and reload itself;
see L<Module::Install::Admin/Bootstrapping> for details.

Otherwise, export a default C<AUTOLOAD> handler to the caller's package.

The C<@args> array is passed to C<new> to intialize the top-level
B<Module::Install> object; it should usually be left empty.

=item autoload()

Returns an AUTOLOAD handler bound to the caller package.

=back

=item new(%args)

Constructor, taking a hash of named arguments.  Usually you do not want
change any of them.

=item call($method, @args)

Call an extension method, passing C<@args> to it.

=item load($method)

Include and load an extension object implementing C<$method>.

=item load_extensions($path, $top_obj)

Loads all extensions under C<$path>; for each extension, create a
singleton object with C<_top> pointing to C<$top_obj>, and populates the
arrayref C<$self-E<gt>{extensions}> with those objects.

=item load_extensions($path)

Returns an array of C<[ $file_name, $package_name ]> for each extension
module found under C<$path> and its subdirectories.

=head1 FAQ

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

Here is a brief overview of the reasons:

    Does everything ExtUtils::MakeMaker does.
    
    Requires no installation for end-users.
    
    Generate stock Makefile.PL for Module::Build users.
    
    Guaranteed forward-compatibility.
    
    Automatically updates your MANIFEST.
    
    Distributing scripts is easy.
    
    Include prerequisite modules (even the entire dependency tree).
    
    Auto-installation of prerequisites.
    
    Support for Inline-based modules.
    
    Support for precompiled PAR binaries.

Besides, if you maintain more than one CPAN modules, chances are there
are duplications in their F<Makefile.PL>, and also with other CPAN module
you copied the code from.  B<Module::Install> makes it really easy for you
to abstract away such codes; see the next question.

=head2 How is this different from its predecessor, B<CPAN::MakeMaker>?

According to Brian Ingerson, the author of B<CPAN::MakeMaker>,
their difference is that I<Module::Install is sane>.

Also, this module is not self-modifying, and offers a clear separation
between standard, private and administrative extensions.  Therefore
writing extensions for B<Module::Install> is easier -- instead of
tweaking your local copy of C<CPAN/MakeMaker.pm>, just make your own
B<Modula::Install::PRIVATE> module, or a new B<Module::Install::*>
extension.

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

=head1 COPYRIGHT

Copyright 2002, 2003, 2004, 2005 by
    Adam Kennedy E<lt>cpan@ali.asE<gt>
    Audrey Tang E<lt>autrijus@autrijus.orgE<gt>,
    Brian Ingerson E<lt>ingy@cpan.orgE<gt>.

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
