How does the key "file" of the structure "provides" work with "META.*" for "CPAN::Meta::Spec"?

Question

I'm trying to better understand what I could use CPAN::Meta::Spec for and came across the following sentence in the spec for the key file:

[...]to a file that contains or generates the package. It may be given as META.yml or META.json to claim a package for indexing without needing a *.pm.

This sentence reads to me like one was able to directly specify some META.* within the config using a path to a file instead of a *.pm. Hence using the wording it, that clearly associates to the formerly mentioned path. Pretty much like in the following example:

provides => {
  'Foo::Bar' => {
    file    => 'lib/Foo/Bar.pm',
    version => '0.27_02'
  },
  'Foo::Bar2' => {
    file    => 'lib/Foo/Bar2.yml', <-- META.yml?
  },
  'Foo::Bar3' => {
    file    => 'lib/Foo/Bar3.json', <-- META.json?
    version => '0.3'
  }

So, while Foo/Bar2.pm and Foo/Bar3.pm might exist in the distribution, they are not defined explicitly, but implicitly using the META.* files.

1. How does such a META.* look like, what does it contain? Only things like name and version, which is what a native Perl package might provide as well? Or additional things like license and keyword, maybe everything except dependencies?

2. How do CPAN-clients handle such cases? META.* obviously isn't the Perl package itself and I don't see how it's used to generate it. So what gets actually installed in a system in the end? Is there some additional mechanism generating the package somehow?

3. How is providing META.* instead of *.pm compatible with the key version and the following restriction:

[...]If the package does not have a $VERSION, this field must be omitted.

Does META.* count as a package containing $VERSION in this case? Or is it expected that somehow the package gets generated in the end and that simply must have $VERSION as well and as long as the package isn't generated, the version of META.* can simply be used?

Thanks for your clarification!

Answer 1

The provides metadata is a list of the packages provided by the distribution primarily for use by the PAUSE indexer, but also may be used by analysis tools. If it is present, PAUSE will not inspect your files for packages and their versions but will trust provides. For each package in the distribution it must list the file in which the package resides, and the version of the package if it has one. Since this is an "override", it is not required to match reality, but unless you're doing something very strange it should. The ability to set the file to META.yml or META.json is simply a fallback if you have a package which has no associated file; it is extremely uncommon that you will need to do this, and it places no additional requirement on the META.json or META.yml except they should exist. As always, in implementation this metadata is always set in META.json and META.yml included in the distribution.