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.52 of ExtUtils::ModuleMaker, released to CPAN
on July 04 2014.
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:
- •
- Required Argument
- •
- NAME
The only required feature. This is the name of the primary module
(with '"::"' separators if needed). Will no longer support the
older, Perl 4-style separator ''"'"'' like the module
D'Oh. There is no current default for NAME; you must supply a name
explicitly.
- •
- Other Important Arguments
- •
- ABSTRACT
A short description of the module. CPAN likes to use this feature to
describe the module. If the abstract contains an apostrophe
("'"), then the value corresponding to key "ABSTRACT"
in the list passed to the constructor must be double-quoted; otherwise
Makefile.PL gets messed up. Certain CPAN indexing features still
work better if the abstract is 44 or fewer characters in length, but this
does not appear to be as mandatory as in the past. (Defaults to dummy
copy.)
- •
- VERSION
A string holding the version number. For alpha releases, include an
underscore to the right of the dot like "0.31_21". (Default is
0.01.)
- •
- LICENSE
Which license to include in the Copyright section. You can choose one of the
standard licenses by including 'perl', 'gpl', 'artistic', and 18 others
approved by opensource.org. The default is to choose the 'perl' flavor
which is to share it ''under the same terms as Perl itself.''
Other licenses can be added by individual module authors to
ExtUtils::ModuleMaker::Licenses::Local to keep your company lawyers happy.
Some licenses include placeholders that will be replaced with AUTHOR
information.
- •
- BUILD_SYSTEM
This can take one of three values:
- •
- 'ExtUtils::MakeMaker'
The first generates a basic Makefile.PL file for your module.
- •
- 'Module::Build'
The second creates a Build.PL file.
- •
- 'Module::Build and Proxy'
The third creates a Build.PL along with a proxy Makefile.PL script that
attempts to install Module::Build if necessary, and then runs the Build.PL
script. This option is recommended if you want to use Module::Build as
your build system. See Module::Build::Compat for more details.
Note: To correct a discrepancy between the documentation and code in
earlier versions of ExtUtils::ModuleMaker, we now explicitly provide this
synonym for the third option:
'Module::Build and proxy Makefile.PL'
(Thanks to David A Golden for spotting this bug.)
- •
- COMPACT
For a module named ''Foo::Bar::Baz'' creates a base directory named
''Foo-Bar-Baz'' instead of Foo/Bar/Baz. (Default is off.)
- •
- VERBOSE
Prints messages to STDOUT as it creates directories, writes files, etc.
(Default is off.)
- •
- PERMISSIONS
Used to create new directories. (Default is 0755: group and world can not
write.)
- •
- USAGE_MESSAGE
Message given when the module "die"s. Scripts should set this to
the same string it would print if the user asked for help. (A reasonable
default is provided.)
- •
- NEED_POD
Include POD section in *.pm files created. (Default is on.)
- •
- NEED_NEW_METHOD
Include a simple "new()" method in the *.pm files created.
(Default is on.)
- •
- CHANGES_IN_POD
Omit a Changes file, but instead add a HISTORY section to the POD.
(Default is off).
- •
- INCLUDE_MANIFEST_SKIP
Boolean value which, if true, includes a MANIFEST.SKIP file in the
distribution with reasonable default values facilitating use of the
make manifest command during module development. (Thanks to
David A Golden for this feature. Default is off.)
- •
- INCLUDE_TODO
Boolean value which, if true, includes a Todo file in the
distribution in which the module's author or maintainer can discuss future
lines of development. (Default is on.)
- •
- INCLUDE_LICENSE
Boolean value which, if true, includes a LICENSE file in the
distribution. (Which LICENSE file is determined in the LICENSE option.)
(Default is on.)
- •
- INCLUDE_SCRIPTS_DIRECTORY
Boolean value which, if true, includes a scripts/ directory (at the
same level as lib/ or t/). (Default is on.)
- •
- INCLUDE_WARNINGS
Boolean value which, if true, inserts "use warnings;" in all Perl
modules created by use of this module. (Default is off.)
- •
- INCLUDE_ID_LINE
Boolean value which, if true, inserts "#$Id$" in all Perl modules
created by use of this module for the purpose of inserting a Subversion
file 'Id' string. (Default is off.)
- •
- Arguments Related to the Module's Author
- •
- AUTHOR
Name of the author. If the author's name contains an apostrophe
("'"), then the corresponding value in the list passed to the
constructor must be double-quoted; otherwise Makefile.PL gets
messed up. (Defaults to dummy copy.)
- •
- EMAIL
Email address of the author. If the author's e-mail address contains an
apostrophe ("'"), then the corresponding value in the list
passed to the constructor must be double-quoted; otherwise
Makefile.PL gets messed up. (Defaults to dummy copy.)
- •
- CPANID
The CPANID of the author. If this is omitted, then the line will not be
added to the documentation. (Defaults to dummy copy.)
- •
- WEBSITE
The personal or organizational website of the author. If this is omitted,
then the line will not be added to the documentation. (Defaults to dummy
copy.)
- •
- ORGANIZATION
Company or group owning the module. If this is omitted, then the line will
not be added to the documentation. (Defaults to dummy copy.)
- •
- Argument Related to Multiple Modules within a Distribution
- •
- EXTRA_MODULES
A reference to an array of hashes, each of which contains values for
additional modules in the distribution.
$mod = ExtUtils::ModuleMaker->new(
NAME => 'Alpha::Beta',
EXTRA_MODULES => [
{ NAME => 'Alpha::Beta::Gamma' },
{ NAME => 'Alpha::Beta::Delta' },
{ NAME => 'Alpha::Beta::Gamma::Epsilon' },
],
);
As with the primary module, the only attribute required for each extra
module is "NAME". Other attributes may be supplied but the
primary module's values will be used if no value is given here.
Each extra module will be created in the correct relative place in the
lib directory. By default, a test file will also be created in the
t directory corresponding to each extra module to test that it
loads properly. (See EXTRA_MODULES_SINGLE_TEST_FILE below to learn how to
change this behavior.) However, no other supporting documents (
e.g., README, Changes) will be created.
This is one major improvement over the earlier h2xs as you can now
build multi-module packages.
- •
- Arguments Related to Test Files
- •
- FIRST_TEST_NUMBER
A non-negative natural number from which the count begins in test files that
are numerically ordered. (Default is 1.)
- •
- TEST_NUMBER_FORMAT
In test files that are numerically ordered, a Perl "sprintf"
formatting string that specifies how FIRST_TEST_NUMBER is to be formatted.
(Default is "%03d".)
- •
- TEST_NAME
String forming the core of the name of a test file. (Default is
"load").
- •
- TEST_NAME_DERIVED_FROM_MODULE_NAME
Boolean value which, when true, tells ExtUtils::ModuleMaker to create a file
in the test suite with a name derived from the .pm package it is
testing, thereby overriding any value set in the TEST_NAME attribute. For
example, for a module called 'Alpha::Sigma::Tau', a test file named
t/Alpha_Sigma_Tau.t will be created. (Default is off.)
- •
- TEST_NAME_SEPARATOR
String holding the character which joins components of a test file's name,
e.g., the character used to join 001 and <load> in a file
named 001_load.t. (Defaults to an underscore "_".)
- •
- EXTRA_MODULES_SINGLE_TEST_FILE
Boolean value which, when true and when extra modules have been specified in
the EXTRA_MODULES attribute, will put tests for those extra modules in a
single test file rather than in individual test files corresponding to
each module. (Default is off.)
- •
- INCLUDE_POD_COVERAGE_TEST
Boolean value which, if true, causes a test file called
t/pod-coverage.t to be included in the t/ directory. This
test is advocated by some Perl quality assurance experts and module
authors. However, since the maintainer of ExtUtils::ModuleMaker is not
persuaded of its worth, default is off.
- •
- INCLUDE_POD_TEST
Boolean value which, if true, causes a test file called t/pod.t to be
included in the t/ directory. This test is advocated by some Perl
quality assurance experts and module authors. However, since the
maintainer of ExtUtils::ModuleMaker is not persuaded of its worth, default
is off.
- •
- INCLUDE_FILE_IN_PM
String holding a path to a file containing Perl code and/or documentation
which will be included in each lib/*.pm file created in a
particular distribution. By default, such content is placed after any
constructor and before the main POD block. This could, for example, be
used to insert stub subroutines in each package within a distribution.
Default is off.
- •
- Arguments for Advanced Usages
- •
- INTERACTIVE
Activates interactive mode in modulemaker utility. The interactive
mode presents the user with a series of menus from which the user selects
features by entering text at the command prompt. This attribute should
only be used by interactive scripts like modulemaker. (Default is
off.)
- •
- ALT_BUILD
Name of a Perl package holding methods which override those called withiin
"complete_build" to shape the content of files created by using
ExtUtils::ModuleMaker. See "An Alternative Approach to
Subclassing" below.
"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?
- •
- "NAME"
You cannot enter a default value for "NAME": the name of the
module you are creating. ExtUtil::ModuleMaker's own defaults file omits a
value for "NAME" to prevent you from overwriting an already
existing module. (More precisely, the default value is an empty string.
ExtUtil::ModuleMaker will throw an error if you attempt to create a module
whose name is empty.) This precaution applies to your personal defaults
file as well.
- •
- "ABSTRACT"
Since every module you create presumably has its own unique purpose, every
module must have a unique "ABSTRACT" to summarize that purpose.
ExtUtil::ModuleMaker supplies the following string as the default value
for the "ABSTRACT" key:
Module abstract (<= 44 characters) goes here
... a string which, not coincidentally, happens to be exactly 44 characters
long -- so you can just overstrike it. This will be the default value for
"ABSTRACT" in any Personal/Defaults.pm file you create as
well.
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¶
- •
- Tests Require Perl 5.6
While the maintainer has attempted to make the code in
lib/ExtUtils/Modulemaker.pm and the modulemaker utility
compatible with versions of Perl older than 5.6, the test suite currently
requires 5.6 or later. The tests which require 5.6 or later are placed in
SKIP blocks. Since the overwhelming majority of the tests do
require 5.6, running the test suite on earlier Perl versions won't report
much that is meaningful.
- •
- Testing of modulemaker's Interactive Mode
The easiest, laziest and recommended way of using this distribution is the
command-line utility modulemaker, especially its interactive mode.
However, this is necessarily the most difficult test, as its testing would
require capturing the STDIN, STDOUT and STDERR for a process spawned by a
"system('modulemaker')" call from within a test file. For now,
the maintainer has relied on repeated visual inspection of the screen
prompts generated by modulemaker. With luck, Expect-based
tests will be available in a future version.
- •
- Testing modulemaker on Non-*nix-Like Operating Systems
Since testing the modulemaker utility from within the test suite
requires a "system()" call, a clean test run depends in part on
the way a given operating system parses command-line arguments. The
maintainer has tested this on Darwin and Win32 and, thanks to a suggestion
by A. Sinan Unur, solved a problem on Win32. Results on other operating
systems may differ; feedback is welcome.
TO DO¶
- •
- Tests for modulemaker's interactive mode.
- •
- Possible new "USE_AS_BASE" attribute which would insert modules
from which user's new module will inherit.
USE_AS_BASE => [ qw|
Template::Toolkit
Module::Build
Lingua::Romana::Perligata
Acme::Buffy
| ],
Such an attribute would require replacement copy for
"ExtUtils::ModuleMaker::StandardText::block_begin()".
- •
- Creation of a mailing list for ExtUtils::ModuleMaker.
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>.
Development repository: <
https://github.com/jkeenan/extutils-modulemaker>
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-2014 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.