Generally when you need to load a module, you use it:

use My::Number::Utilities;

The use statement has a variety of different uses and these can be a bit confusing.

use VERSION
use Module VERSION LIST
use Module VERSION
use Module LIST
use Module

The use VERSION form tells Perl that it must use a minimum version of Perl. This being Perl, there are a variety of different formats for the version number. So if you want to declare that your code requires Perl version 5.8.1 or above:

use v5.8.1;
use 5.8.1;
use 5.008_001;

If you require Perl version 5.9.5 or above, all features available via use feature will be loaded. Thus, instead of saying:

use feature "say";
# or
use feature ":5.12";

You can say:

use v5.12.0;

Prefixing the number with a v (as in v5.12.0) requires a 3-part number and it’s called a version string, or v-string. They have some issues and not everyone likes them. See “Version Strings” in perldoc perldata.

use Module
use Module LIST
use Module VERSION
use Module VERSION LIST

Many times you use a module with:

use Test::More;

Test::More is used in testing your code (Chapter 14, Testing). You may find that you enjoy the subtest() feature of Test::More, but it’s not available until version 0.96, so you can assert that you need at least that version of Test::More:

use Test::More 0.96;
# or
use Test::More v0.96.0;

use Some::Module  .32;  # Syntax error, do not use!
use Some::Module 0.32;  # Properly asserting the version

When Perl loads Test::More, if its version is less than the supplied version, it will automatically croak().

Test::More accepts an import list. When you use a module, Perl automatically looks for a function in that module named import() and, if it’s found, it will call it for you, passing in any arguments included in the import list when you use the module. So you might use Test::More like this:

use Test::More tests => 13;

Then, the list tests, 13 will be passed as arguments to Test::More::import().

Finally, you can combine the version check and import list:

use Test::More 0.96 tests => 13;

That tells Perl that Test::More must be version 0.96 or better and passes the arguments tests and 13 to the import method.

# Don't export Dumper() into our namespace
use Data::Dumper ();

You can also require a module:

require My::Number::Utilities;

The use statement happens are compile time, even if it’s embedded in a code path which would not normally be executed. The require happens are runtime. Normally loading a module with use is what you need. However, sometimes you want to delay loading a module if you don’t need it. For example, if you want to debug output with Data::Dumper, it automatically exports the Dumper() subroutine (unless you use Data::Dumper ()).

use Data::Dumper;
print Dumper($some_variable);

However, sometimes you don’t want to load Data::Dumper unless there’s a problem. You might wrap this in a subroutine and use require.

sub debug {
    my @args = @_;
    require Data::Dumper;
    warn Data::Dumper::Dumper(\@args);
}

With the debug() subroutine, Data::Dumper will never be loaded unless debug() is called. Because it’s loaded with require and not use, Data::Dumper’s import() method is not called, so you must call Dumper() with it’s fully-qualified subroutine name: Data::Dumper::Dumper().

Up to now we’ve primarily seen lexically scoped variables declared with the my builtin:

my $foo;
my @bar;
my %baz;

Those are file or block scoped and not visible elsewhere. However, sometimes you want a variable to be seen by other packages. To enable the visibility you need to use fully-qualified package variables (variables with a package name prefixed to them) or declare the variables with our. The our builtin is like my, but it’s for package variables and not lexically scoped ones.

For example, the Data::Dumper module let’s you control much of its behavior with package variables:

use Data::Dumper;
# sort hash keys alphabetically
local $Data::Dumper::Sortkeys = 1;
# tighten up indentation
local $Data::Dumper::Indent   = 1;
print Dumper(\%hash);

Typing long package names like can be frustrating and you author repeatedly types $Data::Dumper::SortKeys = 1 and then tries to figure out what went wrong. Fortunately, Data::Dumper provides an alternate, cleaner interface, so we recommend reading the documentation.

You would use a package variable when you need a variable that other packages can access using its fully qualified name. We will explain in a bit why this is usually a bad idea, but for now, here’s how you might declare them.

package My::Number::Utilities;
use strict;
use warnings;
our $VERSION = 0.01;
$My::Number::Utilities::PI  = 3.14159265351;
$My::Number::Utilities::E   = 2.71828182846;
$My::Number::Uitlities::PHI = 1.61803398874; # golden ratio
@My::Number::Utilities::FIRST_PRIMES = qw(
  2  3  5  7 11 13 17 19 23 29
 31 37 41 43 47 53 59 61 67 71
);
sub is_prime {
    #
}
1;

