NAME
Module::Install - Standalone, extensible Perl module installer
VERSION
This document describes version 0.19_97 of Module::Install, released May 8, 2003.
THIS IS A PRE-ALPHA SNAPSHOT RELEASE. THE INTERFACE IS SUBJECT TO CHANGE, AND IS LIKELY TO BE BUGGY. USE IT AT YOUR OWN RISK.
SYNOPSIS
In your Makefile.PL:
# drop-in replacement to ExtUtils::MakeMaker!
use inc::Module::Install;
WriteMakefile(); # leave it empty to determine automatically
Standard usage:
use inc::Module::Install;
name('Your-Module');
abstract('Some Abstract here');
author('Your Name <email@example.com>');
license('perl');
include_deps('Test::More', 5.004);
requires('Test::More');
recommends('Acme::ComeFrom', 0.01);
check_nmake(); # check and download nmake.exe for Win32
&Makefile->write;
Or rename it to Build.PL; just change the last line to:
&Build->generate_makefile_pl;
&Build->write;
You can also put all setting into META.yml, and use this instead:
use inc::Module::Install;
&Meta->read; # parses META.yml
&AutoInstall->run; # auto-install dependencies from CPAN
&Makefile->write; # generates Makefile
# &Build->write; # generates ./Build if desired
DESCRIPTION
This module provides a drop-in replacement for ExtUtils::MakeMaker. If you want to start working with real-world examples right away, check out Module::Install-Cookbook. For some personal opinions behind this module's making, see Module::Install-Philosophy.
It is designed to let module authors eliminate all duplicated codes in Makefile.PL and Build.PL, by abstracting them into extensions, and distribute them under the inc/ directory.
To start using it, just replace the use ExtUtils::MakeMaker;
line from Makefile.PL with use inc::Module::Install;
, then run it once:
% perl Makefile.PL
include inc/Module/Install.pm
include inc/Module/Install/MakeMaker.pm
include inc/Module/Install/Base.pm
Updating your MANIFEST file:
Adding inc/Module/Install.pm
Adding inc/Module/Install/Base.pm
Adding inc/Module/Install/MakeMaker.pm
Now your distribution will have an extra inc/ directory, with the minimal loader code inc/Module/Install.pm copied into it. Also, since you made use of the WriteMakefile
function, the Module::Install::MakeMaker extension is also copied into inc/, along with the base extension class Module::Install::Base.
End-users of your distribution do not need to install anything extra; the distribution already includes all necessary extensions, with their POD documentations removed. Note that because it does not include unused extensions or Module::Install itself, the impact on distribution size is minimized.
METHODS
- import(@args)
-
If this module was not loaded from inc/, calls the
init
method of Module::Install::Admin to include and reload itself; see "Bootstrapping" in Module::Install::Admin for details.Otherwise, export a default
AUTOLOAD
handler to the caller's package.The
@args
array is passed tonew
to intialize the top-level Module::Install object; it should usually be left empty. - autoload()
-
Returns an AUTOLOAD handler bound to the caller package.
- new(%args)
-
Constructor, taking a hash of named arguments. Usually you do not want change any of them.
- call($method, @args)
-
Call an extension method, passing
@args
to it. - load($method)
-
Include and load an extension object implementing
$method
. - load_extensions($path, $top_obj)
-
Loads all extensions under
$path
; for each extension, create a singleton object with_top
pointing to$top_obj
, and populates the arrayref$self->{extensions}
with those objects. - load_extensions($path)
-
Returns an array of
[ $file_name, $package_name ]
for each extension module found under$path
and its subdirectories.
EXTENSIONS
All extensions belong to the Module::Install::* namespace, and inherits from Module::Install::Base. There are three kinds of them:
- Standard Extensions
-
Methods defined by a standard extension may be called as plain functions inside Makefile.PL; a corresponding 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 installs a different version of the same extension, the included one will still be used instead.
If you wish to upgrade extensions in inc/ with installed ones, simply remove the inc/ directory and run
perl Makefile.PL
again. Alternatively, typingmake reset
will also do this for you. - 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::PAR for functions specific to a distribution).
Private extensions need not to be released on CPAN; simply put them somewhere in your
@INC
, under theModule/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, remove the inc/ directory via
make reset
and runperl Makefile.PL
.Scripts (usually one-liners stored as part of 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.
Module::Install comes with several standard extensions:
- Module::Install::AutoInstall
-
Provides
auto_install()
to automatically fetch and install prerequisites via CPANPLUS or CPAN, specified either by thefeatures
metadata or by method arguments.You may wish to add a
include('ExtUtils::AutoInstall');
beforeauto_install()
to include ExtUtils::AutoInstall with your distribution. Otherwise, this extension will attempt to automatically install it from CPAN. - Module::Install::Base
-
The base class of all extensions, providing
new
,initialized
,admin
,load
and theAUTOLOAD
dispatcher. - Module::Install::Build
-
Provides
&Build->write
to generate a Module::Build compliant Build file, as well as other Module::Build support functions. - Module::Install::Fetch
-
Handles fetching files from remote servers via FTP.
- Module::Install::Include
-
Provides the
include($pkg)
function to include pod-stripped package(s) from@INC
to inc/.Also provides the
include_deps($pkg, $base_perl_version)
function to include every non-core modules needed by$pkg
, as of Perl version$base_perl_version
. - Module::Install::Inline
-
Provides
&Inline->write
to replace Inline::MakeMaker's functionality of making (and cleaning after) Inline-based modules. - Module::Install::MakeMaker
-
Simple wrapper class for
ExtUtils::MakeMaker::WriteMakefile
. - Module::Install::Makefile
-
Provides
&Makefile->write
to generate a ExtUtils::MakeMaker compliant Makefile; preferred over Module::Install::MakeMaker. It adds several extramake
targets, as well as being more intelligent at guessing unspecified arguments. - Module::Install::Makefile::Name
-
Guess the distribution name.
- Module::Install::Makefile::Version
-
Guess the distribution version.
- Module::Install::Metadata
-
Provides
&Meta->write
to generate a YAML-compliant META.yml file, and&Meta->read
to parse it for&Makefile
,&Build
and&AutoInstall
to use. - Module::Install::PAR
-
Makes pre-compiled module binary packages from blib, and download existing ones to save the user from recompiling.
- Module::Install::Run
-
Determines if a command is available on the user's machine, and run external commands via IPC::Run3.
- Module::Install::Scripts
-
Handles packaging and installation of scripts, instead of modules.
- Module::Install::Win32
-
Functions related for installing modules on Win32, e.g. automatically fetching and installing nmake.exe for users that need it.
Module::Install also comes with several administrative extensions:
- Module::Install::Admin::Find
-
Functions for finding extensions, installed packages and files in subdirectories.
- Module::Install::Admin::Manifest
-
Functions for manipulating and updating the MANIFEST file.
- Module::Install::Admin::Metadata
-
Functions for manipulating and updating the META.yml file.
- Module::Install::Admin::ScanDeps
-
Handles scanning for non-core dependencies via Module::ScanDeps and Module::CoreList.
Please consult their own POD documentations for detailed information.
FAQ
What are the benefits of using 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::C.
Support for precompiled binaries.
Besides, if you author more than one CPAN modules, chances are there are duplicated in their Makefile.PL or with some other CPAN module you copied the code from. Module::Install makes it really easy for you to abstract away such codes; see next question.
How is this different from its predecessor, CPAN::MakeMaker?
According to Brian Ingerson, the author of CPAN::MakeMaker, their difference is that 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 Module::Install is easier -- instead of tweaking your local copy of CPAN/MakeMaker.pm
, just make a new Module::Install::* module.
SEE ALSO
Module::Install-Cookbook, Module::Install-Philosophy, inc::Module::Install
Module::Install::AutoInstall, Module::Install::Base, Module::Install::Build, Module::Install::Directives, Module::Install::Fetch, Module::Install::Include, Module::Install::MakeMaker, Module::Install::Makefile, Module::Install::Makefile::CleanFiles, Module::Install::Makefile::Name, Module::Install::Makefile::Version, Module::Install::Metadata, Module::Install::PAR, Module::Install::Run, Module::Install::Scripts, Module::Install::Win32
Module::Install::Admin, Module::Install::Admin::Find, Module::Install::Admin::Manifest, Module::Install::Admin::Metadata, Module::Install::Admin::ScanDeps
CPAN::MakeMaker, Inline::MakeMaker, ExtUtils::MakeMaker, Module::Build
AUTHORS
Brian Ingerson <INGY@cpan.org>, Autrijus Tang <autrijus@autrijus.org>
COPYRIGHT
Copyright 2003 by Autrijus Tang <autrijus@autrijus.org>, Brian Ingerson <INGY@cpan.org>.
Copyright 2002 by Brian Ingerson <INGY@cpan.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.