The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CPAN-Meta-X-0.008
River stage one • 1 direct dependent • 1 total dependent
++
/ CPAN::Meta::X

NAME

CPAN::Meta::X - Custom (x_*) keys in CPAN distribution metadata being used in the wild

VERSION

This document describes version 0.008 of CPAN::Meta::X (from Perl distribution CPAN-Meta-X), released on 2022-10-28.

DESCRIPTION

The CPAN distribution metadata specification allows custom keys (those that begin with x_ or X_) to be added to the metadata. This document tries to catalog the custom keys that are being used by CPAN authors.

In addition to custom metadata keys, this document also lists:

  • custom phases and relationships in the prereqs hash that are being used by people

  • custom keys in resources hash

CUSTOM DISTRIBUTION METADATA KEYS

x_Dist_Zilla key

A big structure recording information related to Dist::Zilla which presumably is used to build the current distribution. Some of the things being put in here include: perl version used to build the distribution, Dist::Zilla plugins used to build the distribution, and so on.

x_authority key

x_contributors key

List of contributors in a release.

Examples:

TBD

References:

x_deprecated key

x_examples key

List prerequisites for example scripts.

References:

x_generated_by_perl key

x_help_wanted key

x_provides_scripts key

List scripts that are being provided in the distribution. The structure is modelled after the standard provides hash.

Examples:

So say your distribution provides a "csv2json" script, your META.json would contain:

 "x_provides_scripts": {
   "csv2json": {
     "version": "0.1",
     "file": "bin/csv2json"
   }
 }

References:

x_spdx_expression key

x_serialization_backend key

x_static_install key

CUSTOM PREREQS PHASES

x_benchmarks phase

Express that the current distribution is benchmarking the specified module.

References:

x_lists phase

Express that the current distribution is including the specified module in some list(s), e.g. an Acme::CPANModules list.

References:

x_mentions phase

Express that the current distribution is mentioning the specified module.

References:

CUSTOM PREREQS RELATIONSHIPS

x_alt_for relationship

Express that a distribution provides an alternate (implementation) for a module.

Example: Perinci::Access::Lite distribution specifies a runtime x_alt_for prereq relationship to Perinci::Access.

IDEA: The more specific nature of alternate could be specified further in additional relationsip e.g. x_lightweight_alt_for, x_tiny_alt_for, x_windows_alt_for, etc, if needed.

x_benchmarks relationship

See "x_benchmarks phase".

x_features_from relationship

Express that one of the modules in the current distribution is declaring features that are defined defined in an associated Module::Features::* module. Used with (phase=develop).

Examples: Text::ANSITable, Text::Table::More, and Text::Table::Sprintf declares features defined by Module::Features::TextTable so they add a dependency (phase=develop, rel=x_features_from) to Module::Features::TextTable.

References:

x_lists relationship

See "x_lists phase".

x_mentions relationship

See "x_mentions phase".

x_spec relationship

Express that the current distribution is following a specification defined in the specified module. Used with (phase=develop).

References:

CUSTOM RESOURCES

x_IRC resource

x_identifier resource

x_mailinglist resource

x_wiki resource

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/CPAN-Meta-X.

SOURCE

Source repository is at https://github.com/perlancar/perl-CPAN-Meta-X.

SEE ALSO

CPAN::Meta::Spec - Specification for CPAN distribution metadata

CPAN::Meta::X::Old

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022, 2021 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=CPAN-Meta-X

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.