As you can see, we’ve declared several package variables, but the sharp-eyed amongst our readers may have noticed the problem. The $My::Number::Uitlities::PHI variable has a misspelled package name. Oops!

Instead, you use the our declaration to omit the package name.

our $PI  = 3.14159265351;
our $E   = 2.71828182846;
our $PHI = 1.61803398874; # golden ratio
our @FIRST_PRIMES = qw(
  2  3  5  7 11 13 17 19 23 29
 31 37 41 43 47 53 59 61 67 71
);

Versions of Perl prior to version 5.6.1 did not have the our builtin, so they used the vars pragma instead.

use vars qw($PI $E $PHI @FIRST_PRIMES);
$PI  = 3.14159265351;
$E   = 2.71828182846;
$PHI = 1.61803398874; # golden ratio
@FIRST_PRIMES = qw(
  2  3  5  7 11 13 17 19 23 29
 31 37 41 43 47 53 59 61 67 71
);

Today if you must use package variables, it is recommended that you use the our builtin instead of the vars pragma.

So what’s wrong with package variables?

package Universe::Roman;
use My::Number::Utilities;
$My::Number::Utilities::PI = 3;

And all the other universes fall apart. The proper way to do that is:

package Universe::Roman;
use My::Number::Utilities;
local $My::Number::Utilities::PI = 3;

However, since you can’t force other packages to declare your package variables with local, it’s better to just provide a subroutine that encapsulates this value:

package My::Number::Utilities;
use strict;
use warnings;
our $VERSION = 0.01;
sub pi { 3.14159265351 }
And now the value of PI is read-only.
package Universe::Roman;
use My::Number::Utilities;
my $PI = My::Number::Utilities::pi();

package Foo;
use strict;
use warnings;
our ( $THIS, $THAT, $OTHER ) = qw( foo bar baz );

my ( $THIS, $THAT, $OTHER ) = qw( foo bar baz );

We repeat: do not package variables unless absolutely necessary. There is one clear exception: declaring version numbers.

You’ll notice in our My::Number::Utilities module, we declared a version number with our:

our $VERSION = 0.01;

While not strictly needed, it’s strongly recommended that you declare a version number for your modules. Thus, if your Time::Dilation module version 2.3 has a bug and you release version 2.4, programmers who wish to avoid your bug can do this:

use Time::Dilation 2.4;

When you assert a version of a module in a use statement, Perl will check the package variable $Module::Name::VERSION and throw an exception if the version is lower than the version needed.

If you do not provide a version number for the module, it makes life difficult for other developers trying to use your code. As a general rule, the version declaration we’ve shown above should be sufficient for your needs, but some argue for the following:

our $VERSION = '0.001';   # make sure it's in quotes!
$VERSION = eval $VERSION;

David Golden has an excellent description of why this is the preferred way to write version numbers:

http://www.dagolden.com/index.php/369/version-numbers-should-be-boring/

In short, it allows Perl’s version number to always be considered the same regardless of how the module is being used, such as when the $VERSION is parsed for a CPAN upload or which version of Perl you are using. The full reasons are beyond the scope of this book, but it’s worth reading David Golden’s writing on this topic.

Let’s look at our My::Number::Utilities package again:

package My::Number::Utilities;
use strict;
use warnings;
our $VERSION = 0.01;
sub  pi() { 3.14166 }  # good enough for 2,000 year old aqueducts and bridges
sub is_prime {
    my $number = $_[0];
    return   if $number < 2;
    return 1 if $number == 2;
    for ( 2 .. int sqrt($number) ) {
        return if !($number % $_);
    }
    return 1;
}
1;

Others using this package are going to get annoyed at typing My::Number::Utilities::pi() and My::Number::Utilities::is_prime() every time they want to use those functions, so you can export those functions to the calling code’s namespace. The most popular module for doing this is Exporter, which has shipped with Perl since version 5. Here’s another case where you need to use package variables because Exporter’s interface requires it.

Near the top of module code you review, you’ll often see the following:

use base 'Exporter';
our @EXPORT_OK = qw(pi is_prime);
our %EXPORT_TAGS = ( all => \@EXPORT_OK );

This means that those functions, pi() and is_prime(), can be exported. Now, when someone wants to use your module, they can import those functions by specifying their names in the import list:

use My::Number::Utilities 'pi', 'is_prime';

