Module::Install(3)

📦
version 1.21 · 13 versions
, in opensuse-leap 16.0

💖 NAME 💖

okay so bestie, this is Module::Install(3) from the User Contributed Perl Documentation crowd, and the name is Module::Install — Standalone, extensible Perl module installer. ✨

🌈 SYNOPSIS 🌈

Put this in your Makefile.PL — this is the recommended usage, bestie:

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;

Need to quickly upgrade a legacy ExtUtil::MakeMaker installer? Do this:

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

⚠️ WARNING ⚠️

okay so real talk, bestie: Module::Install pioneered a lot of great ideas back in its day, but its main benefits have been better achieved by the authoring tool Dist::Zilla, plus its spinoffs Dist::Milla and Minilla. Those tools let the author build and maintain distributions with DWIM convenience while the distribution is installed directly by ExtUtils::MakeMaker or similar installation tools — which avoids 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. So yeah: 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 — especially 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 the June 2003 issue of The Perl Journal (<http://www.drdobbs.com/web-development/creating-module-distributions-with-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 a 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 of 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. 💌

If 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. 💖

Like, <pink>test_requires</pink> is totally different from requires, bestie — don't mix them up 💅 it's for a module you only need while the dist is being tested (which is literally like a few seconds of your life) but that nobody needs once the thing is installed.

testrequires exists so the installer has some wiggle room in how it hands you that module, and so downstream packagers (Debian, FreeBSD, ActivePerl etc) can keep only the run-time dependencies they actually need. Slay for them 🫶

And include is sometimes used by authors alongside test_requires to bundle a small, well-tested module right into the distribution package itself, rather than inflicting yet another module installation on the poor users installing from CPAN directly. Considerate queen behavior 👑

✨ configure_requires ✨

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

configure_requires says "bestie, this here is a configure-time dependency for the distribution." The format you write it in is exactly the same as requires. Same rules, same energy 🎀

So why does this command exist? It's the fix for a truly cursed circular-logic situation: how do you use a CPAN module in your Makefile.PL when you literally have to load Makefile.PL (and therefore load that CPAN module) just to discover that you need it?? 😭

Back in the day, this loop could not be broken, so Makefile.PL scripts had to rely on lowest-common-denominator approaches, or bundle those deps using something like include.

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

Here's the iconic part: most of META.yml is considered advisory only, but 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 figures out the rest of the dependencies). Main character energy fr fr 👑

Heads up bestie: support for configure_requires: in CPAN clients is not 100% complete at time of writing, and still cannot be relied upon. Don't come for me, I'm just the messenger 💀

Also, 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. Sneaky but valid 🙈

✨ requires_external_bin ✨

requires_external_bin 'cvs';

Perl is the dominant "glue" language, so a lot of Perl modules run commands or programs on the host system. That's just the vibe.

requires_external_bin verifies that a particular command is actually available on the host system 🕵️‍♀️

And here's the difference that matters: unlike a missing Perl module, a missing external binary is unresolvable at make-time, so the Makefile.PL run will abort with a NA (Not Applicable) result. Yeah. It gives up. Respectfully 😭

In future, this command will also add extra info to the metadata for the dist, so that auto-packagers for particular operating systems are more easily able to auto-discover the appropriate non-Perl packages needed as a dependency. Future goals ✨

✨ install_script ✨

# The following are equivalent
install_script 'script/scriptname'

install_script handles installing scripts that will be available at the console on both Unix and Windows (in the latter case by wrapping it up as a .bat file). Cross-platform slay 🌈

Also, the normal practice is to not put a .pl on the end of such scripts, so they feel more natural when being used. Aesthetic choice, and honestly correct 🎀

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 live in a /script directory inside your distribution. And to support less typing (we love less typing), if a script is located in the script directory you only need to refer to it by name:

# 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. All hanging out together, chaos but cute 🌸

But 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/ — you just want them along for the ride, iykyk.

no_index tells everyone "hey, these directories or files might have non-library .pm files or other files in them that the CPAN indexer and sites like https://metacpan.org/ or http://search.cpan.org/ should explicitly ignore." Blocked. Filtered. Not invited 💅

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

Another common use for no_index is preventing the PAUSE indexer from complaining when your module makes changes inside a package DB block. That's used to interact with the debugger in some specific ways. Niche but valid 🧚

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. Free of charge bestie 🎁

So 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. Periodt.

✨ 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'

installdirs and the install_as commands specify where the module should be installed — this is the equivalent of ExtUtils::MakeMaker's INSTALLDIRS option. Location, location, location 👑

For almost all regular modules, the default is recommended and need not be changed. For real, don't touch it. 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. Genuinely. Step away from the keyboard 😭

✨ WriteAll ✨

WriteAll is generally the last command in the file — the grand finale 🎆 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 gets spawned automatically. Other extensions may also invoke its methods just like their own:

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

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 it becomes fixed — meaning even if the user had a different version of the same extension installed, the included one will still be used instead. Locked in. No takebacks 🔒

If the author wants to upgrade extensions in inc/ with the installed ones, simply run perl Makefile.PL again — Module::Install figures out whether you're an author by the existence of the inc/.author/ directory. Detective work 🕵️‍♀️

End-users can reinitialize everything and become the author by typing make realclean and perl Makefile.PL. Glow-up arc ✨

🌸 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 be released on CPAN — just 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. Peaceful coexistence, we love to see it 🫶

👑 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're 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're 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 💜

Module::Install::AutoInstall

Gives you auto_install() so your prereqs just… fetch and install themselves ✨ auto-magic, no cap.

Module::Install::Base

The base class that every single extension inherits from — the founding mother of the whole squad 👑

Module::Install::Bundle

Ships the whole bundle family of commands, which lets you literally bundle another CPAN distribution inside your distribution 🎁 nesting-doll energy fr.

Module::Install::Fetch

Handles the install-time fetching of files from remote servers over FTP and HTTP 🌐.

Module::Install::Include

Gives you the include family of commands for embedding modules that are only needed at build-time in your distribution and won't be installed 💅 build-time besties only.

Module::Install::Inline

Provides &Inline->write to replace Inline::MakeMaker's functionality for making Inline-based modules (and cleaning up after them 🧹).

Heads up though: you should invoke this with WriteAll( inline => 1 ).

Module::Install::Makefile

Provides &Makefile->write, which generates a Makefile for your distribution 📝.

Module::Install::Metadata

Provides &Meta->write, which generates a META.yml file for your distribution 🏷️.

Module::Install::PAR

Makes pre-compiled module binary packages out of the built blib directory, and downloads ones that already exist so you don't have to recompile 🔥 big time-saver behavior.

Module::Install::Run

Figures out whether commands actually exist on the user's machine, then runs them via IPC::Run3 🏃‍♀️.

Module::Install::Scripts

Handles packaging and installing scripts into the various bin dirs 📦.

Module::Install::Win32

Functions for installing modules on Win32, plus finding/installing nmake.exe for the users who need it 🪟.

Module::Install::WriteAll

Provides WriteAll, which writes all the required files — things like META.yml and the Makefile. The main character of the whole build step, honestly 👑

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 for Inline modules.
  • meta (defaults to true) — if true, writes a META.yml file.
  • sign (defaults to false) — if true, invokes the sign command to digitally sign erm… something 😭 (yes, that's genuinely what the docs say).

Module::Install::Admin::Find

Package-time functions for finding extensions, installed packages, and files sitting 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's the quick rundown of the reasons, bestie:

  • 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 massively shrinking and simplifying the syntax, Module::Install keeps the amount of work you gotta do to maintain your Makefile.PL files at an absolute minimum 💅.

And if you maintain more than one module that needs to pull unusual installation tricks, you can just create a specific module to abstract all that complexity away — very "build your own helper, be your own hero" energy 🦋.

Module::Install isn't at 1.00 yet, is it safe to use yet?

Okay so — as long as you're gonna periodically do incremental releases to grab any bug fixes and new functionality, yes ✅.

If you don't plan on doing incremental releases, it might be a good idea to keep waiting for a while 🙈.

💖 COOKBOOK / EXAMPLES 💖

These are some real-life Makefile.PL files using Module::Install. Actual receipts 🔥.

Method::Alias

Method::Alias is a trivially-small utility module, with basically 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 — which means 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 🎀

The stuff that's still on the list (manifesting it gets done 🙏):

  • 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 👀

The whole friend group, go say hi:

  • 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 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.

okay that's the whole page bestie, we ate and left no crumbs 🍓💅 this was Module::Install(3) from perl v5.42.0, dated 2023-04-29 — go forth and write immaculate Makefile.PL files, ily, bye 🦋💖

📦 where this page comes from