NAME

Module::Build::Prereq - Verify your Build.PL/Makefile.PL has all the modules you use()

SYNOPSIS

use Module::Build::Prereq;

assert_modules(\%prereq_pm);

WriteMakefile(CONFIGURE_REQUIRES => {
                'Module::Build::Prereq' => '0.01' },
              PREREQ_PM => \%prereq_pm);

# or Module::Build->new(requires => \%prereq_pm)->create_build_script;

DESCRIPTION

Module::Build::Prereq helps you as a developer make sure you've captured all of your dependencies correctly in your Makefile.PL or Build.PL. This module is meant to be used during development or for non-public modules that need to guarantee modules are installed during deployment.

Module::Build::Prereq naïvely crawls through your source files (*.pm by default) looking for 'use ...' statements. It then subtracts any module that is part of Perl's core module list (as determined by Module::CoreList), subtracts any modules you've told it to ignore, skips any modules already in the PREREQ_PM hashref, then warns you about the rest.

What then? Ideally you'd include those modules in your Makefile.PL's PREREQ_PM list (or Build.PL's requires list) or add them to the ignore_modules pattern in assert_modules for the next run.

For more thorough and careful dependency checks (including CPAN lookups) see BDFOY's Module::Release::Prereq, RJBS's Perl::PrereqScanner, and other related modules.

assert_modules

Module::Build::Prereq has one exported function: assert_modules. It takes the following parameters:

prereq_pm

Required. This is the same hashref you would supply to WriteMakefile's PREREQ_PM argument:

my $prereq_pm = { 'Foo' => '1.22',
                  'Bar' => '0.27a' };

assert_modules(prereq_pm => $prereq_pm);

WriteMakefile(PREREQ_PM => $prereq_pm, ...);

ignore_modules

Optional. A regular expression of module names assert_modules should ignore when looking for missing modules.

assert_modules(prereq_pm => \%modules,
               ignore_modules => qr(^(?:Corp::|BigCorp::|InHouse::)));

module_paths

Optional. A listref of paths to crawl for your *.pm (or see pm_extension) files; by default this is set to lib.

assert_modules(prereq_pm => \%modules,
               module_paths => ['lib', 'examples']);

pm_extension

Optional. A regular expression of what your module names look like. By default this is set to /\.[Pp][Mm]$/.

assert_modules(prereq_pm => \%modules,
               pm_extension => qr(\.p[ml]$));

If assert_modules finds one or more modules you are use()ing but not found in your Makefile.PL, it will die() saying which modules were not found.

BACKSTORY

The author uses the following general pattern for deployment in one particular case:

$ perl Makefile.PL
$ make
$ make test
$ make dist
(copy tarball to production and install it)

Every now and then someone will add a new dependency via a use() statement in a module but forget to update Makefile.PL with that dependency. When the module rolls out, sometimes the dynamic nature of things allows things to run except for the one module that's missing its dependency.

Module::Build::Prereq is one simple-minded effort to prevent that from happening.

SEE ALSO

Test::Prereq (BDFOY) for a more thorough way to do this in your module tests rather than at Makefile.PL. Module::Release::Prereq is also by BDFOY and far more throrough than this module. Perl::PrereqScanner (RJBS) is a mature scanner implementation as well.

AUTHOR

Scott Wiersdorf, <scott@betterservers.com>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Scott Wiersdorf

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.3 or, at your option, any later version of Perl 5 you may have available.