Or if they prefer, they can only import the functions they want:

use My::Number::Utilities 'is_prime';
print is_prime($number)
  ? "$number is prime"
  : "$number is not prime";

When you use base 'Exporter', you are inheriting from the Exporter module (we’ll cover inheritance in Chapter 12, Object Oriented Perl. For now, just follow along). When someone uses your module, the Exporter::import() function is called. It uses your module name and finds the @EXPORT, @EXPORT_OK and %EXPORT_TAGS package variables to determine what functions can be exported. Only function names in @EXPORT_OK and @EXPORT can be exported, but using @EXPORT is usually not recommended because @EXPORT exports all the functions listed in the array and the programmer using your module no longer has control over what is imported into their namespace. It’s no fun accidentally importing a build() function and overwriting the build() function you have in your namespace.

use Exporter 'import';

With the above code, if a programmer wants all of the functions, they can ask for that with :all.

use My::Number::Utilities ':all';

The %EXPORT_TAGS package hash has key/value pairs specifying groups of functions that can be exported. When using your module, a developer uses a key name from %EXPORT_TAGS, prefixed with a colon, :, to say the they want that group of functions.

So if your My::Number::Utilities module has subroutines for mathematical constants such as pi, e and phi, you can allow those to be imported separately from the :all tag:

our %EXPORT_TAGS = qw(
    all       => \@EXPORT_OK,
    constants => [qw(ph e phi)],
);

sub pi() { 3.14159265351 }

use My::Number::Utilities 'pi';
print pi;

use My::Number::Utilities 'pi';
print 3.14159265351;

And someone who just wants the constants and not the is_prime() function can ask for them:

use My::Number::Utilities ':constants';

Note that you’ll often see the constant pragma used to declare constants. These can be exported just like any other subroutine because they’re just created as subroutines with null prototypes.

our @EXPORT_OK = qw(PI E PHI);
use constant PI  => 3.14159265351;
use constant E   => 2.71828182846;
use constant PHI => 1.61803398874;

Though Exporter is the most common way of exporting functions into other namespaces, modules such as Exporter::NoWork, Perl6::Export and others exist for those who do not care for the Exporter syntax. See a CPAN near you for the latest and greatest alternatives.

You’ve seen that subroutines representing constants are often UPPER CASE subroutines, but what about other functions?

For a function that other modules are allowed to use, a normal function name is standard:

sub unique {
    #
}

However, for subroutines you wish to remain private, by convention those are prefixed with an underscore:

sub _log_errors {
    #
}

While a developer may know about those subroutines, they also know that they should not rely on them. This is no guarantee that they won’t try to use these subroutines, but a good developer knows that they should not. Perl doesn’t try to rigorously enforce privacy by default. You’re expected to behave yourself.

package Really::Private;
use strict;
use warnings;
our $VERSION = '0.01';
use Carp 'croak';

my $is_arrayref_of_hashrefs = sub {
    my $arg = shift;
    # is it an array ref?
    return unless 'ARRAY' eq ref $arg;
    # return boolean indicating if all elements are hashrefs.
    return scalar @$arg == scalar grep { 'HASH' eq ref $_ } @$arg;
};

sub process_records {
    my ( $records ) = @_;
    unless ( $is_arrayref_of_hashrefs->($records) ) {
        croak "process_records() requires an array ref of hashrefs";
    }
    # process records here
}
1;

sub is_prime { ... }

Also, you’re strongly urged to use_underscores_to_separate_names insteadOfUpperCaseLetters. Underscores are much easier to read, particularly if English is not your first language.

Try it out Distance Conversion

Example 11-1

We’re going to write a module with six functions:

• miles_to_yards

• yards_to_miles

• miles_to_feet

• feet_to_miles

• miles_to_inches

• inches_to_miles

Each of these functions is exported only if requested, or all may be requested at once.

