NAME
ExtUtils::ModuleMaker::PBP - Create a Perl extension in the style of Damian Conway's Perl Best Practices
SYNOPSIS
use ExtUtils::ModuleMaker::PBP;
$mod = ExtUtils::ModuleMaker::PBP->new(
NAME => 'Sample::Module'
);
$mod->complete_build();
$mod->dump_keys(qw|
... # key provided as argument to constructor
... # same
|);
$mod->dump_keys_except(qw|
... # key provided as argument to constructor
... # same
|);
$license = $mod->get_license();
$mod->make_selections_defaults();
VERSION
This document references version 0.09 of ExtUtils::ModuleMaker::PBP, released to CPAN on April 5, 2006.
DESCRIPTION
ExtUtils::ModuleMaker::PBP subclasses Perl extension ExtUtils::ModuleMaker. If you are not already familiar with ExtUtils::ModuleMaker, you should read its documentation now. The documentation provided below is intended primarily for future maintainers and extenders of ExtUtils::ModuleMaker::PBP.
The default value settings and methods described below supersede the similarly named methods in ExtUtils::ModuleMaker. When used as described herein, they will create a CPAN-ready Perl distribution the content of whose files reflects programming practices recommended by Damian Conway in his book Perl Best Practices (O'Reilly, 2005) http://www.oreilly.com/catalog/perlbp/.
USAGE
The easiest way to get started with ExtUtils::ModuleMaker::PBP is to use the mmkrpbp utility included in this distribution. mmkrpbp is basically a clone of the modulemaker utility included with ExtUtils::ModuleMaker. To get started with mmkrpbp, simply go to the command-prompt and enter:
% mmkrpbp
Then, answer the questions at each prompt. In many cases, you will simply have to type a single letter or number to make your selections. Please see the documentation for mmkrpbp and modulemaker.
DEFAULT VALUES
The following default values for ExtUtils::ModuleMaker::PBP differ from those set in ExtUtils/ModuleMaker/Defaults.pm.
Default to compact top directory. E.g., Alpha-Beta-Gamma instead of Alpha/Beta/Gamma.
$self->{COMPACT} = 1;
Default to placing
use_ok
tests for multiple modules in a single t/*.t file rather than one t*.t file for each module.$self->{EXTRA_MODULES_SINGLE_TEST_FILE} = 1;
Count of t/*.t files begins at 0 rather than 1.
$self->{FIRST_TEST_NUMBER} = 0;
In name of test file, test number is formatted as 2-digit rather than 3-digit.
$self->{TEST_NUMBER_FORMAT} = "%02d";
In name of test file, use a dot (
.
) rather than an underscore (_
) to separate the numerical and lexical parts of the name.$defaults_ref->{TEST_NAME_SEPARATOR} = q{.};
Do not include a Todo file in the top level of the distribution.
$defaults_ref->{INCLUDE_TODO} = 0;
Include t/pod_coverage.t in the distribution.
$defaults_ref->{INCLUDE_POD_COVERAGE_TEST} = 1;
Include t/pod.t in the distribution.
$defaults_ref->{INCLUDE_POD_TEST} = 1;
Do not include directory scripts/ in the distribution.
$defaults_ref->{INCLUDE_SCRIPTS_DIRECTORY} = 0;
METHODS
Methods Called within complete_build()
text_Buildfile()
Usage : $self->text_Buildfile() within complete_build()
Purpose : Composes text for a Buildfile for Module::Build
Returns : String holding text for Buildfile
Argument : n/a
Throws : n/a
Comment : References EU::MM object attributes
NAME, LICENSE, AUTHOR, EMAIL and FILE
text_Changes()
Usage : $self->text_Changes($only_in_pod) within complete_build;
block_pod()
Purpose : Composes text for Changes file
Returns : String holding text for Changes file
Argument : $only_in_pod: True value to get only a HISTORY section for POD
False value to get whole Changes file
Throws : n/a
Comment : Accesses EU::MM object attributes
NAME, VERSION, timestamp, eumm_version
text_Makefile()
Usage : $self->text_Makefile() within complete_build()
Purpose : Build Makefile
Returns : String holding text of Makefile
Argument : n/a
Throws : n/a
Comment : References EU::MM object attributes
NAME, AUTHOR, EMAIL and FILE
text_README()
Usage : $self->text_README() within complete_build()
Purpose : Build README
Returns : String holding text of README
Argument : n/a
Throws : n/a
Comment : References EU::MM object attributes
NAME, VERSION, COPYRIGHT_YEAR and AUTHOR
text_pm_file()
Usage : $self->text_pm_file($module) within generate_pm_file()
Purpose : Composes a string holding all elements for a pm file
Returns : String holding text for a *.pm file
Argument : $module: pointer to the module being built
(as there can be more than one module built by EU::MM);
for the primary module it is a pointer to $self
Comment : References EU::MM object attributes
NAME, AUTHOR, EMAIL and COPYRIGHT_YEAR
PREREQUISITES
ExtUtils::ModuleMaker, version 0.40 or later. http://search.cpan.org/dist/ExtUtils-ModuleMaker/.
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
No bugs have been reported.
Please report any bugs or feature requests to bug-ExtUtils-ModuleMaker-PBP@rt.cpan.org
, or through the web interface at http://rt.cpan.org.
AUTHOR
James E Keenan: jkeenan [at] cpan [dot] org
LICENSE AND COPYRIGHT
Standard text of files created by ExtUtils::ModuleMaker::PBP copyright (c) 2005 Damian Conway. Adapted from Module::Starter::PBP and used by permission. Code building these files copyright (c) 2005 James E Keenan. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perldoc perlartistic
.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE ''AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
SEE ALSO
ExtUtils::ModuleMaker, modulemaker, mmkrpbp.