James E Keenan > ExtUtils-ModuleMaker > ExtUtils::ModuleMaker

Download:
ExtUtils-ModuleMaker-0.51.tar.gz

Dependencies

Annotate this POD (1)

Related Modules

Module::Build
Test::More
Inline::C
Module::Signature
Archive::Tar
Data::Dumper
Test::Harness
Bio::Phylo
Module::ScanDeps
File::Temp
more...
By perlmonks.org

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.51   Source  

NAME ^

ExtUtils::ModuleMaker - Better than h2xs for creating modules

SYNOPSIS ^

At the command prompt:

    %   modulemaker

Inside a Perl program:

    use ExtUtils::ModuleMaker;

    $mod = ExtUtils::ModuleMaker->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.51 of ExtUtils::ModuleMaker, released to CPAN on February 9, 2008.

DESCRIPTION ^

This module is a replacement for the most typical use of the h2xs utility bundled with all Perl distributions: the creation of the directories and files required for a pure-Perl module to be installable with make and distributable on the Comprehensive Perl Archive Network (CPAN).

h2xs has many options which are useful -- indeed, necessary -- for the creation of a properly structured distribution that includes C code as well as Perl code. Most of the time, however, h2xs is used as follows

    %   h2xs -AXn My::Module

to create a distribution containing only Perl code. ExtUtils::ModuleMaker is intended to be an easy-to-use replacement for this use of h2xs.

While you can call ExtUtils::ModuleMaker from within a Perl script (as in the SYNOPSIS above), it's easier to use with a command-prompt invocation of the modulemaker script bundled with this distribution:

    %   modulemaker

Then respond to the prompts. For Perl programmers, laziness is a virtue -- and modulemaker is far and away the laziest way to create a pure Perl distribution which meets all the requirements for worldwide distribution via CPAN.

USAGE ^

Usage from the command-line with modulemaker

The easiest way to use ExtUtils::ModuleMaker is to invoke the modulemaker script from the command-line. You can control the content of the files built by modulemaker either by supplying command-line options or -- easier still -- replying to the screen prompts in modulemaker's interactive mode.

If you are encountering ExtUtils::ModuleMaker for the first time, you should turn now to the documentation for modulemaker which is bundled this distribution. Return to this document once you have become familiar with modulemaker.

Use of Public Methods within a Perl Program

You can use ExtUtils::ModuleMaker within a Perl script to generate the directories and files needed to begin work on a CPAN-ready Perl distribution. You will need to call new() and complete_build(), both of which are described in the next section. These two methods control the building of the file and directory structure for a new Perl distribution.

There are four other publicly available methods in this version of ExtUtils::ModuleMaker. dump_keys, dump_keys_except and get_license are intended primarily as shortcuts for trouble-shooting problems with an ExtUtils::ModuleMaker object. make_selections_defaults enables you to be even lazier in your use of ExtUtils::ModuleMaker by saving keystrokes entered for attributes.

new

Creates and returns an ExtUtils::ModuleMaker object. Takes a list containing key-value pairs with information specifying the structure and content of the new module(s). (In this documentation, we will sometimes refer to these key-value pairs as the attributes of the ExtUtils::ModuleMaker object.) With the exception of key EXTRA_MODULES (see below), the values in these pairs are all strings. Like most such lists of key-value pairs, this list is probably best held in a hash. Keys which may be specified are:

complete_build

Creates all directories and files as configured by the key-value pairs passed to ExtUtils::ModuleMaker::new. Returns a true value if all specified files are created -- but this says nothing about whether those files have been created with the correct content.

dump_keys

When troubleshooting problems with an ExtUtils::ModuleMaker object, it is often useful to use Data::Dumper to dump the contents of the object. Use dump_keys() when you only need to examine a few of the object's attributes.

    $mod->dump_keys( qw| NAME ABSTRACT | );

dump_keys_except

When troubleshooting problems with an ExtUtils::ModuleMaker object, it is often useful to use Data::Dumper to dump the contents of the object. However, since certain elements of that object are often quite lengthy (e.g, the values of keys LicenseParts and USAGE_MESSAGE), it's handy to have a dumper function that dumps all keys except certain designated keys.

    $mod->dump_keys_except(qw| LicenseParts USAGE_MESSAGE |);