1. In lib/Conversion/Distance/Imperial.pm, type the following code:

   package Convert::Distance::Imperial;
   use strict;
   use warnings;
   use diagnostics;
   our $VERSION = '0.001';
   $VERSION = eval $VERSION;
   use Exporter 'import';
   our @EXPORT_OK = qw(
     miles_to_yards
     yards_to_miles
     miles_to_feet
     feet_to_miles
     miles_to_inches
     inches_to_miles
   );
   our %EXPORT_TAGS = ( all => \@EXPORT_OK );
   use constant FEET_PER_MILE   => 5_280;
   use constant FEET_PER_YARD   => 3;
   use constant INCHES_PER_FOOT => 12;
   sub miles_to_yards {
       my $miles = shift;
       return miles_to_feet($miles) / FEET_PER_YARD;
   }
   sub yards_to_miles {
       my $yards = shift;
       return feet_to_miles( $yards * FEET_PER_YARD );
   }
   sub miles_to_feet {
       my $miles = shift;
       return $miles * FEET_PER_MILE;
   }
   sub feet_to_miles {
       my $feet = shift;
       return $feet / FEET_PER_MILE;
   }
   sub miles_to_inches {
       my $miles = shift;
       return miles_to_feet($miles) * INCHES_PER_FOOT;
   }
   sub inches_to_miles {
       my $inches = shift;
       return feet_to_miles( $inches / INCHES_PER_FOOT );
   }
   1;

2. Create a program, convert.pl, with the following code.

   use strict;
   use warnings;
   use diagnostics;
   use lib 'lib';
   use convert::distance::imperial ':all';
   printf "there are %d yards in a mile\n"  => miles_to_yards(1);
   printf "there are %d feet in a mile\n"   => miles_to_feet(1);
   printf "there are %d inches in a mile\n" => miles_to_inches(1);
   printf "there are %0.2f miles in a %d yards\n"  => yards_to_miles(5000),  5000;
   printf "there are %0.2f miles in a %d feet\n"   => feet_to_miles(5000),   5000;
   printf "there are %0.2f miles in a %d inches\n" => inches_to_miles(5000), 5000;

   If you have created this in the same directory you created the lib/My/Number/Utilities.pm and the primes.pl program from Example 11.1, “A simple module”, you should have the following directory structure, as output from tree.pl:

   |--convert.pl
   |  lib/
   |  |  Convert/
   |  |  |  Distance/
   |  |  |  |--Imperial.pm
   |  |  My/
   |  |  |  Number/
   |  |  |  |--Utilities.pm
   |--primes.pl

   Note

   convert.pl and lib/Convert/Distance/Imperial.pm available for download at Wrox.com.

3. Run the program with perl convert.pl. You should see the following output:

   There are 1760 yards in a mile
   There are 5280 feet in a mile
   There are 63360 inches in a mile
   There are 2.84 miles in a 5000 yards
   There are 0.95 miles in a 5000 feet
   There are 0.08 miles in a 5000 inches

By an astonishing stroke of luck, those numbers turn out to be correct.

How it works

We start with the standard strict, warnings, and diagnostics (though at this point, you could probably do without diagnostics and figure out what’s going on). Then we have our use lib line:

use lib 'lib';

This tells Perl that before searching for modules in @INC, check the lib/ directory. If you had several extra places you wanted Perl to look for modules, could pass them all to lib’s import list:

use lib 'lib', 'mylib', 'other/lib';

Next, we set up our subroutine exporting with the following:

use Exporter 'import';
our @EXPORT_OK = qw(
  miles_to_yards
  yards_to_miles
  miles_to_feet
  feet_to_miles
  miles_to_inches
  inches_to_miles
);
our %EXPORT_TAGS = ( all => \@EXPORT_OK );

This will let you import any of those functions individually upon request, or in the case of our convert.pl program, we’ve imported them via the :all tag.

Next, we define several useful constants.

use constant FEET_PER_MILE   => 5_280;
use constant FEET_PER_YARD   => 3;
use constant INCHES_PER_FOOT => 12;

We could have simply typed these directly into our subroutines, but if we did something silly like mistakenly assume the there are 5,200 feet per mile, we’d have to change this value in several places. Instead, we use the constant pragma to create easy to read labels for each value and later, if we find one is in error, we only have to change it in one place.

Also, we could have declared our constants all in one go like this:

use constant {
    FEET_PER_MILE   => 5_280,
    FEET_PER_YARD   => 3,
    INCHES_PER_FOOT => 12,
};

Next we have the functions implementing our actual code. The miles_to_feet() and feet_to_miles() functions are actually our core functions here:

sub miles_to_feet {
    my $miles = shift;
    return $miles * FEET_PER_MILE;
}
sub feet_to_miles {
    my $feet = shift;
    return $feet / FEET_PER_MILE;
}

Those should be pretty clear. Each of them depends only on the FEET_PER_MILE constant and the value passed into it. Note that even when these subroutines are exported into your namespace, they can still reference the value in FEET_PER_MILE, despite it being defined in a different package.

