ExtUtils::ModuleMaker

[simonflk]

Item Description: an h2xs replacement for non-XS modules

Review Synopsis:

ExtUtils::ModuleMaker vs h2xs

ExtUtils::ModuleMaker is a replacement for h2xs. So what's wrong with h2xs anyway and how does ExtUtils::ModuleMaker perform any better?

h2xs -AXn Foo::Bar

My annoyances with h2xs (these are purely personal):

• by default: it produces code that isn't backwards compatible [see note] (our instead of use vars, use warnings, and use 5.00?)
• you have extra work if you have more than one module in the distribution
• you have lots of editing to do before you get started, (unless your name is A. U. Thor)
• module code and tests are all dumped into the main directory

On reflection, these seem quite petty -- but I am very lazy.

perl -MExtUtils::ModuleMaker -e "Quick_Module ('Foo::Bar')"

This is more to type, and produces similar results to h2xs. However there are the following improvements:

• module files are neatly stored in a "lib" folder
• test file is created in "t" subfolder
• LICENSE file is included - defaults to perl license (GPL & Artistic)
• lib/Foo/Bar.pm is backwards compatible with perl 5.005
• useful pod sample for documenting subroutines

Advanced use of ExtUtils::ModuleMaker

The QuickModule() function still leaves A.U. Thor as the author of your work and other defaults and leaves you with only one module in your distribution. Use Generate_Module_Files() for a more complete solution...

Generate_Module_Files()

• Specify author details, (fills in the pod, Makefile.PL, etc)
• Specify version number to start on
• Specify the license that your module is released under (over 20 licenses included - or use custom)
• Create module and test files for additional modules

Here is my code using ExtUtils::ModuleMaker that allows me to be extra lazy:

#!/usr/bin/perl5.6.1 -w
use strict;
use Getopt::Long;
use ExtUtils::ModuleMaker;

my %author = 
(
  NAME => 'Simon Flack',
  EMAIL => '[e-mail]',
  CPANID => 'SIMONFLK',
  WEBSITE => 'http://www.simonflack.com',
);

# Set some defaults
my $license = 'perl';
my $version = '0.1';
my $module_name = '';
my $extra_modules = '';
my @extra_modules = ();

GetOptions
(
  'name=s' => \$module_name, 
  'version:f' => \$version, 
  'license:s' => \$license, 
  'extra:s'=> \$extra_modules
);

Usage() unless $module_name;

######################################################################
+#########
# Now make the module
######################################################################
+#########

push @extra_modules, {NAME => $_, ABSTRACT => $_}
    for split /,/, $extra_modules;

Generate_Module_Files
(
 NAME => $module_name,
 ABSTRACT => $module_name,
 AUTHOR => \%author,
 VERSION => $version,
 LICENSE => $license,
 EXTRA_MODULES => \@extra_modules,
);


sub Usage
{
    my ($prog) = $0 =~ /\/([^\/]+)$/;
print <<HELP;
$prog - Simple Module Maker

Usage: $prog <-name ModuleName> [-version=?] [-extra=?,?] [-license=?]

Eg:    $prog -name My::Module
       $prog -name My::Module -version 0.11
                    -extra My::Utils,My::Extra -license perl

HELP
}

Now I can write: "newmodule -n Foo::Bar -v 1.0 -l gpl" and I can start coding and writing tests straight away...

Note: If you use this, don't forget to change the author info.

Problems with ExtUtils::ModuleMaker

There aren't many.

• ExtUtils::ModuleMaker won't be helpful if you are writing XS modules. You should stick to h2xs for this, probably.
• The .pm files it creates encourage inline pod for documenting subroutines. I know a lot of people do this, but I prefer putting my pod at the bottom.
• The test files are obscurely named, you'll probably want to rename them.

Reference:

See the following docs for more information about writing modules

ExtUtils::ModuleMaker
perlnewmod
perlmod
perlmodlib
Makefile.PL best practices by Matts
How to make a CPAN Module Distribution by tachyon
Simple Module Tutorial by tachyon
Make.pm A perl make. I prefer this to nmake on win32. pmake dist works. do "ppm install make"

update: h2xs compatibility
crazyinsomniac pointed out that h2xs has a backwards compatibility option "-b" I couldn't find this documented and it didn't work when I tried it (my v5.6.0 h2xs is higher up in the PATH than my 5.6.1 h2xs). It seems that is is a new option since perl5.6.1. I'll leave my original statement in here because it will still apply to some people on older perls. Thanks to crazyinsomniac for pointing out this option.