GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DEVEL::REQUIRED (3)

.ds Aq ’

NAME

Devel::Required - automatic update of required modules documentation

CONTENTS

VERSION

This documentation describes version 0.14.

SYNOPSIS



 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 <<"CODE";
 use Devel::Required
   text => INSTALL,
   pod  => [ qw( lib/Your/Module.pod ) ],
 ;
 CODE
 WriteMakefile (
  NAME         => "Your::Module",
  VERSION_FROM => "lib/Your/Module.pm",
  PREREQ_PM    => { Foo => 1.0, Bar::Baz => 0.05 }
 );

 use ExtUtils::MakeMaker; # specify maint / blead installation information
 eval "use Devel::Required maint_blead => 5.014";



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 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.

Optionally, it will also update installation information, specifically for distributions that have a maint and blead version internally.

This module should <B>onlyB> be installed on the system of the developer.

FILES CHANGED

By default the following types of files will be changed:
text file 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



Optionally it may have an Installation: marker:



 Installation:                <- must start at beginning of line
                              <- empty line
                              <- another empty line
                              <- yet 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

 Installation:                  <- must start at beginning of line
 (extensive installation info)  <- added
                                <- empty line
                                <- another 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.

pod file 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



Optionally it may have an INSTALLATION marker:



 =head1 INSTALLATION          <- 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

 =head1 INSTALLATION                         <- must start at beginning of line
                                             <- empty line
 (extensive installation info)               <- added
                                             <- added
 =(anything)                                 <- any other pod directive



No changes will be made if none of the marker texts are not found.

If no pod file specification is specified, then the file specified with the VERSION_FROM parameter of the call to WriteMakefile will be assumed.

SPECIFYING YOUR OWN FILES

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:
text 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.
pod 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.

ADDING MAINT / blead INSTALLATION INFORMATION



 use Devel::Required maint_blead => $version;



By specifying a version number with the <maint_blead> key, the text / pod files will be searched for an Installation marker. The value should be the Perl version <B>belowB> which the maint version of the code should be installed.

The actual installation text is more or less fixed, but may be adapted in the future to provide more clarity for developers and packagers.

REQUIRED MODULES



 (none)



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. The version information is read from the generated Makefile.

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.

Dan Browning for suggestion being able to specify which text and pod files should be changed.

COPYRIGHT

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.

SEE ALSO

ExtUtils::MakeMaker.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DEVEL::REQUIRED (3) 2012-12-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.