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

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.

REQUIRED MODULES

(none)

TODO

Support for Module::Build should be added. Patches are welcome. Probably will do this myself at some point in the future when I migrate all of my modules from ExtUtils::MakeMaker to Module::Build.

THEORY OF OPERATION

Loading this module steals the "WriteMakefile" subroutine of the calling package and inserts its own logic for updating the necessary text-files.

AUTHOR

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Please report bugs to <perlbugs@dijkmat.nl>.

ACKNOWLEDGEMENTS

Castaway on Perl Monks for "complaining" about not mentioning prerequisite modules in the README or in the POD.

COPYRIGHT

Copyright (c) 2003 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

ExtUtils::MakeMaker.