Looking at other subroutines, such as miles_to_yards(), we see that they are defined in terms of miles_to_feet().

sub miles_to_yards {
    my $miles = shift;
    return miles_to_feet($miles) / FEET_PER_YARD;
}

We do this to make things more clear and to avoid repeating our miles to feet calculation.

The miles_to_yards() function relies on FEET_PER_YARD and miles_to_feet(). When exported, miles_to_yards() still knows about those and will return correct answers even if FEET_PER_YARD and miles_to_feet() are not exported. You can verify that by only exporting miles_to_yards() and see that it still works correctly:

use lib 'lib';
use Convert::Distance::Imperial 'miles_to_yards';
printf "There are %d yards in a mile\n"  => miles_to_yards(1);

BEGIN blocks fire during program compilation (Step 1), as soon as the trailing } is found. Ordinarily a print statement happens in Step 2, when the program is executed, so this:

BEGIN {
    print "This is the first BEGIN block\n";
}
print "The program is running\n";
BEGIN {
    print "This is the second BEGIN block\n";
}

Will print this:

This is the first BEGIN block
This is the second BEGIN block
The program is running

Note that if your program contains a syntax error after a BEGIN block, the BEGIN block will still execute because it is executed as soon as it is compiled and before the program finishes compiling. So this:

BEGIN {
    print "This is the first BEGIN block\n";
}
print "The program is running\n";
BEGIN {
    print "This is the second BEGIN block\n";
}
my $x =;

Will print something like this:

syntax error at /var/tmp/eval_GWUz.pl line 8, near "=;"
Execution of /var/tmp/eval_GWUz.pl aborted due to compilation errors.
This is the first BEGIN block
This is the second BEGIN block

Note that because STDERR and STDOUT are separate filehandles, they are not guaranteed to print in sequence, thus leading to this strange case where we may get the syntax error printed before we have the BEGIN block output printing. This is an artifact of how operating systems work and is not a flaw in Perl.

BEGIN blocks always execute in the order they are found.

use Module ();

BEGIN{ require Module; }

BEGIN blocks are useful for a variety of purposes, such as checking whether or not necessary files exist before the program runs or verifying that you are on the correct operating system.

END blocks are like BEGIN blocks, but they happen in Step 3, when the program is exiting. They will even be called if you die(), but signals and (the incredibly rare) segfaults can cause them to be skipped. They are useful if you need to clean anything up after your program finishes running.

They are executed in the reverse order that they are defined. Thus this:

END {
    print "This is the first END block\n";
}
END {
    print "This is the second END block\n";
}

Prints this:

This is the second END block
This is the first END block

When your program is done compiling but before it executes is when INIT, CHECK and UNITCHECK blocks fire. Because of this, unlike BEGIN blocks, they will not execute if there is a syntax error. A CHECK blocks runs immediately after Step 1 (compilation) is finished, in a LIFO (last in, first out) order. INIT blocks run after CHECK blocks and just before Step 2, the program execution. They run in the order they are defined (FIFO, first in, first out).

INIT {
    print "This is the first INIT block\n";
}
CHECK {
    print "This is the first CHECK block\n";
}
INIT {
    print "This is the second INIT block\n";
}
CHECK {
    print "This is the second CHECK block\n";
}

That prints out:

This is the second CHECK block
This is the first CHECK block
This is the first INIT block
This is the second INIT block

As you can see, the CHECK blocks run before the INIT blocks, in reverse order. The INIT blocks are run in the order defined.

UNITCHECK was introduced in Perl 5.9.5. They were designed to solve a problem where code that is loaded during program execution (such as with a require MODULENAME or a string eval) will not execute CHECK and INIT blocks. They would not be executed because those blocks only execute between compilation and execution, not during exection.

A UNITCHECK runs immediately after the code containing it is compiled, even if you are already in the program execution phase. This allows you to “check” necessary conditions before the containing code is executed.

Though the exact format varies, you’ll notice that most modules on the CPAN follow a documentation layout similar to the following (and generally in this order):

It is strongly recommended that you follow this format unless you have a strong reason not to. This makes your documentation consistent with other Perl modules and makes it easier to read. See the documentation for DBIx::Class for a good example of why you might want a slightly different format.

Other common sections include VERSION, DIAGNOSTICS, SEE ALSO (related modules) and CONTRIBUTORS (non-authors who’ve nonetheless offered useful feedback or patches).

