Devel::Required - automatic update of required modules documentation
This documentation describes version 0.10.
use ExtUtils::MakeMaker; # check README and lib/Your/Module.pm eval "use Devel::Required"; WriteMakefile ( NAME => "Your::Module", VERSION_FROM => "lib/Your/Module.pm", PREREQ_PM => { 'Foo' => '1.0', 'Bar::Baz' => '0.05' } ); use ExtUtils::MakeMaker; # specify which files should be checked eval "use Devel::Required text => 'INSTALL', pod => [qw(lib/Your/Module.pod)]" WriteMakefile ( NAME => "Your::Module", VERSION_FROM => "lib/Your/Module.pm", PREREQ_PM => { 'Foo' => '1.0', 'Bar::Baz' => '0.05' } );
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 appropriate text file and in the appropriate source files (either explicitely or implicitely specified).
It takes the information given with the PREREQ_PM parameter and by default writes this to the README file, as well as to the POD of the file specified with the VERSION_FROM parameter. Both these defaults can be overridden with the "text" and "pod" parameters in the use Devel::Required specification.
use Devel::Required
This module should only be installed on the system of the developer.
By default the following types of files will be changed:
A text file should at least have one of these marker texts:
Version: <- must start at beginning of line <- empty line <- another empty line 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:
Version: <- must start at beginning of line This documentation describes version #.##. <- added <- empty line 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 none of the marker texts are not found.
If no "text" file specification is specified, then the file "README" in the current directory will be assumed.
The pod file(s) that are (implicitely) specified, will be searched for any marker texts that consist of the lines:
=head1 VERSION <- must start at beginning of line <- empty line =(anything) <- any other pod directive =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 VERSION <- must start at beginning of line <- empty line This documentation describes version #.##. <- added <- added =(anything) <- any other pod directive =head1 REQUIRED MODULES <- must start at beginning of line <- empty line Foo (1.0) <- added Bar::Baz (0.05) <- added <- added =(anything) <- any other pod directive
If no "pod" file specification is specified, then the file specified with the "VERSION_FROM" parameter of the call to WriteMakefile will be assumed.
WriteMakefile
It is possible to specify which text and which pod files should be searched for the text markers and possibly updated. The import routine of Devel::Required takes a list of parameters, each pair of which is considered to be a key-value pair. The following keys are recognized:
import
The value of this parameter is either the name of the text file to check, or a reference to a list with the names of one or more text files.
The value of this parameter is either the name of a file containing pod to check, or a reference to a list withe the names of one or more files containing pod.
(none)
Loading this module steals the "WriteMakefile" subroutine of the calling package and inserts its own logic for updating the necessary text-files. The version information is read from the generated "Makefile".
Elizabeth Mattijsen, <liz@dijkmat.nl>.
Please report bugs to <perlbugs@dijkmat.nl>.
Castaway on Perl Monks for "complaining" about not mentioning prerequisite modules in the README or in the POD.
Dan Browning for suggestion being able to specify which text and pod files should be changed.
Copyright (c) 2003, 2004, 2006, 2007, 2009, 2012 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.
ExtUtils::MakeMaker.
To install Devel::Required, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Devel::Required
CPAN shell
perl -MCPAN -e shell install Devel::Required
For more information on module installation, please visit the detailed CPAN module installation guide.