Minimal requirement to build a sane CPAN package

I started to write an article explaining how to package a Perl module
but it got too long and detailed. Let's start with a simple case and
build the smallest possible but still sane package. Later we can go
in more details and see alternative ways.

Let's say you have a module called Math::Calc that you would like to upload to CPAN.
This is the code you have in the Calc.pm file:

You need to create a directory, let's say Math-Calc, just to hold
all the parts of the distributions. In that directory put the Calc.pm
file in the lib/Math subdirectory. Also create a Makefile.PL (capital M, P, and L)
and a MANIFEST file in the Math-Calc directory:

like this:

Math-Calc/
lib/Math/Calc.pm
Makefile.PL
MANIFEST

The MANIFEST file contains a list of files that need to be packaged. In our case this
should be the content:

MANIFEST
Makefile.PL
lib/Math/Calc.pm
META.yml
META.json

The first 3 entries are the files we really have. The two META files are
going to be automatically
generated when the distribution is created. They contain META information about
your package. On CPAN they are used by various tools to display information
about the module.

The value of the NAME field will be used as the filename for the distribution.
The version number is taken from the Calc.pm file and for this to work we'll
need to add a $VERSION variable to the module. The module will look like this:

Prerequisites

There are a lot of other improvements one can and should make but let me show you just one thing.
If you change the Math::Calc module to use some other modules, you must include the lists of
prerequisites in the Makefile.PL. Let's say you start using Moose. In that case you need to add
the PREREQ_PM key with key-value pairs. The keys are the module names, the values are the minimum(!)
version numbers.

Use PREREQ_PM instead of BUILD_REQUIRES

As David Golden (xdg) pointed it out in the comments, BUILD_REQUIRES
is only available in relatively recent versions of ExtUtils::MakeMaker.
So for now, I'd suggest to put both the run-time and the build-time
prerequisites in the PREREQ_PM hash.

What's next?

There are a number of other things you should take care of, such as adding a README file, keeping and distributing
a Changes file. Maybe having a MANIFEST.SKIP to handle the MANIFEST file. You should also add copyright and licensing
information to your module. There are also other packaging tools but all this will be part of another post.