get_license

Returns a string which nicely formats a short version of the License and Copyright information.

    $license = $mod->get_license();
    print $license;

... will print something like this:

    =====================================================================
    =====================================================================
    [License Information]
    =====================================================================
    =====================================================================
    [Copyright Information]
    =====================================================================
    =====================================================================

(Earlier versions of ExtUtils::ModuleMaker contained a Display_License function in each of submodules ExtUtils::ModuleMaker::Licenses::Standard and ExtUtils::ModuleMaker::Licenses::Local. These functions were never publicly documented or tested. get_license() is intended as a replacement for those two functions.)

make_selections_defaults()

Saves the values you entered as arguments passed to new() in a personal defaults file so that they supersede the defaults provided by ExtUtils::ModuleMaker itself.

This is an advanced usage of ExtUtils::ModuleMaker. If you have used ExtUtils::ModuleMaker more than once, you have probably typed in a choice for AUTHOR, EMAIL, etc., more than once. To save unnecessary typing and reduce typing errors, ExtUtils::ModuleMaker now offers you the possibility of establishing personal default values which override the default values supplied with the distribution and found in lib/ExtUtils/ModuleMaker/Defaults.pm.

Suppose that you have called ExtUtils::ModuleMaker::new() as follows:

    $mod = ExtUtils::ModuleMaker->new(
        NAME            => 'Sample::Module',
        ABSTRACT        => 'Now is the time to join the party',
        AUTHOR          => 'Hilton Stallone',
        CPANID          => 'RAMBO',
        ORGANIZATION    => 'Parliamentary Pictures',
        WEBSITE         => 'http://parliamentarypictures.com',
        EMAIL           => 'hiltons@parliamentarypictures.com',
    );

While $mod is still in scope, you can call:

    $mod->make_selections_defaults()

and the values selected -- with two important exceptions -- will be saved in a Personal/Defaults.pm file stored in your home directory. The next time you invoke ExtUtils::ModuleMaker, the new values will appear in the appropriate locations in the files created by complete_build(). They will also appear in the menus provided on screen by the modulemaker utility.

What are those two important exceptions?

CUSTOMIZATION ^

ExtUtils::ModuleMaker is designed to be customizable to your needs and to offer you more flexibility as you become more experienced with it.

Via modulemaker Utility Interactive Mode

As with everything else about ExtUtils::ModuleMaker, the easiest, laziest way to get started is via the modulemaker utility; see its documentation. Suppose that you have entered your correct name, email address and website at the prompts in modulemaker's Author Menu.

  ------------------------

  modulemaker: Author Menu

      Feature       Current Value
  N - Author        'John Q Public'
  C - CPAN ID       'MODAUTHOR'
  O - Organization  'XYZ Corp.'
  W - Website       'http://public.net/~jqpublic'
  E - Email         'jqpublic@public.net'

  R - Return to main menu
  X - Exit immediately

  Please choose which feature you would like to edit:

Why should you ever have to enter this information again? Return to the modulemaker Main Menu (R).

  ------------------------

  modulemaker: Main Menu

      Feature                     Current Value
  N - Name of module              ''
  S - Abstract                    'Module abstract (<= 44 characters) goes here'
  A - Author information
  L - License                     'perl'
  D - Directives
  B - Build system                'ExtUtils::MakeMaker'

  G - Generate module
  H - Generate module;
      save selections as defaults

  X - Exit immediately

  Please choose which feature you would like to edit: 

Select H instead of G to generate the distribution. An internal call to make_selections_defaults() will save those selections in a personal defaults file and present them to you on the Author Menu the next time you go to use it.

Via modulemaker Utility Command-Line Options Mode

For simplicity, not all of ExtUtils::ModuleMaker's default values are represented on modulemaker's menus. Those that are not represented on those menus cannot be changed from there. They can, however, in many cases be specified as options passed to modulemaker on the command-line and automatically saved as personal defaults by including the s flag as one of those options. If, for example, your name is 'John Q Public' and you want all modules you create to have compact top-level directories, you would call:

    %   modulemaker -Icsn Sample::Module -u 'John Q Public'

