A Task distribution is like a normal Perl distribution in structure, but it doesn’t actually provide any code. It lists as pre-requisites all of the modules or distributions that you want to install so you can use a conventiional CPAN tool to install all of the dependencies. A Task is slightly different from the older way, a Bundle, but for most people and uses, a Task might be a better way.

You can create your Task::* distribution with your favorite module tool (see Item 80. Don’t start distributions by hand). Once you have the basic structure, you edit the module file to document what your task does and you edit the build file to list the dependencies.

Suppose that you wanted to make one to install all of the modules mentioned in Effective Perl Programming (and we have in Task::EffectivePerlProgramming).

To do this yourself, you first create the stub distribution:

$ module-starter --module=Task::EffectivePerlProgramming
Class is Module::Starter
Created Task-EffectivePerlProgramming
Created Task-EffectivePerlProgramming/lib/Task
Created Task-EffectivePerlProgramming/lib/Task/EffectivePerlProgramming.pm
Created Task-EffectivePerlProgramming/t
Created Task-EffectivePerlProgramming/t/pod-coverage.t
Created Task-EffectivePerlProgramming/t/pod.t
Created Task-EffectivePerlProgramming/t/manifest.t
Created Task-EffectivePerlProgramming/t/boilerplate.t
Created Task-EffectivePerlProgramming/t/00-load.t
Created Task-EffectivePerlProgramming/ignore.txt
Created Task-EffectivePerlProgramming/Changes
Created Task-EffectivePerlProgramming/Build.PL
Created Task-EffectivePerlProgramming/README
Created Task-EffectivePerlProgramming/MANIFEST
Created starter directories and files

Next, you edit the .pm file to document your Task::* and to set a version number (the date is a good choice). Since this is a distribution like any other Perl distribution, when you install the Task, not only will the CPAN tool handle the dependencies, but it will also install the Task::* module, in this case Task::EffectivePerlProgramming. By adding a version to your distribution, you can update it later and use your CPAN tool to update your dependencies.

Here’s an extract of lib/Task/EffectivePerlProgramming.pm file:

package Task::EffectivePerlProgramming;

our $VERSION = '20100714';

=head1 NAME

Task::EffectivePerlProgramming - All of the modules mentioned in Effective Perl Programming, 2nd Edition

=head1 SYNOPSIS

This is just a Task module to install dependencies. There's no code to use
or run.

=head1 DESCRIPTION

These are the modules we used in the book:

=over 4

=item * Apache::DBI

=item * Apache::Perldoc

=item * etc, etc

=back

=head1 LICENSE AND COPYRIGHT

Copyright 2010 brian d foy.

You can distribute this module under the same terms as Perl itself.

=cut

1;

In the Build.PL, you then list each of the modules that you want to install as a dependency. If you don’t care which version of the dependency you want to install, you can use '0' as the version since any version should be equal to or greater than that:

use strict;
use warnings;
use Module::Build;

my $builder = Module::Build->new(
    module_name         => 'Task::EffectivePerlProgramming',
    license             => 'perl',
    dist_author         => q{brian d foy },
    dist_version_from   => 'lib/Task/EffectivePerlProgramming.pm',
    requires            => {
		'Apache::DBI'     => '0',
		'Apache::Perldoc' => '0',
		'App::Ack'        => '0',
		# etc, etc,
		},
    build_requires => {
        'Test::More' => 0,
    	},
    add_to_cleanup     => [ 'Task-EffectivePerlProgramming-*' ],
    create_makefile_pl => 'traditional',
	);

$builder->create_build_script();

That’s it; you’re done! Well, don’t forget to run the tests to check your Pod for proper formatting. Once you’re ready, you can create your distribution:

$ perl Build.PL
$ ./Build test
...
$ ./Build dist
Creating Makefile.PL
Deleting META.yml
Creating META.yml
Creating Task-EffectivePerlProgramming-20100714
Creating Task-EffectivePerlProgramming-20100714.tar.gz
Deleting Task-EffectivePerlProgramming-20100714

You can upload your distribution to CPAN, put it in your private module repository, email it to your coworkers, or pass it around however you like.
If it’s on CPAN, you can install it as you would any other module:

$ cpan Task::EffectivePerlProgramming

Installing the task from a local file

You don’t have to upload your Task distribution to CPAN to use it. You can install the prerequisites of a distribution as long as you have that distribution. You could

In the cpan command-line tool, you can install the current directory (just the dot), including its dependencies:

$ cd Task-EffectivePerlProgramming
$ cpan .

The cpanminus command-line tool can install just the dependencies without installing the module inself (but that’s not necessarily a good thing):

