MYMETA file for CPAN authors.md

(If you use Dist::Zilla, stop reading this document and just do what it tells you to, since it takes care of all this. If you directly use either ExtUtils::MakeMaker, Module::Install or Module::Build, read on.)

You're a new CPAN author (congratulations!) or you have an old distribution that is about to be updated for the first time in years, and you find MYMETA.yml and MYMETA.json in your working directory that git or shipit warns about. You think: What are these files? Should I package these files?

tl;dr - add MYMETA.yml and MYMETA.json to .gitignore and MANIFEST.SKIP (if you have one), and do not include them in the tarball.

If you're using a boilerplate generator that generates your custom MANIFEST.SKIP, including the line #!include_default might be a good idea since it will give you the latest default ignore files that you don't need to maintain.

MYMETA.yml/json files are a relatively new approach for CPAN installers (CPAN, CPANPLUS, cpanm) and module build tools (MakeMaker, Module::Build) to communicate the configured dependencies on the end-user's system.

MYMETA is just like META files in terms of the file format and data structure, but whereas META.yml is generated by the distribution author (you), MYMETA.yml is generated by the end user at a configuration time.

Here's how the installer and build tools work, if you're interested:

• Module authors (you) upload a distribution containing META.yml file
• CPAN installer grabs the tarball, examines META.yml for configure_requires. Installs them if there's any missing cofnigure dependencies
• CPAN installer runs perl Makefile.PL or perl Build.PL depending on which the distribution has.
• Makefile.PL or Build.PL generates MYMETA.yml and MYMETA.json file, based on the configuration result.
• CPAN installer examines MYMETA.json (or MYMETA.yml) for more dependencies for build, test and runtime.
• etc...

When the dependencies of your module are completely static, you could also declare dynamic_config: 0 in your META file, which means the configuration is not dynamic and the generated MYMETA.yml should in theory be identical to META.yml.

Including MYMETA files in MANIFEST and a distribution tarball does not make any sense, and could cause potential problems confusing CPAN installers - do not make them part of your distribution.

(Why this post? Many CPAN authors have been confused or unaware what MYMETA files are and simply include them in the distribution)