modulereview
simonflk
<h2>ExtUtils::ModuleMaker vs h2xs</h2>
<p>[cpan://ExtUtils::ModuleMaker] is a replacement for h2xs. So what's wrong with h2xs
anyway and how does ExtUtils::ModuleMaker perform any better?</p>
<ul>
<h3>h2xs -AXn Foo::Bar</h3>
<p>My annoyances with h2xs (these are purely personal):
<ul>
<li>by default: it produces code that isn't backwards compatible [<a href="#h2xscompat">see note</a>] (our instead of use vars, use warnings, and use 5.00?)</li>
<li>you have extra work if you have more than one module in the distribution</li>
<li>you have lots of editing to do before you get started, (unless your name is A. U. Thor)</li>
<li>module code and tests are all dumped into the main directory</li>
</ul>
</p>
<p>On reflection, these seem quite petty -- but I am very lazy. </p>
<h3>perl -MExtUtils::ModuleMaker -e "Quick_Module ('Foo::Bar')"</h3>
<p>This is more to type, and produces similar results to h2xs. However there are the following improvements:
<ul>
<li>module files are neatly stored in a "lib" folder</li>
<li>test file is created in "t" subfolder</li>
<li>LICENSE file is included - defaults to perl license (GPL & Artistic)</li>
<li>lib/Foo/Bar.pm is backwards compatible with perl 5.005</li>
<li>useful pod sample for documenting subroutines</li>
</ul>
</p>
</ul>
<h2>Advanced use of ExtUtils::ModuleMaker</h2>
<p>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...</p>
<ul>
<p><b>Generate_Module_Files()</b>
<ul>
<li>Specify author details, (fills in the pod, Makefile.PL, etc)</li>
<li>Specify version number to start on</li>
<li>Specify the license that your module is released under (over 20 licenses included - or use custom)</li>
<li>Create module and test files for additional modules</li>
</ul>
</p>
</ul>
<p>Here is my code using ExtUtils::ModuleMaker that allows me to be extra lazy:</p>
<code>
#!/usr/bin/perl5.6.1 -w
use strict;
use Getopt::Long;
use ExtUtils::ModuleMaker;
my %author =
(
NAME => 'Simon Flack',
EMAIL => 'simonflk@example.com',
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
}
</code>
<p>Now I can write: "<tt>newmodule -n Foo::Bar -v 1.0 -l gpl</tt>" and I can start coding and
writing tests straight away...</p>
<p><b>Note: </b>If you use this, don't forget to change the author info.</p>
<h2>Problems with ExtUtils::ModuleMaker</h2>
<p>There aren't many.
<ul>
<li>ExtUtils::ModuleMaker won't be helpful if you are writing XS modules. You should stick to h2xs for this, probably.</li>
<li>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.</li>
<li>The test files are obscurely named, you'll probably want to rename them.</li>
</ul>
</p>
<h2>Reference:</h2>
<p>See the following docs for more information about writing modules</p>
<ul>
[cpan://ExtUtils::ModuleMaker]<br/>
[perldoc://perlnewmod]<br/>
[perldoc://perlmod]<br/>
[perldoc://perlmodlib]<br/>
[http://use.perl.org/~Matts/journal/1707|Makefile.PL best practices] by [Matts]<br/>
[id://159044|How to make a CPAN Module Distribution] by [tachyon]<br/>
[id://102347|Simple Module Tutorial] by [tachyon]<br/>
[http://search.cpan.org/search?dist=Make|Make.pm] A perl make. I prefer this to nmake on win32. pmake dist works. do "<tt>ppm install make</tt>"
</ul>
<p><b>update: </b><a name="h2xscompat">h2xs compatibility</a><br/>
[crazyinsomniac] pointed out that h2xs has a backwards compatibility option "-b" [perldoc://h2xs|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.</p>
an h2xs replacement for non-XS modules