$ cd Task-EffectivePerlProgramming
$ cpanm --installdeps .

Since this Task used Module::Build, you can use the installdeps build target, although you have an extra step now:

$ cd Task-EffectivePerlProgramming
$ perl Build.PL
$ Build installdeps

Bundles are still good

Task distributions take the place of CPAN.pm’s auto-bundles, mostly, but miss a key feature of Bundles, which can install modules given a local file path instead of just a repository path.

You can generate an autobundle with CPAN.pm. The output lists the currently installed versions, the latest version in CPAN, and the relative path in CPAN-like archive. At the end, it writes the actual auto-bundle file:

$ cpan -a
...
Net::POP3                      2.29      2.29  GBARR/libnet-1.22.tar.gz
Net::SMTP                      2.31      2.31  GBARR/libnet-1.22.tar.gz
Net::SSL                       2.84      2.85  NANIS/Crypt-SSLeay-0.58.tar.gz
...
warnings                       1.06      1.11  JESSE/perl-5.13.9.tar.gz
warnings::register             1.01      1.02  JESSE/perl-5.13.9.tar.gz

Wrote bundle file
    /Users/Buster/.cpan/Bundle/Snapshot_2011_08_16_00.pm

The bundle file has some metadata and a list of packages and versions:

package Bundle::Snapshot_2011_08_16_00;

$VERSION = '0.01';

1;

__END__

=head1 NAME

Bundle::Snapshot_2011_08_16_00 - Snapshot of installation on Buster on Tue Aug 16 15:05:40 2011

=head1 SYNOPSIS

perl -MCPAN -e 'install Bundle::Snapshot_2011_08_16_00'

=head1 CONTENTS

Algorithm::Diff 1.1902

Apache::DBI 1.08

Apache::Perldoc 1.11

Apache::Test 1.31

App::Cache 0.36

App::Cmd 0.301

App::Module::Lister 0.13

App::cpanminus 1.0004

AppConfig 1.66

This auto-bundle is a list of everything you have installed, but it doesn’t have to be. You can list any packages and versions that you like. It’s completely up to you to decide what should be part of the task.

Putting this anywhere in your @INC (such as the current working directory) allows you to use the cpan tool to install it:


$ cd /Users/Buster/.cpan
$ cpan Bundle::Snapshot_2011_08_16_00


CPAN.pm handles Bundles specially to handle this.

Since the auto-bundle is a single file (although in a directory named Bundle), it might be easier for you to pass around. Either way, you have a way to tell people everything that should install.

Some interesting Tasks

Some Task distributions cover big topics, such as:

• Task::Kensho for Enlightened Perl development
• Task::Dancer for extra goodies for the Dancer web framework
• Task::Plack for web middleware
• Task::HTML5 for new Web hotness

There are several Task::BeLike:: distributions that list people’s favorite tools and modules. If you want to do the same sorts of things as these people, you might want to install their BeLike distributions:

• Be like Ævar Arnfjörð Bjarmason
• Be like Ricardo SIGNES
• Be like Florian Ragwitz

Things to remember

• Collect project dependencies in a Task distribution
• Install the Task distribution like any other module distribution, or directly from the local directory
• Several tasks already exist on CPAN.

Some definitions

There are several points to consider as you try to figure out how PAUSE works. Start with the defintions to ensure you’re thinking about the same things as you go through this Item. People are often quite loose with their terminology, so its useful to define these terms before you get started.

A module is a unit of Perl re-usability. It’s typically a single .pm file, but it might be more than one if it loads private plugins or other helpers. You load a module with do (rare), require, or use.

A package and a namespace are almost the same thing, but not quite. The package is really all the bits that live under a particular namespace, with is just the name you gave to the package. You declare a default namespace with the package built-in. You can affect the package in any file, but the namespace is just the label. A “module” and a “namespace” are often interchangeable terms because most modules use a single namespace, or at least a single, advertised namespace.

A distribution is a collection of modules or programs, along with ancillary files and installation information, turned into a single file with an archiving tool such as tar or zip. A distribution can contain several modules. In other words, the distribution is the thing you upload and share. Some people use “distribution” to refer to any of the releases with the same base name, such as Moose-1.01.tgz, Moose-1.02.tgz, … Moose-1.21.tgz.

PAUSE indexes a distribution by recording the namespaces and versions it finds and adding them to the database that produces the file modules/02packagedetails.txt.gz, which CPAN clients use to figure out what to download when you want to install a module.

PAUSE only cares about uploads

