In a recent discussion in the CB, castaway mentioned that she missed a list of required modules in the documentation of one of my modules. This initially resulted in the code snippet Auto-document prerequisites in README.

Not being happy with the result, I decided to put this into a module which is on CPAN now: Devel::Required.

From the pod:

NAME

Devel::Required - Automatic update of required modules documentation

SYNOPSIS

 use ExtUtils::MakeMaker;
 eval "use Devel::Required"; # auto-update documentation if needed
 WriteMakefile (
  NAME         => "Your::Module",
  VERSION_FROM => "lib/Your/Module.pm",
  PREREQ_PM    => { 'Foo' => '1.0', 'Bar::Baz' => '0.05' }
 );

DESCRIPTION

The Devel::Required module only serves a purpose in the development environment of an author of a CPAN module (or more precisely: a user of the ExtUtils::MakeMaker module. It makes sure that any changes to the required modules specified in the Makefile.PL are automatically reflected in the README file and in the main source file (if implicitely specified).

It takes the information given with the PREREQ_PM parameter and writes this to the README file, as well as to the POD of the file specified with the VERSION_FROM parameter.

This module should only be installed on the system of the developer.

The following files will be changed:

README

The README file should exists in the current directory. It should at least have this marker text:

 Required Modules:            <- must start at beginning of line
                              <- empty line
                              <- another empty line

After Makefile.PL is executed (using the example of the SYNOPSIS, the above will be changed to:

 Required Modules:            <- must start at beginning of line
  Foo (1.0)                   <- added
  Bar::Baz (0.05)             <- added
                              <- empty line
                              <- another empty line

No changes will be made if the marker text is not found.

Module file

The file indicated with the "VERSION_FROM" parameter, will be searched for a marker text that consists of the lines:

 =head1 REQUIRED MODULES      <- must start at beginning of line
                              <- empty line
 =(anything)                  <- any other pod directive

After Makefile.PL is executed (using the example of the SYNOPSIS, the above will be changed to:

 =head1 REQUIRED MODULES      <- must start at beginning of line
                              <- empty line
 Foo (1.0)                    <- added
 Bar::Baz (0.05)              <- added
                              <- empty line
 =(anything)                  <- any other pod directive

No changes will be made if the marker text is not found.

Now only to change of all my modules to use this new feature... ;-)

Liz