The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
ExtUtils-ModuleMaker-PBP-0.09
River stage zero No dependents
++
/ ExtUtils::ModuleMaker::PBP

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.