Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Devel::Required(3)    User Contributed Perl Documentation   Devel::Required(3)

NAME
       Devel::Required - automatic update of required modules documentation

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

perl v5.24.1			  2012-12-07		    Devel::Required(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | FILES CHANGED | SPECIFYING YOUR OWN FILES | ADDING MAINT / blead INSTALLATION INFORMATION | REQUIRED MODULES | THEORY OF OPERATION | AUTHOR | ACKNOWLEDGEMENTS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Devel::Required&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help