Beefy Boxes and Bandwidth Generously Provided by pair Networks
Come for the quick hacks, stay for the epiphanies.
 
PerlMonks  

How the CB created another CPAN module: Devel::Required

by liz (Monsignor)
on Dec 28, 2003 at 18:25 UTC ( [id://317309]=perlmeditation: print w/replies, xml ) Need Help??

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

Replies are listed 'Best First'.
Re: How the CB created another CPAN module: Devel::Required
by castaway (Parson) on Dec 29, 2003 at 07:56 UTC
    Excellent!

    C.

Re: How the CB created another CPAN module: Devel::Required
by clscott (Friar) on Dec 29, 2003 at 22:15 UTC

    That's very nice. Have you reimplemented part of Module::ScanDeps ?

    --
    Clayton
      Nope, nothing as fancy as that. As it sais in the pod, it just takes whatever you've specified with PREREQ_PM and puts that in the README and the source file indicated with VERSION_FROM.

      It's a tool to help developers improve the documentation of their modules. Nothing more. Nothing less.

      Liz

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://317309]
Approved by Corion
Front-paged by Courage
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others having a coffee break in the Monastery: (5)
As of 2024-03-19 11:34 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found