PAUSE is really just a release mechanism for CPAN. You upload a distribution, PAUSE looks at the namespaces you declare with package, and looks up those namespaces in its database. If it thinks you are allowed to upload those namespaces, PAUSE indexes your distribution. It examines the version numbers for the packages, and as long as the new versions are greater than the previous version values in the index, PAUSE adds your distribution information to its database.

If any of that fails, PAUSE sends you an email explaining what went wrong. PAUSE still puts your uploaded file in your author directory, but since PAUSE doesn’t add the unauthorized namespaces to the modules/02packagedetails.txt.gz, CPAN clients won’t see it.

There are several sorts of maintainers

To PAUSE, a maintainer is someone who can upload a distribution that PAUSE will index. The role is more like a release manager. You don’t have to be a PAUSE maintainer to work on and collaborate on CPAN code.

If you need to get something fixed and uploaded, there are two types of maintainers that may be able to help you: a primary or co-maintainer. There are some additional classifications of those, too.

You can be a primary maintainer or a co-maintainer of a namespace (not a distribution). The primary maintainer can assign or take-away co-maintainer permissions, as well as pass on primary maintainership to someone else (while losing that status in the process). PAUSE will index the namespaces in a distribution uploaded by any of these maintainers.

If you are the first person to upload a distribution using a particular namespace, you are a first-come maintainer. PAUSE assigns that namespace to you merely because you are the first person to use it. You don’t have to ask anyone’s permission or give any notice to use a new namespace. PAUSE, being mostly automated and mostly code, doesn’t care anything about your namespace other than it being new.

You can also add a co-maintainer for a namespace, which is really adding what most people would consider a release manager. By assigning co-maintainer permissions for a namespace, you tell PAUSE to index that namespace if that co-maintainer uploads it. As a co-maintainer, you do not have to upload the assigned namespace as part of the same distribution though. That shouldn’t be a common, or even intended, sort of upload though, and is likely to confuse people when they don’t get the distribution they expected.

There are two less-known types of maintainers too. A primary maintainer can also be a module list maintainer. That means that the maintainer registered the namespace with PAUSE. No one needs to register a namespace, but there are some some PAUSE features that only work with registered modules. For instance, you can register a namespace to “reserve” it for future use without uploading a distribution that uses that namespace.

Beyond that, there is also a mailing list maintainer. This is like a primary maintainership shared among anyone in the mailing list. Any one of those persons can assign or take away co-maintainer permissions. Projects such as PARROT and PERLCRITIC use the mailing list feature because they rotate release managers.

Find a maintainer

Any of the maintainers can upload a new distribution that PAUSE will index. That means that when you need to get something fixed, you may be able to find more than one person who can help you get a bug fixed and uploaded. Note, however, that you should also try the advertised support of the distribution, including its issue tracker (most likely CPAN RT), its mailing list, and so on. As you read earlier, maintainers are really just release managers so there may be other people who can work on the code.

If you have a PAUSE account (Item 70. Contribute to CPAN), you can use the PAUSE interface to search the permissions database. You can search by the maintainer name, the exact module name, or use a string for an SQL LIKE query. The results for any search allow you to drill down into the results by the namespace or the author name.

If you don’t have a PAUSE account, you can still look through the permissions for all of the namespaces. A couple of years ago, PAUSE added the $CPAN/module/06perm.txt file which lists each namespace:

File:        06perms.txt
Description: CSV file of upload permission to the CPAN per namespace
    best-permission is one of "m" for "modulelist", "f" for
    "first-come", "c" for "co-maint"
Columns:     package,userid,best-permission
Line-Count:  175031
Written-By:  Id
Date:        Sun, 19 Dec 2010 09:08:52 GMT

A,ADAMK,f
A::B,CODEREPOS,c
A::B,MARCEL,f
AA,RLZWART,f
AA::GAMP,RLZWART,f
AAA::Demo,JWACH,f
AAA::eBay,JWACH,f
AAAA::Crypt::DH,BINGOS,f
AAC::Pvoice,JOUKE,f
AAC::Pvoice::Bitmap,JOUKE,f
AAC::Pvoice::Dialog,JOUKE,f
AAC::Pvoice::EditableRow,JOUKE,f
AAC::Pvoice::Input,JOUKE,f
AAC::Pvoice::Panel,JOUKE,f
AAC::Pvoice::Row,JOUKE,f

The $CPAN/module/06perm.txt has three fields: namespace, PAUSE author, and the type of permission. The one-letter permission code is explained in the file header. Using grep or a Perl one-liner as a poor man’s query tool is often sufficient to find what you want:

As a bonus, notice the use of the -a and -F switches to perl. The -a autosplits each line using whitespace as the delimiter. However, if you use the -F switch, you can specify an alternate delimiter. Either way, the results end up in the @F array.

In this example, you use -F to split on a comma then match against $F[0] to find namespaces:

$ perl -F, -ane  'print if $F[0] =~ /^CPAN::/' 06perms.txt

If you wanted to find an author, you can look in $F[1]:

$ perl -F, -ane  'print if $F[1] eq q|BDFOY|' 06perms.txt

You don’t have to be a maintainer to work on the code

Although the term “maintainer” implies that you also work on the code, some maintainers do nothing more than uploading the distribution. Likewise, not everyone who actually maintains or works on the code needs co-maintainer permissions in PAUSE.

You don’t own heirarchies

When PAUSE assigns you a namespace as a primary maintainer, you only “own” exactly that namespace. Although Perl namespaces look like they are hierarchial, they aren’t. That is, there’s nothing in Perl that cares what namespace you use or which one your package inherits from. The XML::Simple namespaces doesn’t inherit from XML by virtue of its name. In the same way, you don’t have any permissions on Foo::Bar::Baz merely because PAUSE assigned you permissions on Foo::Bar. That means you don’t have to rush to register your company’s name as a namespace because it’s not going to prevent anyone from using it for another namespace.

As part of the lack of proper heirarchies, you also have to assign comaintainer permissions on every particular namespace that you want to share.

Fix your “unauthorized” release

Even if PAUSE does not index your distribution, it still puts it in your author directory. The CPAN servers still mirror everything in your author directory, just like they mirror old distributions that do not appear in the index. The CPAN Search website still shows the distribution but puts a big red UNAUTHORIZED next to the distribution name and also the namespaces with the missing permissions:

To fix this, you need to get the missing co-maintainer permissions. The primary maintainer or the mailing list members will have to help you with that. As a last resort, you can ask the admins at modules@perl.org for help.

Things to remember

• A PAUSE or CPAN author is really a release manager.
• A primary maintainer can assign co-maintainer permissions.
• You can search permissions through the PAUSE interface.
• You can search permissions in the $CPAN/modules/06perms.txt file.

In Item 91: Write Scripts as Modules, we talk about the creating programs as “modulinos”, or little modules. You segregate everything into subroutines and activate your code through a run() subroutine, similar to the main subroutine you’d use in other languages. I’ve written about this a lot elsewhere, including my TPJ article Scripts As Modules and an entire chapter in Mastering Perl.

A modulino is a great way to start a new program, but it’s often too much work to convert an existing program if you only have a little time available. You can still get a lot of the benefits of a Perl distribution, such as dependency management and installation, even without the module portion.

Typically, in your distribution you put your modules under the lib directory. You’d put your Cat::Burglar module in lib/Cat/Burglar.pm. Your build system (Item 79: Use Module::Build) sees what is in lib and copies it into blib/lib, the build library which is the intermediate staging area for the installation. When you install your distribution, the build system copies the contents of blib into the right places. You don’t have to have just modules in your distribution, though.

You can also have a bin directory under blib. The build system copies the contents of the blib/bin. You don’t have to stage your programs manually. Suppose that you stored your program in the distribution as script/cat_burglar, although the location isn’t magical. For Makemaker, you use the EXE_FILES argument to stage the program for installation:

	use ExtUtils::Makemaker;

	WriteMakefile(
		...
		'EXE_FILES'    => [ qw(script/cat_burglar) ],
		...
		);

For Module::Build, you use the script_files argument:

my $build = Module::Build->new
	(
	...
	script_files => [ qw(script/cat_burglar) ],
	...
	);

You set up the rest of the build file normally, specifying such things as the prerequisites for configuring, building, and running the program, creating the distribution archive, and so on. You don’t even need to have any modules. You can have just modules, just scripts, or scripts and modules combined. You just have to set up the build file appropriately. Once you’ve done that, you can treat your programs just as you do any other distribution. When you want to install it, you go through the same process that you do with modules:

% perl Build.PL
% ./Build install

You can even use the cpan tool to install from the current directory, including all of its dependencies:

% cpan .

Although I now tend to write most programs of any consequence as modulinos, when I first started putting my programs into distributions I wrote a tool that I called scriptdist to turn single program files into complete distributions. I wrote about that for TPJ as Automating script distributions with scriptdist. Although it’s a bit dated, it’s essentially in the same state. If you don’t like its templates, you can modify them to make your own.

Simply wrapping your program in a distribution is merely a first step, but it’s better than nothing until you have time to pay more attention to it.