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.

What files do CPAN clients want?

What files do CPAN websites want?

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

XS stuff

These files are often found in XS packages:

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:

Directories you might see...

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

perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'

In reply to What are the files in a CPAN distribution? by tobyink

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.