A distribution with a top-level directory Sample-Module would be created. 'John Q Public' would appear in appropriate places in Sample-Module/Makefile.PL and Sample-Module/lib/Sample/Module.pm. You could then throw away the entire Sample-Module directory tree. The next time you call modulemaker, the call

    %   modulemaker -In Second::Module

would suffice to generate a compact top-level directory and 'John Q Public' would appear in appropriate locations instead of the dreaded 'A. U. Thor'.

Via ExtUtils::ModuleMaker::new()

In all cases, ExtUtils::ModuleMaker's default values can be overridden with arguments passed to new() inside a Perl program. The overriding can then be made permanent by calling make_selections_defaults().

Suppose, for example,

  1. that you want the files in your test suite to appear in a numerical order starting from 0 rather than ExtUtils::ModuleMaker's own default starting point of 1;
  2. that you want the number in the test file's name to be formatted as a two-digit string padded with zeroes rather than ExtUtils::ModuleMaker's own default format of a three-digit, zero-padded string;
  3. that you want the numerical part of the test filename to be joined to the lexical part with a dot (.) rather than ExtUtils::ModuleMaker's own default linkage character of an underscore (_); and
  4. that you want the lexical part of the test filename to reflect the module's name rather than ExtUtils::ModuleMaker's default of load.

Your Perl program would look like this:

    #!/usr/local/bin/perl
    use strict;
    use warnings;
    use ExtUtils::ModuleMaker;

    my $mod = ExtUtils::ModuleMaker->new(
        NAME        => 'Sample::Module',
        AUTHOR      => 'John Q Public',
        COMPACT     => 1,
        FIRST_TEST_NUMBER    => 0,
        TEST_NUMBER_FORMAT   => "%02d",
        TEST_NAME_SEPARATOR  => q{.},
        TEST_NAME_DERIVED_FROM_MODULE_NAME => 1,
    );

    $mod->make_selections_defaults();

A subsequent call to the modulemaker utility,

    %    modulemaker -In Second::Balcony::Jump

would generate a directory tree with a compact top-level, 'John Q Public' in appropriate locations in Second-Balcony-Jump/Makefile.PL and Second-Balcony-Jump/lib/Second/Balcony/Jump.pm and a test file called Second-Balcony-Jump/t/00.Second.Balcony.Jump.t.

Via Subclassing ExtUtils::ModuleMaker

If you're a power-user, once you start playing with ExtUtils::ModuleMaker, you won't be able to stop. You'll ask yourself, ''Self, if I can change the default values, why can't I change the 'boilerplate' copy that appears inside the files which ExtUtils::ModuleMaker creates?''

Now, you can. You can hack on the methods which ExtUtils::ModuleMaker::new() and complete_build() call internally to customize their results to your heart's desire. The key: build an entirely new Perl extension whose lib/*.pm file has methods that override the methods you need overridden -- and only those methods. Follow these steps:

1. Study ExtUtils::ModuleMaker::Defaults, ::Initializers and ::StandardText

ExtUtils::ModuleMaker's default values are stored in lib/ExtUtils/ModuleMaker/Defaults.pm, specifically, in its default_values() method. Identify those values which you wish to change.

ExtUtils::ModuleMaker's other internal methods are found in two other files: /lib/ExtUtils/ModuleMaker/Initializers.pm and lib/ExtUtils/ModuleMaker/StandardText.pm. Rule of thumb: If an internal method is called within new(), it is found in ExtUtils::ModuleMaker::Initializers. If it is called within complete_build(), it is found in ExtUtils::ModuleMaker::StandardText. Study these two packages to identify the methods you wish to override.

Hint: If changing a default value in ExtUtils::ModuleMaker::Defaults will achieve your objective, make that change rather than trying to override methods in ExtUtils::ModuleMaker::Initializers or ExtUtils::ModuleMaker::StandardText.

Hint: You should probably think about overriding methods in ExtUtils::ModuleMaker::StandardText before overriding those in ExtUtils::ModuleMaker::Initializers.

2. Use modulemaker to Create the Framework for a New Distribution

You're creating a new Perl extension. Who ya gonna call? modulemaker, natch! (If you have not read the documentation for modulemaker by this point, do so now.)

