What files can you expect to find in a typical CPAN distribution? Why do they exist? What purpose do they serve?

This meditation is an answer to a blog post by Ovid but I hope it's generically useful. I'll keep updating this list with more info; please reply below if you can think of anything I've missed.

(Some of these might be automatically generated and others might be created manually; it all depends on your build process. This is not intended as a discussion of the best way to build distributions.)

What files are absolutely required?

None. There are no absolute requirements for the contents of a tarball uploaded to CPAN. However, the presence of certain files can be useful for the CPAN indexer, CPAN clients, search.cpan.org, metacpan.org and so on.

What files does the CPAN indexer want?

Although the CPAN indexer doesn't need either of these, it will handle them specially, unpacking them from the tarball so that people can download them without needing to download the whole distribution.

• ./README - a plain text file containing general information about the distribution. Many people auto-generate this from the pod of the main module in their distribution, but you don't need to.

• ./META.yml or ./META.json - metadata about the distribution, usually including authorship, licence, prerequisites and so on. See CPAN::Meta::Spec. Why have one file format when you can have two?

What files do CPAN clients want?

• ./MANIFEST - a list (one per line) of files contained within the tarball, optionally including comments. See ExtUtils::Manifest. Not actually required, but many CPAN clients will issue massive warnings if it's missing or incorrect.

• ./Makefile.PL or ./Build.PL. If Build.PL is present, and the CPAN client is modern enough, the client will use the following commands to install the distribution:

  perl Build.PL
  ./Build
  ./Build test
  ./Build install
  [download]

  The idea is that Build.PL is a script using Module::Build and that Build is another Perl script output by Build.PL. But of course, it doesn't have to be; Build.PL could be an empty script, and Build could be a shell script.

  If Build.PL is missing, or the client doesn't support Build.PL, the following steps are run:

  perl Makefile.PL
  make
  make test
  make install
  [download]

  You should include at least one of these if you hope for people to be able to install your module via CPAN clients.

• ./META.yml or ./META.json - CPAN clients will use these to determine build-time prerequisites for your module. Recent Makefile.PL or Build.PL files will also typically output ./MYMETA.yml and ./MYMETA.json for the canonical list of run-time prerequisites (and these should not be packaged in the distributed tarball), but if they do not, then ./META.yml or ./META.json are used as fallbacks.

• ./SIGNATURE - a list of MD5 hashes of the files in the MANIFEST, signed by GPG/PGP. Optional, but some CPAN clients will offer to verify the signature and check the MD5 hashes.

What files do CPAN websites want?

MetaCPAN will display the following documentation files on a release's front page if they exist:

• ./README / ./README.md / ./README.pod
• ./INSTALL
• ./NEWS
• ./FAQ
• ./LICENSE / ./Copying
• ./COPYRIGHT
• ./TODO / ./ToDo / ./Todo
• ./CONTRIBUTING
• ./AUTHORS / ./CREDITS / ./THANKS
• ./CHANGES / ./Changes / ./ChangeLog / ./Changelog / ./CHANGELOG (see CPAN::Changes::Spec)
• It will similarly display (though they're not strictly documentation): ./MANIFEST, ./Makefile.PL, ./Build.PL, ./META.yml, ./META.json, dist.ini (see Dist::Zilla) and ./cpanfile (see Module::CPANfile).

XS stuff

These files are often found in XS packages:

• ./ppport.h - C header file that many XS packages link against.
• ./typemap - mapping between Perl and native C data types.

Other files you might see...

Though not used by the CPAN indexer or clients, you will often see some other files left as artefacts of the system used to package the distribution:

• ./MANIFEST.SKIP - many authors use this to list the files they have in their development directory which they don't want to package. Most distribution building processes will honour this list. They should really include MANIFEST.SKIP in their MANIFEST.SKIP so that it doesn't get distributed!

• ./dist.ini - config file for the popular distribution builder Dist::Zilla.

Directories you might see...

• ./lib/ - by convention, packaged modules are distributed here.

• ./bin/ or ./script/ - by convention, packaged scripts are distributed here.

• ./t/ - by convention, packaged test cases are distributed here.

• ./xt/ - additional test cases run by the author only; there's no need to upload these to CPAN; they should be in MANIFEST.SKIP.

• ./inc/ - bundled support files for Makefile.PL.

• ./share/ - conventional place to distribute data files accompanying the distribution

• ./examples/ or ./eg/ - for example scripts, sample input and sample output. As of 2013-03-19, MetaCPAN displays a list of example files on a release's front page.

• ./meta/ - used by Module::Package::RDF as the source of distribution metadata

What should be checked into version control?

My general rule is that if a file is automatically regenerated on a regular basis (e.g. META.yml is often automatically generated when packaging up the distribution) then it doesn't go into version control. Everything else does.

Update History

• 2013-03-20: added info about ./examples/, ./cpanfile and ./CONTRIBUTING.