=pod =head1 NAME Module::Install - Standalone, extensible Perl module installer =head1 SYNOPSIS In your F: (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 L installer: use inc::Module::Install; WriteMakefile( ... ); =head1 WARNING Please note that while B pioneered many great ideas in its time, its primary benefits have been better achieved by the authoring tool L, and its spinoffs L and L. These tools allow the author to build and maintain distributions with DWIM convenience, while the distribution is installed directly by L or similar installation tools, avoiding the complexity of bundling the installer. L additionally has a more robust plugin system which makes it easier to keep up with changes to the L and add other new functionality. Use of B for new distributions is therefore discouraged by the maintainers. =head1 DESCRIPTION B is a package for writing installers for CPAN (or CPAN-like) distributions that are clean, simple, minimalist, act in a strictly correct manner with L, 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. =head2 Writing Module::Install Installers The quickest way to get started with Module::Install is to copy the L from above and save it as your own F. Then modify the file to suit your own particular case, using the list of commands documented in L 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. =head1 How it Works The motivation behind B is that distributions need to interact with a large number of different versions of L and module installers infrastructure, primarily L.pm, L.pm, L and L. These have accumulated B 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 L.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, B 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. =head2 History This module was originally written by Brian Ingerson as a smart drop-in replacement for L. For more information, see Brian's I in June 2003 issue of The Perl Journal (L) For a B more information, and some personal opinions on the module and its creation, see L. =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 command is compulsory command, generally the first. It provides the name of your distribution, which for a module like B would normally be C. 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 L modules come in a distribution called C. =head2 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 B command, which will try to extract as much metadata as possible from the Perl code and POD in that primary module. Functionally, C is equivalent to C + C + C + C + C. See below for details. If any of these values are set already B C is used, they will kept and B be overwritten. =head2 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 C command is used to explicitly set the abstract for the distribution, at least as far as the metadata file for the distribution is concerned. =head2 abstract_from abstract_from 'lib/My/Module.pm'; The C command retrieves the abstract from a particular file contained in the distribution package. Most often this is done from the main module, where C will read the POD and use whatever is in the C<=head1 NAME> section (with module name stripped if needed) C is set as part of C. =head2 author author 'Adam Kennedy '; 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 C address you receive automatically when you got your PAUSE account. The C command is used to explicitly set this value. =head2 author_from author_from 'lib/My/Module.pm'; The C command retrieves the author from a particular file contained in the distribution package. Most often this is done using the main module, where L will read the POD and use whatever it can find in the C<=head1 AUTHOR> section. =head2 version version '0.01'; The C 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 C. =head2 version_from version_from 'lib/My/Module.pm'; The C command retrieves the distribution version from a particular file contained in the distribution package. Most often this is done from the main module. C will look for the first time you set C<$VERSION> and use the same value, using a technique consistent with various other module version scanning tools. =head2 license license 'perl'; The C 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'>, C<'MIT'>, and C<'artistic'>. This value is always considered a summary, and it is normal for authors to include a F 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 B be an OSI-approved open source license. Commercial software is not permitted on the CPAN. =head2 license_from license_from 'lib/My/Module.pm'; The C command retrieves the distribution license from a particular file contained in the distribution package. Most often this is done from the main module. C 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 C command summary. =head2 perl_version perl_version '5.006'; The C 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 C<'5.006'> and Perl 5.10.2 will become C<'5.010002'>. =head2 perl_version_from perl_version_from 'lib/My/Module.pm' The C command retrieves the minimum F 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 pragma calls in the module file. =head2 recommends recommends 'Text::CSV_XS' => '0.50' The C 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 L, the dependency is on a B and not a distribution. A version of zero indicates that any version of the module is recommended. =head2 requires requires 'List::Util' => 0; requires 'LWP' => '5.69'; The C 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 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 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 B version of module is sufficient. Versions should generally be quoted for clarity. =head2 test_requires test_requires 'Test::More' => '0.47'; The C command indicates a test script dependency for the distribution. The specification format is identical to that of the C command. The C command is distinct from the C command in that it indicates a module that is needed B during the testing of the distribution (often a period of only a few seconds) but will B be needed after the distribution is installed. The C 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 C command is sometimes used by some authors along with C 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. =head2 configure_requires configure_requires 'File::Spec' => '0.80'; The C command indicates a configure-time dependency for the distribution. The specification format is identical to that of the C command. The C 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 C command. The C command creates an entry in the special configure_requires: key in the distribution's F file. Although most of F is considered advisory only, a L client will treat the contents of configure_requires: as authoritative, and install the listed modules B it executes the F (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 B itself only supports 5.005, it will silently add the equivalent of a C<< configure_requires( perl => '5.005' ); >> command to your distribution. =head2 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 C 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 F 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. =head2 install_script # The following are equivalent install_script 'script/scriptname' The C 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 B put a .pl on the end of such scripts, so that they feel more natural when being used. In the example above, the F