perlmeditation
liz
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 [id://316828].
<P>
Not being happy with the result, I decided to put this into a module which is on CPAN now: [cpan://Devel::Required].
<P>
From the pod:
<DL>
<DT>NAME
<DD>
Devel::Required - Automatic update of required modules documentation
<P>
<DT>SYNOPSIS
<DD><PRE> 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' }
);
</PRE>
<P>
<DT>DESCRIPTION
<DD>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).
<P>
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.
<P>
This module should only be installed on the system of the developer.
<P>
The following files will be changed:
<P>
<DL>
<DT>README
<DD>The README file should exists in the current directory. It should at
least have this marker text:
<PRE>
Required Modules: <- must start at beginning of line
<- empty line
<- another empty line
</PRE>
After Makefile.PL is executed (using the example of the SYNOPSIS, the
above will be changed to:
<PRE>
Required Modules: <- must start at beginning of line
Foo (1.0) <- added
Bar::Baz (0.05) <- added
<- empty line
<- another empty line
</PRE>
<P>
No changes will be made if the marker text is not found.
<P>
<DT>Module file
<DD>The file indicated with the "VERSION_FROM" parameter, will be
searched for a marker text that consists of the lines:
<PRE>
=head1 REQUIRED MODULES <- must start at beginning of line
<- empty line
=(anything) <- any other pod directive
</PRE>
<P>
After Makefile.PL is executed (using the example of the SYNOPSIS, the
above will be changed to:
<PRE>
=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
</PRE>
No changes will be made if the marker text is not found.
</DL>
</DL>
<P>
Now only to change of all my modules to use this new feature... ;-)
<P>
Liz