Skip to end of metadata
Go to start of metadata


In Core

Module::Build is distributed with the core. Module::Build was first released with perl v5.9.4


Module::Build is the preferred build system for my Perl development work. My favorite features are: the ease
of use and the extensibility.

Implementing a Custom Build System

Module::Build is really ease to and be done so easily. Reasons for doing so can be numerous, there are some of the more common reasons I myself have encountered:

1. One you keep feeding long lines of options to Module::Build to get it to do what you need
1. One of the standard actions does not do exactly what you want to do, so you need to tweak it, beyond what can be done using the CLI options
1. You need to extend your build process with more steps, not implemented as part of the standard actions

Module::Build::Bundle is an example of the last point. This distribution is a sub-class of Module::Build implementing a step where
a set is automatically generated from a the Build.PL requires section.

The Module::Build documentation provides good pointers.

Build.PL Boilerplate

use strict;
use Module::Build;

my $build = Module::Build->new(
    dist_author          => '', #author name
    dist_abstract        => '', #short description
    module_name          => '', #module name, resolves both name and version
    license              => '', #license
    recursive_test_files => 1, #flag indicating whether t directory should be descended into recursively
    create_readme        => 1, #flag indicating whether README file should be auto-generated based on the file to which module_name points
    create_makefile_pl   => 'traditional',  
    configure_requires   => {},
    build_requires       => {},
    requires             => {},


The license specifies under what licensing the software is available. I always spent time trying to locate the canonical list of available values, so I decided to put it here. The list is lifted from Module::Build::Base (external link). Module::Build mentions Software::License (external link) as a possible canonical resource, another good list is included in CPAN::Meta::Spec (external link).

Module::Build List of Licenses
perl         => '',    
apache       => '',
apache_1_1   => '',
artistic     => '',
artistic_2   => '',
lgpl         => '',
lgpl2        => '',
lgpl3        => '',
bsd          => '',
gpl          => '',
gpl2         => '',
gpl3         => '',
mit          => '',
mozilla      => '',
open_source  => undef,
unrestricted => undef,
restrictive  => undef,
unknown      => undef,

Lifted from: Module::Build::Base 0.40.


This flag can be quite useful if you have a large number of test scripts and you want to organize these in a deep directory structure or a basic structure following the naming conventions of the components in your distribution.

If you are not using something like Test::Class and you want to isolate your tests of specific parts of your application into separate files, this can be useful since you can organize your files resembling your name space.



Dependencies you want to have met before starting the configuration step has to be specified in this section.

Use this section for dependencies you need for the whole process, like Module::Build. Newer versions of Module::Build adds this information if not present.


Dependencies you want to have met before starting the build step has to be specified in this section. Some clients might handle the distributions mentioned here differently. App::cpanminus asks you whether you want to have the dependencies installed and not just discarded after ended use.


Where the two previous steps: configure_requires and build_requires are just about the process of building, this step can be used to assert whether a given environment targeted for your build is same.

This step checks whether dependencies are met.


Build.PL can be extended with meta information related to the project and distribution. For my projects I define the following section in my Build.PL

META information
    meta_merge => {
        resources => {
            homepage         => '', #Site of distribution, see also ProjectSite below
            bugtracker       => '', #Bug tracker
            repository       => '', #SCM
            ProjectChangelog => '', #Change log
            ProjectSite      => '', #Web site
            ProjectWiki      => '', #Wiki

For Task::Jenkins it looks the following way:

META information example
    meta_merge => {
        resources => {
            homepage   => '',
            bugtracker => '',
            repository => '',
            ProjectChangelog => '',
            ProjectSite => '',
            ProjectWiki => '',

If you want to see examples of complete Build.PL files many of the CPAN distributions hosted here have complete examples: Business::DK::CPR aso.


Installing Scripts and Applications

Scripts are per default installed in /usr/local/bin

% mkdir bin

% touch bin/

% perl Build.PL

% ./Build

#too see where it goes
% ./Build fakeinstall

% sudo ./Build install

t alias

This has been taken from the Module::Build::Cookbook documentation, it is a very nice shell alias, which has saved me plenty of typing.

alias t './Build test --verbose 1 --test_files'
% t t/mytest.t

#Or to run the whole suite
% t

In addition, I can recommend the following aliases:

alias b='./Build'
alias build='./Build'
alias pb='perl Build.PL'
alias manifest='./Build manifest'
alias bm='./Build manifest'
alias bt='./Build test'
alias btv='./Build test --verbose 1'
alias btc='./Build testcover'
alias bc='./Build clean'
alias brc='./Build realclean'
alias bd="./Build dist --gzip='/usr/bin/gzip --force'"
alias bdc="./Build distcheck"

Resolving Data From Distribution Automatically

Module::Build can utilize a lot of parameters to assist the user in creating distributions etc.

The shortest representation however is to use the following snippet in your Build.PL

module_name => "Workflow"

This does the following

  • Sets dist_name to 'Workflow'
  • Sets dist_version_from to: $VERSION from: lib/

See also our Build.PL boilerplate.

Using cpanm with Module::Build to install dependencies

The installdeps action can be used with cpanm, please see the App::cpanminus page for more information.

Auto-generate the README file

create_readme => 1,

See also our Build.PL boilerplate.

Auto-generate the Makefile.PL for backwards compatibility

create_makefile_pl => 'traditional',

I have used previously used:

create_makefile_pl => 'passthrough',

Instead of the topmost example, this has given me some problems, see this CPAN testers report. The issue is further discussed and explained in this PerlMonks article on Module::Build and Makefile.PL generation.

See also our Build.PL boilerplate.

In order to address this potential issue for all of my CPAN distributions I have created this worksheet to get an overview.

Coverage Test via Module::Build


If you are using Module::Build you can utilize Devel::Cover easily as part of your build process.

% ./Build testcover

Module::Build can do test coverage using Devel::Cover. Devel::Cover takes a lot of options, which can be really interesting when customizing your coverage test.

In order to pass in options you have to utilize the environment variable: DEVEL_COVER_OPTIONS.

In order to execute a coverage test you could do the following:

% ./Build testcover

After this you will have a coverage report in cover_db/coverage.html. The report might be very extensive, providing coverage information on externals components you include via Subversion externals or if you are using larger frameworks like Mojolicious. You can then provide options to Devel::Cover to customize your report.

Here are the options Devel::Cover currently support ():

% DEVEL_COVER_OPTIONS=+inc,/Users,+inc,tmp,+inc,lib/ACME,+inc,t, ./Build testcover

Coverage Database

Please note that when experimenting the options, it is very important that you clear the existing coverage database to see the result. You might get a report based on the previous run of you have only changed some of the options.

% cover -delete

When experimenting with the options, prefix the invocating line with the note mentioned above.

% cover -delete && DEVEL_COVER_OPTIONS=+inc,/Users,+inc,tmp,+inc,t, ./Build testcover

Extract Dependencies Report

Module::Build can provide a list of your dependencies, from the requirements section in your Build.PL.

CLI - prereq_report
$ ./Build prereq_report

An example result could look at follows

prereq_report output
    Module                                   Need    Have
    Authen::Passphrase                       0        0.008
    autovivification                         0        0.10
    Carp                                     0        1.11
    Contextual::Return                       0
    Cwd                                      0        3.3
    Data::Dumper                             0        2.131

This is quite useful and it can of course be parsed, I do this to build the requirements.txt for Stackato deployments.


1 Comment

  1. Considering moving Devel::Cover related information to page dedicated to Devel::Cover