I would love a few sets of eyeballs looking over what I have so far before running make dist.

I am having a hard time finding documentation on the values in the META.yml file. I found documentation for META.json easily enough. I am specifically looking for the yml settings for the resources I have in the json file.

  "resources" : {
    "repository" : {
      "url" : "https://github.com/LadyAleena/File-Slurp-Affix",
      "web" : "https://github.com/LadyAleena/File-Slurp-Affix",
      "type" : "git"
    },
    "bugtracker" : {
      "web" : "https://github.com/LadyAleena/File-Slurp-Affix/issues"
    },
    "x_twitter" => 'http://twitter.com/Lady_Aleena',
  },
[download]

Also, should I ask in a git channel or forum about how to manage versioning? Either way, I am not sure where to go after the testing release. Also, what files in the repo should I add to .gitignore? make clean cleansed the directory structure well.

I am having a hard time finding documentation on the values in the META.yml file. I found documentation for META.json easily enough. I am specifically looking for the yml settings for the resources I have in the json file.

It rather sounds from this like you are writing these files yourself. That's almost never a good idea. Your build system should do that for you based upon the contents of Makefile.PL. Get Makefile.PL right and all the META files will follow without you having to lift a finger.

Also, what files in the repo should I add to .gitignore?

None. .gitignore is for specifying files to keep out of the repo. Here's a fairly standard one of mine - you will notice that the META files are listed here because I want to make sure that such transient files are not accidentally committed (hopefully this emphasises the point above).

/blib/
/.build/
_build/
cover_db/
inc/
Build
!Build/
Build.bat
.last_cover_stats
/Makefile
/Makefile.old
/MANIFEST*.bak
/META.yml
/META.json
/MYMETA.*
nytprof.out
/pm_to_blib
*.o
*.bs
*.tmp
*.swp
[download]

---

🦛

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:

• ExtUtils::MakeMaker::Tutorial
• ExtUtils::MakeMaker
• CPAN::Meta::Spec

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

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.

---

🦛

Good explanation has already been done in the davido's long read.

---

You asked:

... I am specifically looking for the yml settings for the resources I have in the json file.

It should be a part of Makefile.PL. For example:

my %WriteMakefileArgs = (
    NAME             => 'File::Slurp::Affix',
...
    META_MERGE => {
        resources => {
            homepage   => 'https://github.com/LadyAleena/File-Slurp-Af
+fix',
            bugtracker => 'https://github.com/LadyAleena/File-Slurp-Af
+fix/issues',
            repository => 'https://github.com/LadyAleena/File-Slurp-Af
+fix.git',
        },
    },
...
    clean => { FILES => 'File-Slurp-Affix-*' },
);
[download]

Unfortunately, this part is not explained clearly. I learnt it looking on other projects, especially what is written in ExtUtils::MakeMaker itself. There are two version of META_ADD/META_MERGE. In my example above I used the first version.

---

Once module-starter executed, you've got the following directory structure:

lib/
t/
xt/
Changes
ignore.txt (or .gitignore when module-starter --git)
Makefile.PL
MANIFEST
README
[download]

lib/ is the stuff you are working on.

t/ and xt/ contain the stuff used for testing the module. You can check how tests wok:

prove -l -v
[download]

You can put here any code you'd like for proving your module. All (or almost all) aspects should be covered by these tests. It is template for your future tests, you can remove them and write your own tests.

Changes is used for the history. You will write here significant changes in current version since last one.

ignore.txt, .gitignore are used to skip some temporary files.

Makefile.PL creates MYMETA.* and Makefile. In general, there are no special reasons to keep them in you repo.

README is the first thing is read by others (usually). In it you need to explain your module. POD of the module is applicable as well. Check it and convert if no errors:

podchecker lib/File/Slurp/Affix.pm
pod2text lib/File/Slurp/Affix.pm > README
[download]



MANIFEST is for declaring the content of your package. You also need to create MANIFEST.SKIP to declare the stuff that is not in MANIFEST and should be excluded from the package. It can be the same as .gitignore. Also you can add anything what you need to keep in the repo but should be skipped in the package. The following simple script will show what is not good with manifests.

#!/usr/bin/env perl

use Test::More tests => 2;
use ExtUtils::Manifest;
 
is_deeply [ ExtUtils::Manifest::manicheck() ], [], 'missing';
is_deeply [ ExtUtils::Manifest::filecheck() ], [], 'extra';
[download]