14.6.1. Packaging for CPAN

Now create a file named Makefile.PL, containing these lines:

use ExtUtils::MakeMaker;

my $pm = 'NavListbox';

WriteMakefile(
    NAME          => "Tk::$pm",
    DISTNAME      => "Tk-$pm",
    VERSION_FROM  => "$pm.pm",
    dist          => {COMPRESS => 'gzip', SUFFIX => 'gz'},
    ($] >= 5.005 ?
        (ABSTRACT => 'Navigatible Listbox',
         AUTHOR   => 'Flaz T. Bizzo ([email protected])') : ( ),
    ),
);

% perldoc ExtUtils::MakeMaker

The minimum attributes we require are:

NAME

The actual module name.

DISTNAME

The distribution tar filename.

VERSION_FROM

The name of the file containing the module's version information. We've always included it in the module itself.

dist

The distribution is compressed with gzip and given the extension .gz.

ABSTRACT

The description line from the module list entry.

AUTHOR

Who wrote the module.

The last two attributes, particularly important for modules destined for a PPM archive, are conditional, because they weren't available prior to Perl 5.005.

To complete our distribution, we need two more files—MANIFEST, which lists all the filenames in the distribution, and test.pl, a Perl program for the make test phase—for a total of four files: NavListbox.pm, Makefile.PL, MANIFEST, and test.pl.

This configuration will likely work, but instead of using ExtUtils::MakeMaker::WriteMakefile, we should use its Tk counterpart, Tk::MMutil::TkExtMakefile.

As it happens, without even resorting to trickery, an improved Makefile.PL program using TkExtMakefile can do several more things:

• Create the MANIFEST file automatically.

• Create the test.pl file automatically.

Add an optional sample program to widget's User Contributed Demonstrations section. widget is a Perl/Tk program that demonstrates most of the toolkit's capabilities and is installed in your normal Unix or Win32 path. It's a multisection hypertext application that contains a special User Contributed Demonstrations section for highlighting nonstandard toolkit features. You can use the following special Makefile.PL to include a special demonstration of your new widget. For our purposes, this optional fifth file—the "widget contributed" (widtrib) demonstration file—is included.

Here's the widtrib file, navtest.pl:

# A NavListbox sample program.
use Tk;
use Tk::NavListbox;
use strict;

my $mw = MainWindow->new;
my $nlb = $mw->NavListbox->pack;
for (qw/one two three four five six seven eight none ten/) {
    $nlb->insert('end', $_);
}
MainLoop;

Our new Makefile.PL first writes the MANIFEST file containing the names of the four archive files plus the widtrib demonstration file, then writes test.pl after first substituting our module's name in the template.

# A generic Makefile.PL file for any pure Perl/Tk mega-widget. Set
# $pm to the name of the Perl module, and update %widinfo.  Leave
# $widtrib undefined unless you have an addition for widget's User
# Contributed Demonstrations section.
#
# This program creates the MANIFEST and test.pl files, then invokes
# MakeMaker to create the Makefile.  [email protected], 2001/01/01

use Tk::MMutil;
use vars qw/$pm $widinfo $widtrib %widtrib/;

$pm = 'NavListbox';             # widget Class name
%widinfo = (                    # PPM widget information
    ABSTRACT => 'Navigatible Listbox',
    AUTHOR   => 'Nancy Walsh ([email protected])',
);
$widtrib = 'navtest.pl';        # widtrib demo file name

print "Writing MANIFEST for Tk::$pm\n";
open MANIFEST, ">MANIFEST" or die "Cannot open MANIFEST: $!";
print MANIFEST <<"end-of-manifest";
MANIFEST
Makefile.PL
$pm.pm
test.pl
end-of-manifest
print MANIFEST "$widtrib\n" if $widtrib;
close MANIFEST or die $!;

print "Writing test.pl for Tk::$pm\n";
open TEST, ">test.pl" or die "Cannot open test.pl: $!";
while (<DATA>) {
    s/NavListbox/$pm/o;
    print TEST;
}
close TEST or die $!;

%widtrib = 
  ($widtrib => "\$(INST_ARCHLIB)/Tk/demos/widtrib/$widtrib") if $widtrib;

Tk::MMutil::TkExtMakefile(
    NAME          => "Tk::$pm",
    DISTNAME      => "Tk-$pm",
    VERSION_FROM  => "$pm.pm",
    PM            => {"$pm.pm" => "\$(INST_LIBDIR)/$pm.pm", %widtrib},
    dist          => {COMPRESS => 'gzip', SUFFIX => 'gz'},
    ($] >= 5.005 ? %widinfo  : ( )),
);
__DATA__
#!perl -w
use Test;
use strict;

BEGIN { plan tests => 12 };

eval { require Tk; };
ok($@, "", "loading Tk module");

my $mw;
eval {$mw = Tk::MainWindow->new( );};
ok($@, "", "can't create MainWindow");
ok(Tk::Exists($mw), 1, "MainWindow creation failed");
eval { $mw->geometry('+10+10'); };

my $w;
my $class = 'NavListbox';

print "Testing $class\n";

eval "require Tk::$class;";
ok($@, "", "Error loading Tk::$class");

eval { $w = $mw->$class( ); };
ok($@, "", "can't create $class widget");
skip($@, Tk::Exists($w), 1, "$class instance does not exist");

if (Tk::Exists($w)) {
    eval { $w->pack; };

    ok ($@, "", "Can't pack a $class widget");
    eval { $mw->update; };
    ok ($@, "", "Error during 'update' for $class widget");

    eval { my @dummy = $w->configure; };
    ok ($@, "", "Error: configure list for $class");
    eval { $mw->update; };
    ok ($@, "", "Error: 'update' after configure for $class widget");

    eval { $w->destroy; };
    ok($@, "", "can't destroy $class widget");
    ok(!Tk::Exists($w), 1, "$class: widget not really destroyed");
} else  { 
    for (1..5) { skip (1,1,1, "skipped because widget couldn't be created"); }
}

1;

So now we have three files, NavListbox.pm, navtest.pl, and Makefile.PL, in an otherwise empty directory. Type this:

% perl Makefile.PL
% make

This automatically creates MANIFEST and test.pl for us. Now type this:

% make test

14.6.2. Packaging for PPM