Suppose that you've gotten on the 'Perl Best Practices' bandwagon and want to create all your Perl extensions in the style recommended by Damian Conway in the book of the same name. Use modulemaker to create the framework:

    %    modulemaker -Icqn ExtUtils::ModuleMaker::PBP \ 
         -u 'James E Keenan' \ 
         -p JKEENAN \
         -o 'Perl Seminar NY' \ 
         -w http://search.cpan.org/~jkeenan/

You used the -q option above because you do not want or need a constructor in the new package you are creating. That package will inherit its constructor from ExtUtils::ModuleMaker.

3. Edit the lib/*.pm File

Open up the best text-editor at your disposal and proceed to hack:

    %    vi ExtUtils-ModuleMaker-PBP/lib/ExtUtils/ModuleMaker/PBP.pm

Add this line near the top of the file:

    use base qw{ ExtUtils::ModuleMaker };

so that ExtUtils::ModuleMaker::PBP inherits from ExtUtils::ModuleMaker (which, in turn, inherits from ExtUtils::ModuleMaker::Defaults, ExtUtils::ModuleMaker::Initializers and ExtUtils::ModuleMaker::StandardText).

If you have carefully studied ExtUtils::ModuleMaker::Defaults, ExtUtils::ModuleMaker::StandardText and Perl Best Practices, you will write methods including the following:

    sub default_values {
        my $self = shift;
        my $defaults_ref = $self->SUPER::default_values();
        $defaults_ref->{COMPACT}                        = 1;
        $defaults_ref->{FIRST_TEST_NUMBER}              = 0;
        $defaults_ref->{TEST_NUMBER_FORMAT}             = "%02d";
        $defaults_ref->{EXTRA_MODULES_SINGLE_TEST_FILE} = 1;
        $defaults_ref->{TEST_NAME_SEPARATOR}            = q{.};
        $defaults_ref->{INCLUDE_TODO}                   = 0;
        $defaults_ref->{INCLUDE_POD_COVERAGE_TEST}      = 1;
        $defaults_ref->{INCLUDE_POD_TEST}               = 1;
        return $defaults_ref;;
    }

    sub text_Makefile {
        my $self = shift;
        my $Makefile_format = q~
    use strict;
    use warnings;
    use ExtUtils::MakeMaker;

    WriteMakefile(
        NAME            => '%s',
        AUTHOR          => '%s <%s>',
        VERSION_FROM    => '%s',
        ABSTRACT_FROM   => '%s',
        PL_FILES        => {},
        PREREQ_PM    => {
            'Test::More'    => 0,
            'version'       => 0,
        },
        dist            => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
        clean           => { FILES => '%s-*' },
    );
    ~;
        my $text_of_Makefile = sprintf $Makefile_format,
            map { my $s = $_; $s =~ s{'}{\\'}g; $s; }
                $self->{NAME},
                $self->{AUTHOR},
                $self->{EMAIL},
                $self->{FILE},
                $self->{FILE},
                $self->{FILE};
        return $text_of_Makefile;
    }

Of course, for true Perl laziness, you'll use CPAN distribution ExtUtils::ModuleMaker::PBP, written by the author of ExtUtils::ModuleMaker as an exemplar of subclassing ExtUtils::ModuleMaker and generating the same output as Damian Conway's Module::Starter::PBP.

4. Test

How do you know you have correctly subclassed ExtUtils::ModuleMaker? With a test suite, of course. With careful editing, you can use many of ExtUtils::ModuleMaker's own tests in your new distribution. You will, of course, have to change a number of tests, because the default values implied by Conway's recommendations are different from ExtUtils::ModuleMaker's own defaults. Among other things, you will have to do a search-and-replace on all constructor calls.

    %    perl -pi'*.bak' -e 's{ExtUtils::ModuleMaker->new}{ExtUtils::ModuleMaker::PBP->new}g;'

Of course, you should have written your tests first, right?

5. Install and Use

You would install your new distribution as you would any other Perl distribution, i.e., with either ExtUtils::MakeMaker or Module::Build, depending on which you chose in creating your subclass.

    #!/usr/local/bin/perl
    use strict;
    use warnings;
    use ExtUtils::ModuleMaker::PBP;

    my $mod = ExtUtils::ModuleMaker::PBP->new(
        NAME        => 'Sample::Module',
    );
   
    $mod->complete_build();

For an adaptation of the modulemaker utility to work with ExtUtils::ModuleMaker::PBP, see mmkrpbp which is bundled with the latter package.

An Alternative Approach to Subclassing

There is one other way to subclass to ExtUtils::ModuleMaker which bears mentioning, more because the author used it in the development of this version of ExtUtils::ModuleMaker than because it is recommended. If for some reason you do not wish to create a full-fledged Perl distribution for your subclass, you can simply write the subclassing package and store it in the same directory hierarchy on your system in which your personal defaults file is stored.

For example, suppose you are experimenting and only wish to override one method in ExtUtils::ModuleMaker::StandardText. You can create a package called ExtUtils::ModuleMaker::AlternativeText. If you are working on a Unix-like system, you would move that file such that its path would be:

    "$ENV{HOME}/.modulemaker/ExtUtils/ModuleMaker/AlternativeText.pm"

You would then add one argument to your call to ExtUtils::ModuleMaker::new():

    my $mod = ExtUtils::ModuleMaker->new(
        NAME        => 'Sample::Module',
        ALT_BUILD   => 'ExtUtils::ModuleMaker::AlternativeText',
    );

CAVEATS ^

TO DO ^

AUTHOR/MAINTAINER ^

ExtUtils::ModuleMaker was originally written in 2001-02 by R. Geoffrey Avery (modulemaker [at] PlatypiVentures [dot] com). Since version 0.33 (July 2005) it has been maintained by James E. Keenan (jkeenan [at] cpan [dot] org).

SUPPORT ^

Send email to jkeenan [at] cpan [dot] org. Please include 'modulemaker' in the subject line. Please report any bugs or feature requests to bug-ExtUtils-ModuleMaker@rt.cpan.org, or through the web interface at http://rt.cpan.org.

ACKNOWLEDGMENTS ^

Thanks first and foremost to Geoff Avery for creating ExtUtils::Modulemaker and popularizing it via presentations I attended at YAPC::NA::2003 (Boca Raton) and YAPC::EU::2003 (Paris).

Soon after I took over maintenance of ExtUtils::ModuleMaker, David A Golden became a driving force in its ongoing development, providing suggestions for additional functionality as well as bug reports. David is the author of ExtUtils::ModuleMaker::TT which, while not a pure subclass of ExtUtils::ModuleMaker, extends its functionality for users of Template::Toolkit.

Thanks for suggestions about testing the modulemaker utility to Michael G Schwern on perl.qa and A Sinan Unur and Paul Lalli on comp.lang.perl.misc. Thanks for help in dealing with a nasty bug in the testing to Perlmonks davidrw and tlm. That well known Perl hacker, Anonymous Guest, contributed another bug report on rt.cpan.org.

As development proceeded, several issues were clarified by members of Perlmonks.org. CountZero, xdg, Tanktalus, holli, TheDamian and nothingmuch made particularly useful suggestions, as did Brian Clarkson.

Thanks also go to the following beta testers: Alex Gill, Marc Prewitt, Scott Godin, Reinhard Urban and imacat.

Version 0.39 of ExtUtils::ModuleMaker encountered spurious testing failure reports from testers.cpan.org. These were eventually diagnosed as being due to bugs in the automated testing programs and/or their operating environments on different systems -- i.e., to problems outside ExtUtils::ModuleMaker itself. Several Perlmonks helped investigate this problem: chromatic, dave_the_m, randyk, and njh.

Thanks to Paul M Sirianni for reporting bugs that led to versions 0.48 and 0.51.

COPYRIGHT ^

Copyright (c) 2001-2002 R. Geoffrey Avery. Revisions from v0.33 forward (c) 2005-2007 James E. Keenan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

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 ^

modulemaker, perlnewmod, h2xs, ExtUtils::MakeMaker, Module::Build, ExtUtils::ModuleMaker::PBP, ExtUtils::ModuleMaker::TT, mmkrpbp.

syntax highlighting: