CPAN packages have their own standardised format, consisting of a set of standard files and paths that should be pretty familar to anybody used to installing F/LOSS software from source. CPANTS provides some basic automated Kwalitee testing at http://cpants.perl.org. You can also test your module's Kwalitee with Test::Kwalitee.

A normal/traditional CPAN package contains 4 standard files and 2 standard directories :

• README - A brief ASCII Text document about the package, that should include information about the package, copyright, requirements, and other useful information
• Changes - An ASCII Text document giving a history of versions of the package and the changes made
• MANIFEST - An ASCII Text document listing the files in the package
• Makefile.PL - A short perl script to create the Makefile for the package, containing requirements and pointers to the author, documentation, etc
• lib/ - A directory containing the Perl modules, i.e. lib/Foo/Bar.pm for Foo::Bar
• t/ - A directory containing TAP compliant test files that will be run with 'make test'

A CPAN Package contains this (or similar) in a gzip compressed tarball, other files can be META.yml which provides metadata for cpan tools and digital signature files.

Declaring dependencies

When packaging a module for distribution you should declare its dependencies in META.yml. Most of these will be automatically created if you
are using one of the standard packaging tool.

• Which is the minimum perl version should be declared in META.yml in requires:perl (no toolchain support for this yet)
• Runtime dependencies on other modules on CPAN should go in the requires fields of META.yml (the toolchain supports this)

The best would be to declare each module you are using but in many cases that is just too much work.
For example when using 10 different widgets that are all provided by Tk, people usually tend to only declare dependency on Tk.
While this works most of the time if in the future Tk will be split into two modules and some of the 10 widgets will be moved
to let's say Tk::Extra then your module will no longer get all of its dependencies from Tk.

• Buildtime dependency should go build_requires field of META.yml. Currently Module::Build and Module::Install support this while ExtUtils::MakeMaker not yet.
• Test dependecies should be also declared separately but because of the lack of support in META.yml this is usually declared in the build_requires field.
• Dependence on non CPAN code (e.g. C compiler, C libraries etc). is not yet supported in META.yml, one needs to check this in Makefile.PL or Build.PL programatically

Modules to create CPAN Packages

To create a CPAN package, use one of the following tools:

• modulemaker (interactive)
• module-starter (newer)
• h2xs (only recommended for XS modules)

There are two main tools for building CPAN packages, namely ExtUtils::MakeMaker and Module::Build. To build your package, once you've written the code, tests and documentation, run:

The result is a gzipped tarball which you can upload to PAUSE.

Guidelines for module authors for easy repackaging

In order to make packaging of CPAN modules for the various distributions easier
module authors should create and package their module adhering to some
standards. Following is a wishlist created by the Debian Perl module maintainers:
http://people.debian.org/~terpstra/message/20080304.104744.f5ca7c1c.en.html

See also the new packaging guidelines of Debian: http://wiki.debian.org/GettingPackaged

Version numbering

Perl versions are numbers. This means 1.2 is higher than 1.09.

Good Perl versions have two key attributes:

1. They must sort numerically
2. They must always go up

For this reason a simple decimal version number like 1.23 is recommended -
or even just an integer. Please think ahead - if you end up changing your
versioning system after a few releases, it is very annoying.

CPAN's system automatically tags versions with an underscore (_) as
experimental versions, so there is no need to make releases called "alpha1".
Just do "1.0.0_1", "1.0.0_2", or the like.

If you want to use 1.2.3 style versions, you can use version objects but
be sure not to mix version objects with numeric versions unless you understand
how they convert.

Copyrights/licensing

Ideally each and every file in given CPAN distribution should have
clearly stated copyright and license information in two places.
First, in a LICENSE section of the POD. A URL referencing the text
of your license is fine. http://dev.perl.org/licenses/ is a good source of
the Perl license. Otherwise use http://www.opensource.org/licenses/

Second is in the META.yml so the license can be determined programatically.
This can be done with the LICENSE or license parameter in your Makefile.PL
or Build.PL respectively.

It is encouraged, but not required, that CPAN distributions use an Open Source license.
The only requirement is that a CPAN distribution must be freely re-distributable.
Restrictive-use license, such as "free for non-commercial use" are allowed.

FYI In order to be packaged by Fedora they require that the code uses one of the licenses
approved by them. The list of approved licenses should be at http://fedoraproject.org/wiki/Licensing
Most notably for Perl developers they won't package modules that come with Artistic 1 license only.
The Artistic 1 + GPL pair (aka. Perl license) or the Artistic 2 license are ok.

Use prompt() for build interaction.

Both MakeMaker and Module::Build provide a prompt() function to use to ask
questions of the user. It will do the right thing to detect non-interactive
installations and take the defaults.

Set sensible defaults.

For all your configuration, write sensible defaults so it has a good chance of
installing automatically without user interaction.

No network access during build

No network access needed for building and testing (or an
easy and documented way to turn network tests off).

Use standard packaging systems

Please use one of the standard Perl module build packages if at all
possible. Use make/Build dist rather than rolling your own archive.
Less things can go wrong.

Run disttest

make/Build disttest will check a fresh copy of your distribution. This is
helpful to check if you forgot to put a file into your MANIFEST.

Structured POD

POD documentation for modules should be structured as described in the
pod2man man page. In particular, the NAME section and its content is
mandatory. Otherwise, one doesn't get a valid man page.

Use things like podchecker and Test::Pod to make sure your POD is valid.

Look at your own documentation through perldoc, often what looks fine in the
source code is malformated in perldoc.

Don't ship Makefiles

Please don't ship generated Makefiles etc.

Testing

Put your tests into the t/ directory, not in a test.pl file.

Don't use conditions in tests that test for the existence of author
specfic files or settings (" unless -d '.svn'" or "unless $username eq
'timbo'")

Specifically, don't do this unless that's being used as a criteria for
skipping a test that's really meaningless outside of the author's
environment. (I do have a few tests in modules that depend on local
infrastructure to run and hence are skipped if they're not run by me.)

See Also

• Building and Deploying Perl Packages / Applications
• Recommended Modules For Module Development

Suggested reading

• Jose Castro's Guide for Creating Perl Modules on perlmonks
• Writing solid CPAN modules on perlmonks
• How to make a CPAN distribution
• Simple module tutorial
• Writing Perl Modules for CPAN