The sections generally begin with a =head1 command paragraph.

=head1 NAME

Convert::Distance::Imperial - Convert imperial units to other units

=head1 VERSION

VERSION 0.001

=head1 SYNOPSIS

 use Convert::Distance::Imperial 'miles_to_inches';
 my $miles = miles_to_inches(453285);

POD, by default, supports 4 levels of headings:

The pod2html formatter, included with Perl, will render these as <h1>, <h2>, <h3> and <h4>, respectively. Other POD formatters will obviously make different choices. The ALL CAPS for the =head1 command is not strictly required for all POD formatters, but some require it, so you should probably stick with it.

A paragraph in POD, as mentioned, is merely text you type in a POD section. Note that there must be no whitespace at the start of any paragraph line.

=pod

This is a POD paragraph.

This is a second POD paragraph.

=cut

A list begins with =over indentlevel (typically the number 4), has one or more =item commands and ends with a =back command.

=over 4

=item * This is a list item

=item * This is a second list item.

This is an optional paragraph explaining the second list item.

=back

You may have an optional paragraph after an =item command. No =headn commands are allowed and while you might think that a nested list is handy, not all POD formatters respect them.

If you don’t want a bulleted list, you can create a numbered list manually. Use 1., 2., 3., etc., after each =item. Many POD parsers are weak in this area, so double check that your desired POD parser handles this correctly.

=over 4

=item 1. This is a list item

=item 2. This is a second list item.

This is an optional paragraph explaining the second list item.

=item 3.

=back

If you don’t want a bulleted or numbered list, just use =item followed by your desired list text.

The indentlevel is optional as it defaults to 4. Many POD formatters ignore it entirely, while others consider that to be the number of ems width of indent (an em is the with of the capital letter M in the base font of the document).

So why can’t we have any whitespace at the start of a line of normal POD paragraph? Because any text with a leading whitespace is rendered verbatim. This makes it very easy to insert code in your documentation.

=head1 SUBROUTINES

=head2 C<miles_to_yards>

 use Convert::Distance::Imperial 'miles_to_yards';
 my $yards = miles_to_yards($miles);
 print "$miles miles is $yards yards\n";

The C<miles_to_yards()> subroutines takes a number, in
miles, and returns a number, in yards.

We’ll explain that funky C<> stuff in just a bit.

With headings, paragraphs, lists and verbatim text, you now know most of the POD syntax people use. However, there are a few other commands we’ll take the time to explain. These are merely the most popular and you will want to read perldoc perlpod to understand what else you can do.

Sometimes you want to have a bit more control over the
output. It can be useful to have C<fixed-width text>,
B<bold> or I<italics> text. All paragraphs and some
command paragraphs allow formatting codes, also known
as I<interior sequences>. Here's how I might format this
paragraph in POD.

L<Read about formatting codes|perlpod/"Formatting Codes">

L<http://overseas-exile.blogspot.com/>

=encoding utf8

In the old days, people used a program that ships with Perl called h2xs, but it’s so old and out of date that we mention it just to say “don’t bother”. Today many people are using Dist::Zilla to create and install modules and while we recommend it, it’s beyond the scope of this book. Instead, we recommend that you start by installing Module::Starter from the CPAN. It will provide a module-starter program. Let’s create an installable version of our Convert::Distance::Imperial program.

module-starter --module=Convert::Distance::Imperial \
               --author='Curtis "Ovid" Poe'         \
               --email=ovid@cpan.org

That will create a directory named Convert-Distance-Imperial/. Using our tree.pl program, we see the following directory structure:

$ tree.pl Convert-Distance-Imperial/
Convert-Distance-Imperial/
|--Changes
|--MANIFEST
|--Makefile.PL
|--README
|--ignore.txt
|  lib/
|  |  Convert/
|  |  |  Distance/
|  |  |  |--Imperial.pm
|  t/
|  |--00-load.t
|  |--boilerplate.t
|  |--manifest.t
|  |--pod-coverage.t
|  |--pod.t

There’s a lot of stuff here, so let’s go over each item.

author: Curtis "Ovid" Poe
email:  ovid@cpan.org

module-starter --module=My::Module

You can just copy your copy of Convert/Distance/Imperial.pm to Convert-Distance-Imperial/lib/Convert/Distance/Imperial.pm and you have an installable module.

