http://qs321.pair.com?node_id=11122911


in reply to Re^4: What do I use to release a module to CPAN for the first time?
in thread What do I use to release a module to CPAN for the first time?

You don't write the META.json and META.yml yourself. They're generated. The easiest way I've found to generate them is to run make disttest and then copy them up one directory level from the test-distribution directory to the top level distribution directory. This has always felt wonky to me, and I'm sure I'm missing the most obvious approach. But it works.

These are generated based on what you have in the hash passed to WriteMakefile() in your ./Makefile.PL script. That's where you do your editing. For an understanding on what can go in the WriteMakefile hash, you can read the following documentation:

As you read through that last one, keep in mind the following two points: First, you put things in your WriteMakefile hash to get them into your META.* files. Second, things listed as DEPRECATED FIELDS are often still widely used, and better supported than newer alternatives (I'm thinking of build_requires, configure_requires, recommends, and requires. That doesn't mean you shouldn't use the newer alternatives, but if you do use them, you may need to do ExtUtils::MakeMaker version detection in your Makefile.PL to verify what features are available on a given system.

I've seen the ExtUtils::MakeMaker version checking dance done in a bunch of modules in recent years. It's fine, but it means you need to investigate the Changes file for EU::MM, which is a bit of a pain, or list a modern version of ExtUtils::MakeMaker in a CONFIGURE_REQUIRES section (but only if you detect an older version of EU::MM) or in the prereqs => {configure => {requires => {...}}} section, if a new enough version of EU::MM is detected on the user's system (in which case it may not be necessary anyway, but for consistency is probably worthwhile). The down-side to putting a minimum version requirement on ExtUtils::MakeMaker is that you force yet another dependency on people installing your module in environments where dependency management is difficult, and do so only so that your distribution can have better set-up tooling, not so that the runtime is any better.

Think of PREQ_PM and prereqs => {runtime => {requires => {...}}} as how you indicate what dependencies are needed for your module to run. BUILD_REQUIRES and prereqs => {build => {requires => {...}}} as what is needed to build the module so that it can be installed. Under older versions of BUILD_REQUIRES I think this is also where you list test dependencies. Under newer versions of EU::MM you use the prereqs => {test => {requires => {...}}} namespace to indicate test dependencies. And finally, to set up the dependencies that Makefile.PL needs to produce a correct Makefile, you use the CONFIGURE_REQUIRES or prereqs => {configure => {requires => {...}}}. You can additionally specify prereqs => {develop => {requires => {...}}}, and that can be useful if you have dependencies on development tooling. I don't see that as often. Anyway, this is all documented in the links provided above.

Think of your WriteMakefile hash as the input to ExtUtils::MakeMaker, with the desired output being twofold: One, a Makefile that provides the targets make needs. Two, a make target that can generate the META.* files that CPAN installer and indexing tooling need to catalog the distribution, and to be able to pull it down, as well as its dependencies.


Dave

Replies are listed 'Best First'.
Re^6: What do I use to release a module to CPAN for the first time?
by hippo (Bishop) on Oct 16, 2020 at 16:20 UTC
    This has always felt wonky to me, and I'm sure I'm missing the most obvious approach.

    When you run make tardist (which should be the last thing to do before uploading the resultant tarball to PAUSE) it generates the META files for you (as part of the implicit make distdir) and therefore they are automatically included in that tarball. To me, that is the most obvious approach. By doing it this way I never have to actively think about any of the META files - remember that laziness is one of the Three Virtues. HTH.


    🦛

      I guess I never noticed that the META.* files get included in the tarball just in time. I can safely drop them from my Git repo, and they will still be included in the PAUSE upload. Thanks.


      Dave