Let’s do that now in Try It out 11-2.

module-starter --module=Convert::Distance::Imperial,\
                        Convert::Distance::Metric

use 5.006;
use strict;
use warnings;
use ExtUtils::MakeMaker;
WriteMakefile(
    NAME          => 'Convert::Distance::Imperial',
    AUTHOR        => q{Curtis "Ovid" Poe <ovid@cpan.org>},
    VERSION_FROM  => 'lib/Convert/Distance/Imperial.pm',
    ABSTRACT_FROM => 'lib/Convert/Distance/Imperial.pm',
    ($ExtUtils::MakeMaker::VERSION >= 6.3002
      ? ('LICENSE'=> 'perl')
      : ()),
    PL_FILES            => {},
    PREREQ_PM => {
        'Test::More' => 0,
    },
    dist   => { COMPRESS => 'gzip −9f', SUFFIX => 'gz', },
    clean  => { FILES => 'Convert-Distance-Imperial-*' },
);

$ prove -l -v t/boilerplate.t

$ prove -lv t/boilerplate.t
t/boilerplate.t ..
1..3
not ok 1 - README # TODO Need to replace the boilerplate text
#   Failed (TODO) test 'README contains boilerplate text'
#   at t/boilerplate.t line 24.
# The README is used... appears on lines 3
# 'version information here' appears on lines 11
not ok 2 - Changes # TODO Need to replace the boilerplate text
#   Failed (TODO) test 'Changes contains boilerplate text'
#   at t/boilerplate.t line 24.
# placeholder date/time appears on lines 3
not ok 3 - Convert/Distance/Imperial.pm # TODO replace boilerplate
#   Failed (TODO) test 'lib/Convert/Distance/Imperial.pm'
#   at t/boilerplate.t line 24.
# stub function definition appears on lines 38 42 45 49
# boilerplate description appears on lines 22
# the great new $MODULENAME appears on lines 9
ok
All tests successful.
Files=1, Tests=3,  0 wallclock secs ( 0.02 usr  0.01 sys +
  0.02 cusr  0.00 csys =  0.05 CPU)
Result: PASS

Now that you’ve created your first “proper” module, turning it into a distribution is a snap. After you’ve done perl Makefile.PL, make and make test, you can type make dist and something called a tarball will be created for you. In this case it will have a name similar to Convert-Distance-Imperial-0.01.tar.gz. That’s suitable for uploading to the CPAN. If you wish to do that, you will need a PAUSE (Perl Authors Upload SErver) account. You can apply for one at https://pause.perl.org/ and start sharing your CPAN modules with everyone else.

You will also notice that after you type make, there are many extra files that have been built, such as a makefile, a blib/ directory and a pm_to_blib/ directory. They can be useful for debugging build problems, but to make them go away, you can just type make realclean. They will return the next time you type make.

You might think it odd that a language like Perl uses an external tool like a makefile to control how it builds its modules. After all, Java has ant and Ruby has rakefiles, why not a pure Perl alternative? This is because when Perl was first introduced, long before either Java or Ruby, it was very common on Unix-like systems and people who were likely to use Perl already knew about makefiles.

The Perl module that creates the actual makefile is called ExtUtils::MakeMaker (often referred to simply as EUMM) and it’s a beast to maintain. This is because there are many different implementations of the make program, not all of which are compatible with one another. Further, different operating systems have different constraints about filenames, paths, how commands get executed, and so on. Because the makefile must respect those constraints, the job gets harder. Imagine all of the different types of make utilities and the different incompatible operating systems and you can understand why this system has been hard to maintain.

As a result, the Module::Build project was started. It’s written entirely in Perl and is much easier to extend than EUMM. Unfortunately, Module::Build was a buggy when it first came out. Further, because EUMM had some design flaws when it was implemented, Module::Build fixed some of those flaws and this led to subtle incompatibilities between the two. Michael Schwern, the maintainer of EUMM has tried to convince people to switch to Module::Build, but many developers have chosen not to.

If you wish to use Module::Build with module-starter, just pass the --mb switch to module-starter. You’ll also want to read Module::Build::Authoring. The build process is then:

perl Build.PL
./Build
./Build test
./Build install

Finally, there’s the Module::Install module. This is designed primarily to work with ExtUtils::MakeMaker and is very easy to learn, particularly for new programmers. If you have Perl version 5.9.4 or better, you will already have Module::Build installed. You will have to install Module::Install separately.