diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/CPAN::Meta::Spec.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/CPAN::Meta::Spec.3pm | 1225 |
1 files changed, 1225 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/CPAN::Meta::Spec.3pm b/upstream/mageia-cauldron/man3pm/CPAN::Meta::Spec.3pm new file mode 100644 index 00000000..dcccd16c --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/CPAN::Meta::Spec.3pm @@ -0,0 +1,1225 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "CPAN::Meta::Spec 3pm" +.TH CPAN::Meta::Spec 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CPAN::Meta::Spec \- specification for CPAN distribution metadata +.SH VERSION +.IX Header "VERSION" +version 2.150010 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 10 +\& my $distmeta = { +\& name => \*(AqModule\-Build\*(Aq, +\& abstract => \*(AqBuild and install Perl modules\*(Aq, +\& description => "Module::Build is a system for " +\& . "building, testing, and installing Perl modules. " +\& . "It is meant to ... blah blah blah ...", +\& version => \*(Aq0.36\*(Aq, +\& release_status => \*(Aqstable\*(Aq, +\& author => [ +\& \*(AqKen Williams <kwilliams@cpan.org>\*(Aq, +\& \*(AqModule\-Build List <module\-build@perl.org>\*(Aq, # additional contact +\& ], +\& license => [ \*(Aqperl_5\*(Aq ], +\& prereqs => { +\& runtime => { +\& requires => { +\& \*(Aqperl\*(Aq => \*(Aq5.006\*(Aq, +\& \*(AqExtUtils::Install\*(Aq => \*(Aq0\*(Aq, +\& \*(AqFile::Basename\*(Aq => \*(Aq0\*(Aq, +\& \*(AqFile::Compare\*(Aq => \*(Aq0\*(Aq, +\& \*(AqIO::File\*(Aq => \*(Aq0\*(Aq, +\& }, +\& recommends => { +\& \*(AqArchive::Tar\*(Aq => \*(Aq1.00\*(Aq, +\& \*(AqExtUtils::Install\*(Aq => \*(Aq0.3\*(Aq, +\& \*(AqExtUtils::ParseXS\*(Aq => \*(Aq2.02\*(Aq, +\& }, +\& }, +\& build => { +\& requires => { +\& \*(AqTest::More\*(Aq => \*(Aq0\*(Aq, +\& }, +\& } +\& }, +\& resources => { +\& license => [\*(Aqhttp://dev.perl.org/licenses/\*(Aq], +\& }, +\& optional_features => { +\& domination => { +\& description => \*(AqTake over the world\*(Aq, +\& prereqs => { +\& develop => { requires => { \*(AqGenius::Evil\*(Aq => \*(Aq1.234\*(Aq } }, +\& runtime => { requires => { \*(AqMachine::Weather\*(Aq => \*(Aq2.0\*(Aq } }, +\& }, +\& }, +\& }, +\& dynamic_config => 1, +\& keywords => [ qw/ toolchain cpan dual\-life / ], +\& \*(Aqmeta\-spec\*(Aq => { +\& version => \*(Aq2\*(Aq, +\& url => \*(Aqhttps://metacpan.org/pod/CPAN::Meta::Spec\*(Aq, +\& }, +\& generated_by => \*(AqModule::Build version 0.36\*(Aq, +\& }; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This document describes version 2 of the CPAN distribution metadata +specification, also known as the "CPAN Meta Spec". +.PP +Revisions of this specification for typo corrections and prose +clarifications may be issued as CPAN::Meta::Spec 2.\fIx\fR. These +revisions will never change semantics or add or remove specified +behavior. +.PP +Distribution metadata describe important properties of Perl +distributions. Distribution building tools like Module::Build, +Module::Install, ExtUtils::MakeMaker or Dist::Zilla should create a +metadata file in accordance with this specification and include it with +the distribution for use by automated tools that index, examine, package +or install Perl distributions. +.SH TERMINOLOGY +.IX Header "TERMINOLOGY" +.IP distribution 4 +.IX Item "distribution" +This is the primary object described by the metadata. In the context of +this document it usually refers to a collection of modules, scripts, +and/or documents that are distributed together for other developers to +use. Examples of distributions are \f(CW\*(C`Class\-Container\*(C'\fR, \f(CW\*(C`libwww\-perl\*(C'\fR, +or \f(CW\*(C`DBI\*(C'\fR. +.IP module 4 +.IX Item "module" +This refers to a reusable library of code contained in a single file. +Modules usually contain one or more packages and are often referred +to by the name of a primary package that can be mapped to the file +name. For example, one might refer to \f(CW\*(C`File::Spec\*(C'\fR instead of +\&\fIFile/Spec.pm\fR +.IP package 4 +.IX Item "package" +This refers to a namespace declared with the Perl \f(CW\*(C`package\*(C'\fR statement. +In Perl, packages often have a version number property given by the +\&\f(CW$VERSION\fR variable in the namespace. +.IP consumer 4 +.IX Item "consumer" +This refers to code that reads a metadata file, deserializes it into a +data structure in memory, or interprets a data structure of metadata +elements. +.IP producer 4 +.IX Item "producer" +This refers to code that constructs a metadata data structure, +serializes into a bytestream and/or writes it to disk. +.IP "must, should, may, etc." 4 +.IX Item "must, should, may, etc." +These terms are interpreted as described in IETF RFC 2119. +.SH "DATA TYPES" +.IX Header "DATA TYPES" +Fields in the "STRUCTURE" section describe data elements, each of +which has an associated data type as described herein. There are four +primitive types: Boolean, String, List and Map. Other types are +subtypes of primitives and define compound data structures or define +constraints on the values of a data element. +.SS Boolean +.IX Subsection "Boolean" +A \fIBoolean\fR is used to provide a true or false value. It \fBmust\fR be +represented as a defined value that is either "1" or "0" or stringifies +to those values. +.SS String +.IX Subsection "String" +A \fIString\fR is data element containing a non-zero length sequence of +Unicode characters, such as an ordinary Perl scalar that is not a +reference. +.SS List +.IX Subsection "List" +A \fIList\fR is an ordered collection of zero or more data elements. +Elements of a List may be of mixed types. +.PP +Producers \fBmust\fR represent List elements using a data structure which +unambiguously indicates that multiple values are possible, such as a +reference to a Perl array (an "arrayref"). +.PP +Consumers expecting a List \fBmust\fR consider a String as equivalent to a +List of length 1. +.SS Map +.IX Subsection "Map" +A \fIMap\fR is an unordered collection of zero or more data elements +("values"), indexed by associated String elements ("keys"). The Map's +value elements may be of mixed types. +.SS "License String" +.IX Subsection "License String" +A \fILicense String\fR is a subtype of String with a restricted set of +values. Valid values are described in detail in the description of +the "license" field. +.SS URL +.IX Subsection "URL" +\&\fIURL\fR is a subtype of String containing a Uniform Resource Locator or +Identifier. [ This type is called URL and not URI for historical reasons. ] +.SS Version +.IX Subsection "Version" +A \fIVersion\fR is a subtype of String containing a value that describes +the version number of packages or distributions. Restrictions on format +are described in detail in the "Version Formats" section. +.SS "Version Range" +.IX Subsection "Version Range" +The \fIVersion Range\fR type is a subtype of String. It describes a range +of Versions that may be present or installed to fulfill prerequisites. +It is specified in detail in the "Version Ranges" section. +.SH STRUCTURE +.IX Header "STRUCTURE" +The metadata structure is a data element of type Map. This section +describes valid keys within the Map. +.PP +Any keys not described in this specification document (whether top-level +or within compound data structures described herein) are considered +\&\fIcustom keys\fR and \fBmust\fR begin with an "x" or "X" and be followed by an +underscore; i.e. they must match the pattern: \f(CW\*(C`qr{\eAx_}i\*(C'\fR. If a +custom key refers to a compound data structure, subkeys within it do not +need an "x_" or "X_" prefix. +.PP +Consumers of metadata may ignore any or all custom keys. All other keys +not described herein are invalid and should be ignored by consumers. +Producers must not generate or output invalid keys. +.PP +For each key, an example is provided followed by a description. The +description begins with the version of spec in which the key was added +or in which the definition was modified, whether the key is \fIrequired\fR +or \fIoptional\fR and the data type of the corresponding data element. +These items are in parentheses, brackets and braces, respectively. +.PP +If a data type is a Map or Map subtype, valid subkeys will be described +as well. +.PP +Some fields are marked \fIDeprecated\fR. These are shown for historical +context and must not be produced in or consumed from any metadata structure +of version 2 or higher. +.SS "REQUIRED FIELDS" +.IX Subsection "REQUIRED FIELDS" +\fIabstract\fR +.IX Subsection "abstract" +.PP +Example: +.PP +.Vb 1 +\& abstract => \*(AqBuild and install Perl modules\*(Aq +.Ve +.PP +(Spec 1.2) [required] {String} +.PP +This is a short description of the purpose of the distribution. +.PP +\fIauthor\fR +.IX Subsection "author" +.PP +Example: +.PP +.Vb 1 +\& author => [ \*(AqKen Williams <kwilliams@cpan.org>\*(Aq ] +.Ve +.PP +(Spec 1.2) [required] {List of one or more Strings} +.PP +This List indicates the person(s) to contact concerning the +distribution. The preferred form of the contact string is: +.PP +.Vb 1 +\& contact\-name <email\-address> +.Ve +.PP +This field provides a general contact list independent of other +structured fields provided within the "resources" field, such as +\&\f(CW\*(C`bugtracker\*(C'\fR. The addressee(s) can be contacted for any purpose +including but not limited to (security) problems with the distribution, +questions about the distribution or bugs in the distribution. +.PP +A distribution's original author is usually the contact listed within +this field. Co-maintainers, successor maintainers or mailing lists +devoted to the distribution may also be listed in addition to or instead +of the original author. +.PP +\fIdynamic_config\fR +.IX Subsection "dynamic_config" +.PP +Example: +.PP +.Vb 1 +\& dynamic_config => 1 +.Ve +.PP +(Spec 2) [required] {Boolean} +.PP +A boolean flag indicating whether a \fIBuild.PL\fR or \fIMakefile.PL\fR (or +similar) must be executed to determine prerequisites. +.PP +This field should be set to a true value if the distribution performs +some dynamic configuration (asking questions, sensing the environment, +etc.) as part of its configuration. This field should be set to a false +value to indicate that prerequisites included in metadata may be +considered final and valid for static analysis. +.PP +Note: when this field is true, post-configuration prerequisites are not +guaranteed to bear any relation whatsoever to those stated in the metadata, +and relying on them doing so is an error. See also +"Prerequisites for dynamically configured distributions" in the implementors' +notes. +.PP +This field explicitly \fBdoes not\fR indicate whether installation may be +safely performed without using a Makefile or Build file, as there may be +special files to install or custom installation targets (e.g. for +dual-life modules that exist on CPAN as well as in the Perl core). This +field only defines whether or not prerequisites are exactly as given in the +metadata. +.PP +\fIgenerated_by\fR +.IX Subsection "generated_by" +.PP +Example: +.PP +.Vb 1 +\& generated_by => \*(AqModule::Build version 0.36\*(Aq +.Ve +.PP +(Spec 1.0) [required] {String} +.PP +This field indicates the tool that was used to create this metadata. +There are no defined semantics for this field, but it is traditional to +use a string in the form "Generating::Package version 1.23" or the +author's name, if the file was generated by hand. +.PP +\fIlicense\fR +.IX Subsection "license" +.PP +Example: +.PP +.Vb 1 +\& license => [ \*(Aqperl_5\*(Aq ] +\& +\& license => [ \*(Aqapache_2_0\*(Aq, \*(Aqmozilla_1_0\*(Aq ] +.Ve +.PP +(Spec 2) [required] {List of one or more License Strings} +.PP +One or more licenses that apply to some or all of the files in the +distribution. If multiple licenses are listed, the distribution +documentation should be consulted to clarify the interpretation of +multiple licenses. +.PP +The following list of license strings are valid: +.PP +.Vb 10 +\& string description +\& \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& agpl_3 GNU Affero General Public License, Version 3 +\& apache_1_1 Apache Software License, Version 1.1 +\& apache_2_0 Apache License, Version 2.0 +\& artistic_1 Artistic License, (Version 1) +\& artistic_2 Artistic License, Version 2.0 +\& bsd BSD License (three\-clause) +\& freebsd FreeBSD License (two\-clause) +\& gfdl_1_2 GNU Free Documentation License, Version 1.2 +\& gfdl_1_3 GNU Free Documentation License, Version 1.3 +\& gpl_1 GNU General Public License, Version 1 +\& gpl_2 GNU General Public License, Version 2 +\& gpl_3 GNU General Public License, Version 3 +\& lgpl_2_1 GNU Lesser General Public License, Version 2.1 +\& lgpl_3_0 GNU Lesser General Public License, Version 3.0 +\& mit MIT (aka X11) License +\& mozilla_1_0 Mozilla Public License, Version 1.0 +\& mozilla_1_1 Mozilla Public License, Version 1.1 +\& openssl OpenSSL License +\& perl_5 The Perl 5 License (Artistic 1 & GPL 1 or later) +\& qpl_1_0 Q Public License, Version 1.0 +\& ssleay Original SSLeay License +\& sun Sun Internet Standards Source License (SISSL) +\& zlib zlib License +.Ve +.PP +The following license strings are also valid and indicate other +licensing not described above: +.PP +.Vb 6 +\& string description +\& \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& open_source Other Open Source Initiative (OSI) approved license +\& restricted Requires special permission from copyright holder +\& unrestricted Not an OSI approved license, but not restricted +\& unknown License not provided in metadata +.Ve +.PP +All other strings are invalid in the license field. +.PP +\fImeta-spec\fR +.IX Subsection "meta-spec" +.PP +Example: +.PP +.Vb 4 +\& \*(Aqmeta\-spec\*(Aq => { +\& version => \*(Aq2\*(Aq, +\& url => \*(Aqhttp://search.cpan.org/perldoc?CPAN::Meta::Spec\*(Aq, +\& } +.Ve +.PP +(Spec 1.2) [required] {Map} +.PP +This field indicates the version of the CPAN Meta Spec that should be +used to interpret the metadata. Consumers must check this key as soon +as possible and abort further metadata processing if the meta-spec +version is not supported by the consumer. +.PP +The following keys are valid, but only \f(CW\*(C`version\*(C'\fR is required. +.IP version 4 +.IX Item "version" +This subkey gives the integer \fIVersion\fR of the CPAN Meta Spec against +which the document was generated. +.IP url 4 +.IX Item "url" +This is a \fIURL\fR of the metadata specification document corresponding to +the given version. This is strictly for human-consumption and should +not impact the interpretation of the document. +.Sp +For the version 2 spec, either of these are recommended: +.RS 4 +.IP \(bu 4 +\&\f(CW\*(C`https://metacpan.org/pod/CPAN::Meta::Spec\*(C'\fR +.IP \(bu 4 +\&\f(CW\*(C`http://search.cpan.org/perldoc?CPAN::Meta::Spec\*(C'\fR +.RE +.RS 4 +.RE +.PP +\fIname\fR +.IX Subsection "name" +.PP +Example: +.PP +.Vb 1 +\& name => \*(AqModule\-Build\*(Aq +.Ve +.PP +(Spec 1.0) [required] {String} +.PP +This field is the name of the distribution. This is often created by +taking the "main package" in the distribution and changing \f(CW\*(C`::\*(C'\fR to +\&\f(CW\*(C`\-\*(C'\fR, but the name may be completely unrelated to the packages within +the distribution. For example, LWP::UserAgent is distributed as part +of the distribution name "libwww-perl". +.PP +\fIrelease_status\fR +.IX Subsection "release_status" +.PP +Example: +.PP +.Vb 1 +\& release_status => \*(Aqstable\*(Aq +.Ve +.PP +(Spec 2) [required] {String} +.PP +This field provides the release status of this distribution. If the +\&\f(CW\*(C`version\*(C'\fR field contains an underscore character, then +\&\f(CW\*(C`release_status\*(C'\fR \fBmust not\fR be "stable." +.PP +The \f(CW\*(C`release_status\*(C'\fR field \fBmust\fR have one of the following values: +.IP stable 4 +.IX Item "stable" +This indicates an ordinary, "final" release that should be indexed by PAUSE +or other indexers. +.IP testing 4 +.IX Item "testing" +This indicates a "beta" release that is substantially complete, but has an +elevated risk of bugs and requires additional testing. The distribution +should not be installed over a stable release without an explicit request +or other confirmation from a user. This release status may also be used +for "release candidate" versions of a distribution. +.IP unstable 4 +.IX Item "unstable" +This indicates an "alpha" release that is under active development, but has +been released for early feedback or testing and may be missing features or +may have serious bugs. The distribution should not be installed over a +stable release without an explicit request or other confirmation from a +user. +.PP +Consumers \fBmay\fR use this field to determine how to index the +distribution for CPAN or other repositories in addition to or in +replacement of heuristics based on version number or file name. +.PP +\fIversion\fR +.IX Subsection "version" +.PP +Example: +.PP +.Vb 1 +\& version => \*(Aq0.36\*(Aq +.Ve +.PP +(Spec 1.0) [required] {Version} +.PP +This field gives the version of the distribution to which the metadata +structure refers. +.SS "OPTIONAL FIELDS" +.IX Subsection "OPTIONAL FIELDS" +\fIdescription\fR +.IX Subsection "description" +.PP +Example: +.PP +.Vb 3 +\& description => "Module::Build is a system for " +\& . "building, testing, and installing Perl modules. " +\& . "It is meant to ... blah blah blah ...", +.Ve +.PP +(Spec 2) [optional] {String} +.PP +A longer, more complete description of the purpose or intended use of +the distribution than the one provided by the \f(CW\*(C`abstract\*(C'\fR key. +.PP +\fIkeywords\fR +.IX Subsection "keywords" +.PP +Example: +.PP +.Vb 1 +\& keywords => [ qw/ toolchain cpan dual\-life / ] +.Ve +.PP +(Spec 1.1) [optional] {List of zero or more Strings} +.PP +A List of keywords that describe this distribution. Keywords +\&\fBmust not\fR include whitespace. +.PP +\fIno_index\fR +.IX Subsection "no_index" +.PP +Example: +.PP +.Vb 6 +\& no_index => { +\& file => [ \*(AqMy/Module.pm\*(Aq ], +\& directory => [ \*(AqMy/Private\*(Aq ], +\& package => [ \*(AqMy::Module::Secret\*(Aq ], +\& namespace => [ \*(AqMy::Module::Sample\*(Aq ], +\& } +.Ve +.PP +(Spec 1.2) [optional] {Map} +.PP +This Map describes any files, directories, packages, and namespaces that +are private to the packaging or implementation of the distribution and +should be ignored by indexing or search tools. Note that this is a list of +exclusions, and the spec does not define what to \fIinclude\fR \- see +"Indexing distributions a la PAUSE" in the implementors notes for more +information. +.PP +Valid subkeys are as follows: +.IP file 4 +.IX Item "file" +A \fIList\fR of relative paths to files. Paths \fBmust be\fR specified with +unix conventions. +.IP directory 4 +.IX Item "directory" +A \fIList\fR of relative paths to directories. Paths \fBmust be\fR specified +with unix conventions. +.Sp +[ Note: previous editions of the spec had \f(CW\*(C`dir\*(C'\fR instead of \f(CW\*(C`directory\*(C'\fR ] +.IP package 4 +.IX Item "package" +A \fIList\fR of package names. +.IP namespace 4 +.IX Item "namespace" +A \fIList\fR of package namespaces, where anything below the namespace +must be ignored, but \fInot\fR the namespace itself. +.Sp +In the example above for \f(CW\*(C`no_index\*(C'\fR, \f(CW\*(C`My::Module::Sample::Foo\*(C'\fR would +be ignored, but \f(CW\*(C`My::Module::Sample\*(C'\fR would not. +.PP +\fIoptional_features\fR +.IX Subsection "optional_features" +.PP +Example: +.PP +.Vb 12 +\& optional_features => { +\& sqlite => { +\& description => \*(AqProvides SQLite support\*(Aq, +\& prereqs => { +\& runtime => { +\& requires => { +\& \*(AqDBD::SQLite\*(Aq => \*(Aq1.25\*(Aq +\& } +\& } +\& } +\& } +\& } +.Ve +.PP +(Spec 2) [optional] {Map} +.PP +This Map describes optional features with incremental prerequisites. +Each key of the \f(CW\*(C`optional_features\*(C'\fR Map is a String used to identify +the feature and each value is a Map with additional information about +the feature. Valid subkeys include: +.IP description 4 +.IX Item "description" +This is a String describing the feature. Every optional feature +should provide a description +.IP prereqs 4 +.IX Item "prereqs" +This entry is required and has the same structure as that of the +\&\f(CW"prereqs"\fR key. It provides a list of package requirements +that must be satisfied for the feature to be supported or enabled. +.Sp +There is one crucial restriction: the prereqs of an optional feature +\&\fBmust not\fR include \f(CW\*(C`configure\*(C'\fR phase prereqs. +.PP +Consumers \fBmust not\fR include optional features as prerequisites without +explicit instruction from users (whether via interactive prompting, +a function parameter or a configuration value, etc. ). +.PP +If an optional feature is used by a consumer to add additional +prerequisites, the consumer should merge the optional feature +prerequisites into those given by the \f(CW\*(C`prereqs\*(C'\fR key using the same +semantics. See "Merging and Resolving Prerequisites" for details on +merging prerequisites. +.PP +\&\fISuggestion for disuse:\fR Because there is currently no way for a +distribution to specify a dependency on an optional feature of another +dependency, the use of \f(CW\*(C`optional_feature\*(C'\fR is discouraged. Instead, +create a separate, installable distribution that ensures the desired +feature is available. For example, if \f(CW\*(C`Foo::Bar\*(C'\fR has a \f(CW\*(C`Baz\*(C'\fR feature, +release a separate \f(CW\*(C`Foo\-Bar\-Baz\*(C'\fR distribution that satisfies +requirements for the feature. +.PP +\fIprereqs\fR +.IX Subsection "prereqs" +.PP +Example: +.PP +.Vb 10 +\& prereqs => { +\& runtime => { +\& requires => { +\& \*(Aqperl\*(Aq => \*(Aq5.006\*(Aq, +\& \*(AqFile::Spec\*(Aq => \*(Aq0.86\*(Aq, +\& \*(AqJSON\*(Aq => \*(Aq2.16\*(Aq, +\& }, +\& recommends => { +\& \*(AqJSON::XS\*(Aq => \*(Aq2.26\*(Aq, +\& }, +\& suggests => { +\& \*(AqArchive::Tar\*(Aq => \*(Aq0\*(Aq, +\& }, +\& }, +\& build => { +\& requires => { +\& \*(AqAlien::SDL\*(Aq => \*(Aq1.00\*(Aq, +\& }, +\& }, +\& test => { +\& recommends => { +\& \*(AqTest::Deep\*(Aq => \*(Aq0.10\*(Aq, +\& }, +\& } +\& } +.Ve +.PP +(Spec 2) [optional] {Map} +.PP +This is a Map that describes all the prerequisites of the distribution. +The keys are phases of activity, such as \f(CW\*(C`configure\*(C'\fR, \f(CW\*(C`build\*(C'\fR, \f(CW\*(C`test\*(C'\fR +or \f(CW\*(C`runtime\*(C'\fR. Values are Maps in which the keys name the type of +prerequisite relationship such as \f(CW\*(C`requires\*(C'\fR, \f(CW\*(C`recommends\*(C'\fR, or +\&\f(CW\*(C`suggests\*(C'\fR and the value provides a set of prerequisite relations. The +set of relations \fBmust\fR be specified as a Map of package names to +version ranges. +.PP +The full definition for this field is given in the "Prereq Spec" +section. +.PP +\fIprovides\fR +.IX Subsection "provides" +.PP +Example: +.PP +.Vb 10 +\& provides => { +\& \*(AqFoo::Bar\*(Aq => { +\& file => \*(Aqlib/Foo/Bar.pm\*(Aq, +\& version => \*(Aq0.27_02\*(Aq, +\& }, +\& \*(AqFoo::Bar::Blah\*(Aq => { +\& file => \*(Aqlib/Foo/Bar/Blah.pm\*(Aq, +\& }, +\& \*(AqFoo::Bar::Baz\*(Aq => { +\& file => \*(Aqlib/Foo/Bar/Baz.pm\*(Aq, +\& version => \*(Aq0.3\*(Aq, +\& }, +\& } +.Ve +.PP +(Spec 1.2) [optional] {Map} +.PP +This describes all packages provided by this distribution. This +information is used by distribution and automation mechanisms like +PAUSE, CPAN, metacpan.org and search.cpan.org to build indexes saying in +which distribution various packages can be found. +.PP +The keys of \f(CW\*(C`provides\*(C'\fR are package names that can be found within +the distribution. If a package name key is provided, it must +have a Map with the following valid subkeys: +.IP file 4 +.IX Item "file" +This field is required. It must contain a Unix-style relative file path +from the root of the distribution directory to a file that contains or +generates the package. It may be given as \f(CW\*(C`META.yml\*(C'\fR or \f(CW\*(C`META.json\*(C'\fR +to claim a package for indexing without needing a \f(CW\*(C`*.pm\*(C'\fR. +.IP version 4 +.IX Item "version" +If it exists, this field must contains a \fIVersion\fR String for the +package. If the package does not have a \f(CW$VERSION\fR, this field must +be omitted. +.PP +\fIresources\fR +.IX Subsection "resources" +.PP +Example: +.PP +.Vb 10 +\& resources => { +\& license => [ \*(Aqhttp://dev.perl.org/licenses/\*(Aq ], +\& homepage => \*(Aqhttp://sourceforge.net/projects/module\-build\*(Aq, +\& bugtracker => { +\& web => \*(Aqhttp://rt.cpan.org/Public/Dist/Display.html?Name=CPAN\-Meta\*(Aq, +\& mailto => \*(Aqmeta\-bugs@example.com\*(Aq, +\& }, +\& repository => { +\& url => \*(Aqgit://github.com/dagolden/cpan\-meta.git\*(Aq, +\& web => \*(Aqhttp://github.com/dagolden/cpan\-meta\*(Aq, +\& type => \*(Aqgit\*(Aq, +\& }, +\& x_twitter => \*(Aqhttp://twitter.com/cpan_linked/\*(Aq, +\& } +.Ve +.PP +(Spec 2) [optional] {Map} +.PP +This field describes resources related to this distribution. +.PP +Valid subkeys include: +.IP homepage 4 +.IX Item "homepage" +The official home of this project on the web. +.IP license 4 +.IX Item "license" +A List of \fIURL\fR's that relate to this distribution's license. As with the +top-level \f(CW\*(C`license\*(C'\fR field, distribution documentation should be consulted +to clarify the interpretation of multiple licenses provided here. +.IP bugtracker 4 +.IX Item "bugtracker" +This entry describes the bug tracking system for this distribution. It +is a Map with the following valid keys: +.Sp +.Vb 2 +\& web \- a URL pointing to a web front\-end for the bug tracker +\& mailto \- an email address to which bugs can be sent +.Ve +.IP repository 4 +.IX Item "repository" +This entry describes the source control repository for this distribution. It +is a Map with the following valid keys: +.Sp +.Vb 3 +\& url \- a URL pointing to the repository itself +\& web \- a URL pointing to a web front\-end for the repository +\& type \- a lowercase string indicating the VCS used +.Ve +.Sp +Because a url like \f(CW\*(C`http://myrepo.example.com/\*(C'\fR is ambiguous as to +type, producers should provide a \f(CW\*(C`type\*(C'\fR whenever a \f(CW\*(C`url\*(C'\fR key is given. +The \f(CW\*(C`type\*(C'\fR field should be the name of the most common program used +to work with the repository, e.g. \f(CW\*(C`git\*(C'\fR, \f(CW\*(C`svn\*(C'\fR, \f(CW\*(C`cvs\*(C'\fR, \f(CW\*(C`darcs\*(C'\fR, +\&\f(CW\*(C`bzr\*(C'\fR or \f(CW\*(C`hg\*(C'\fR. +.SS "DEPRECATED FIELDS" +.IX Subsection "DEPRECATED FIELDS" +\fIbuild_requires\fR +.IX Subsection "build_requires" +.PP +\&\fI(Deprecated in Spec 2)\fR [optional] {String} +.PP +Replaced by \f(CW\*(C`prereqs\*(C'\fR +.PP +\fIconfigure_requires\fR +.IX Subsection "configure_requires" +.PP +\&\fI(Deprecated in Spec 2)\fR [optional] {String} +.PP +Replaced by \f(CW\*(C`prereqs\*(C'\fR +.PP +\fIconflicts\fR +.IX Subsection "conflicts" +.PP +\&\fI(Deprecated in Spec 2)\fR [optional] {String} +.PP +Replaced by \f(CW\*(C`prereqs\*(C'\fR +.PP +\fIdistribution_type\fR +.IX Subsection "distribution_type" +.PP +\&\fI(Deprecated in Spec 2)\fR [optional] {String} +.PP +This field indicated 'module' or 'script' but was considered +meaningless, since many distributions are hybrids of several kinds of +things. +.PP +\fIlicense_uri\fR +.IX Subsection "license_uri" +.PP +\&\fI(Deprecated in Spec 1.2)\fR [optional] {URL} +.PP +Replaced by \f(CW\*(C`license\*(C'\fR in \f(CW\*(C`resources\*(C'\fR +.PP +\fIprivate\fR +.IX Subsection "private" +.PP +\&\fI(Deprecated in Spec 1.2)\fR [optional] {Map} +.PP +This field has been renamed to "no_index". +.PP +\fIrecommends\fR +.IX Subsection "recommends" +.PP +\&\fI(Deprecated in Spec 2)\fR [optional] {String} +.PP +Replaced by \f(CW\*(C`prereqs\*(C'\fR +.PP +\fIrequires\fR +.IX Subsection "requires" +.PP +\&\fI(Deprecated in Spec 2)\fR [optional] {String} +.PP +Replaced by \f(CW\*(C`prereqs\*(C'\fR +.SH "VERSION NUMBERS" +.IX Header "VERSION NUMBERS" +.SS "Version Formats" +.IX Subsection "Version Formats" +This section defines the Version type, used by several fields in the +CPAN Meta Spec. +.PP +Version numbers must be treated as strings, not numbers. For +example, \f(CW1.200\fR \fBmust not\fR be serialized as \f(CW1.2\fR. Version +comparison should be delegated to the Perl version module, version +0.80 or newer. +.PP +Unless otherwise specified, version numbers \fBmust\fR appear in one of two +formats: +.IP "Decimal versions" 4 +.IX Item "Decimal versions" +Decimal versions are regular "decimal numbers", with some limitations. +They \fBmust\fR be non-negative and \fBmust\fR begin and end with a digit. A +single underscore \fBmay\fR be included, but \fBmust\fR be between two digits. +They \fBmust not\fR use exponential notation ("1.23e\-2"). +.Sp +.Vb 2 +\& version => \*(Aq1.234\*(Aq # OK +\& version => \*(Aq1.23_04\*(Aq # OK +\& +\& version => \*(Aq1.23_04_05\*(Aq # Illegal +\& version => \*(Aq1.\*(Aq # Illegal +\& version => \*(Aq.1\*(Aq # Illegal +.Ve +.IP "Dotted-integer versions" 4 +.IX Item "Dotted-integer versions" +Dotted-integer (also known as dotted-decimal) versions consist of +positive integers separated by full stop characters (i.e. "dots", +"periods" or "decimal points"). This are equivalent in format to Perl +"v\-strings", with some additional restrictions on form. They must be +given in "normal" form, which has a leading "v" character and at least +three integer components. To retain a one-to-one mapping with decimal +versions, all components after the first \fBshould\fR be restricted to the +range 0 to 999. The final component \fBmay\fR be separated by an +underscore character instead of a period. +.Sp +.Vb 5 +\& version => \*(Aqv1.2.3\*(Aq # OK +\& version => \*(Aqv1.2_3\*(Aq # OK +\& version => \*(Aqv1.2.3.4\*(Aq # OK +\& version => \*(Aqv1.2.3_4\*(Aq # OK +\& version => \*(Aqv2009.10.31\*(Aq # OK +\& +\& version => \*(Aqv1.2\*(Aq # Illegal +\& version => \*(Aq1.2.3\*(Aq # Illegal +\& version => \*(Aqv1.2_3_4\*(Aq # Illegal +\& version => \*(Aqv1.2009.10.31\*(Aq # Not recommended +.Ve +.SS "Version Ranges" +.IX Subsection "Version Ranges" +Some fields (prereq, optional_features) indicate the particular +version(s) of some other module that may be required as a prerequisite. +This section details the Version Range type used to provide this +information. +.PP +The simplest format for a Version Range is just the version +number itself, e.g. \f(CW2.4\fR. This means that \fBat least\fR version 2.4 +must be present. To indicate that \fBany\fR version of a prerequisite is +okay, even if the prerequisite doesn't define a version at all, use +the version \f(CW0\fR. +.PP +Alternatively, a version range \fBmay\fR use the operators < (less than), +<= (less than or equal), > (greater than), >= (greater than +or equal), == (equal), and != (not equal). For example, the +specification \f(CW\*(C`< 2.0\*(C'\fR means that any version of the prerequisite +less than 2.0 is suitable. +.PP +For more complicated situations, version specifications \fBmay\fR be AND-ed +together using commas. The specification \f(CW>= 1.2, != 1.5, < +2.0\fR indicates a version that must be \fBat least\fR 1.2, \fBless than\fR 2.0, +and \fBnot equal to\fR 1.5. +.SH PREREQUISITES +.IX Header "PREREQUISITES" +.SS "Prereq Spec" +.IX Subsection "Prereq Spec" +The \f(CW\*(C`prereqs\*(C'\fR key in the top-level metadata and within +\&\f(CW\*(C`optional_features\*(C'\fR define the relationship between a distribution and +other packages. The prereq spec structure is a hierarchical data +structure which divides prerequisites into \fIPhases\fR of activity in the +installation process and \fIRelationships\fR that indicate how +prerequisites should be resolved. +.PP +For example, to specify that \f(CW\*(C`Data::Dumper\*(C'\fR is \f(CW\*(C`required\*(C'\fR during the +\&\f(CW\*(C`test\*(C'\fR phase, this entry would appear in the distribution metadata: +.PP +.Vb 7 +\& prereqs => { +\& test => { +\& requires => { +\& \*(AqData::Dumper\*(Aq => \*(Aq2.00\*(Aq +\& } +\& } +\& } +.Ve +.PP +\fIPhases\fR +.IX Subsection "Phases" +.PP +Requirements for regular use must be listed in the \f(CW\*(C`runtime\*(C'\fR phase. +Other requirements should be listed in the earliest stage in which they +are required and consumers must accumulate and satisfy requirements +across phases before executing the activity. For example, \f(CW\*(C`build\*(C'\fR +requirements must also be available during the \f(CW\*(C`test\*(C'\fR phase. +.PP +.Vb 4 +\& before action requirements that must be met +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& perl Build.PL configure +\& perl Makefile.PL +\& +\& make configure, runtime, build +\& Build +\& +\& make test configure, runtime, build, test +\& Build test +.Ve +.PP +Consumers that install the distribution must ensure that +\&\fIruntime\fR requirements are also installed and may install +dependencies from other phases. +.PP +.Vb 4 +\& after action requirements that must be met +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& make install runtime +\& Build install +.Ve +.IP configure 4 +.IX Item "configure" +The configure phase occurs before any dynamic configuration has been +attempted. Libraries required by the configure phase \fBmust\fR be +available for use before the distribution building tool has been +executed. +.IP build 4 +.IX Item "build" +The build phase is when the distribution's source code is compiled (if +necessary) and otherwise made ready for installation. +.IP test 4 +.IX Item "test" +The test phase is when the distribution's automated test suite is run. +Any library that is needed only for testing and not for subsequent use +should be listed here. +.IP runtime 4 +.IX Item "runtime" +The runtime phase refers not only to when the distribution's contents +are installed, but also to its continued use. Any library that is a +prerequisite for regular use of this distribution should be indicated +here. +.IP develop 4 +.IX Item "develop" +The develop phase's prereqs are libraries needed to work on the +distribution's source code as its author does. These tools might be +needed to build a release tarball, to run author-only tests, or to +perform other tasks related to developing new versions of the +distribution. +.PP +\fIRelationships\fR +.IX Subsection "Relationships" +.IP requires 4 +.IX Item "requires" +These dependencies \fBmust\fR be installed for proper completion of the +phase. +.IP recommends 4 +.IX Item "recommends" +Recommended dependencies are \fIstrongly\fR encouraged and should be +satisfied except in resource constrained environments. +.IP suggests 4 +.IX Item "suggests" +These dependencies are optional, but are suggested for enhanced operation +of the described distribution. +.IP conflicts 4 +.IX Item "conflicts" +These libraries cannot be installed when the phase is in operation. +This is a very rare situation, and the \f(CW\*(C`conflicts\*(C'\fR relationship should +be used with great caution, or not at all. +.SS "Merging and Resolving Prerequisites" +.IX Subsection "Merging and Resolving Prerequisites" +Whenever metadata consumers merge prerequisites, either from different +phases or from \f(CW\*(C`optional_features\*(C'\fR, they should merged in a way which +preserves the intended semantics of the prerequisite structure. Generally, +this means concatenating the version specifications using commas, as +described in the "Version Ranges" section. +.PP +Another subtle error that can occur in resolving prerequisites comes from +the way that modules in prerequisites are indexed to distribution files on +CPAN. When a module is deleted from a distribution, prerequisites calling +for that module could indicate an older distribution should be installed, +potentially overwriting files from a newer distribution. +.PP +For example, as of Oct 31, 2009, the CPAN index file contained these +module-distribution mappings: +.PP +.Vb 3 +\& Class::MOP 0.94 D/DR/DROLSKY/Class\-MOP\-0.94.tar.gz +\& Class::MOP::Class 0.94 D/DR/DROLSKY/Class\-MOP\-0.94.tar.gz +\& Class::MOP::Class::Immutable 0.04 S/ST/STEVAN/Class\-MOP\-0.36.tar.gz +.Ve +.PP +Consider the case where "Class::MOP" 0.94 is installed. If a +distribution specified "Class::MOP::Class::Immutable" as a prerequisite, +it could result in Class\-MOP\-0.36.tar.gz being installed, overwriting +any files from Class\-MOP\-0.94.tar.gz. +.PP +Consumers of metadata \fBshould\fR test whether prerequisites would result +in installed module files being "downgraded" to an older version and +\&\fBmay\fR warn users or ignore the prerequisite that would cause such a +result. +.SH SERIALIZATION +.IX Header "SERIALIZATION" +Distribution metadata should be serialized (as a hashref) as +JSON-encoded data and packaged with distributions as the file +\&\fIMETA.json\fR. +.PP +In the past, the distribution metadata structure had been packed with +distributions as \fIMETA.yml\fR, a file in the YAML Tiny format (for which, +see YAML::Tiny). Tools that consume distribution metadata from disk +should be capable of loading \fIMETA.yml\fR, but should prefer \fIMETA.json\fR +if both are found. +.SH "NOTES FOR IMPLEMENTORS" +.IX Header "NOTES FOR IMPLEMENTORS" +.SS "Extracting Version Numbers from Perl Modules" +.IX Subsection "Extracting Version Numbers from Perl Modules" +To get the version number from a Perl module, consumers should use the +\&\f(CW\*(C`MM\->parse_version($file)\*(C'\fR method provided by +ExtUtils::MakeMaker or Module::Metadata. For example, for the +module given by \f(CW$mod\fR, the version may be retrieved in one of the +following ways: +.PP +.Vb 3 +\& # via ExtUtils::MakeMaker +\& my $file = MM\->_installed_file_for_module($mod); +\& my $version = MM\->parse_version($file) +.Ve +.PP +The private \f(CW\*(C`_installed_file_for_module\*(C'\fR method may be replaced with +other methods for locating a module in \f(CW@INC\fR. +.PP +.Vb 3 +\& # via Module::Metadata +\& my $info = Module::Metadata\->new_from_module($mod); +\& my $version = $info\->version; +.Ve +.PP +If only a filename is available, the following approach may be used: +.PP +.Vb 3 +\& # via Module::Build +\& my $info = Module::Metadata\->new_from_file($file); +\& my $version = $info\->version; +.Ve +.SS "Comparing Version Numbers" +.IX Subsection "Comparing Version Numbers" +The version module provides the most reliable way to compare version +numbers in all the various ways they might be provided or might exist +within modules. Given two strings containing version numbers, \f(CW$v1\fR and +\&\f(CW$v2\fR, they should be converted to \f(CW\*(C`version\*(C'\fR objects before using +ordinary comparison operators. For example: +.PP +.Vb 4 +\& use version; +\& if ( version\->new($v1) <=> version\->new($v2) ) { +\& print "Versions are not equal\en"; +\& } +.Ve +.PP +If the only comparison needed is whether an installed module is of a +sufficiently high version, a direct test may be done using the string +form of \f(CW\*(C`eval\*(C'\fR and the \f(CW\*(C`use\*(C'\fR function. For example, for module \f(CW$mod\fR +and version prerequisite \f(CW$prereq\fR: +.PP +.Vb 3 +\& if ( eval "use $mod $prereq (); 1" ) { +\& print "Module $mod version is OK.\en"; +\& } +.Ve +.PP +If the values of \f(CW$mod\fR and \f(CW$prereq\fR have not been scrubbed, however, +this presents security implications. +.SS "Prerequisites for dynamically configured distributions" +.IX Subsection "Prerequisites for dynamically configured distributions" +When \f(CW\*(C`dynamic_config\*(C'\fR is true, it is an error to presume that the +prerequisites given in distribution metadata will have any relationship +whatsoever to the actual prerequisites of the distribution. +.PP +In practice, however, one can generally expect such prerequisites to be +one of two things: +.IP \(bu 4 +The minimum prerequisites for the distribution, to which dynamic configuration will only add items +.IP \(bu 4 +Whatever the distribution configured with on the releaser's machine at release time +.PP +The second case often turns out to have identical results to the first case, +albeit only by accident. +.PP +As such, consumers may use this data for informational analysis, but +presenting it to the user as canonical or relying on it as such is +invariably the height of folly. +.SS "Indexing distributions a la PAUSE" +.IX Subsection "Indexing distributions a la PAUSE" +While no_index tells you what must be ignored when indexing, this spec holds +no opinion on how you should get your initial candidate list of things to +possibly index. For "normal" distributions you might consider simply indexing +the contents of lib/, but there are many fascinating oddities on CPAN and +many dists from the days when it was normal to put the main .pm file in the +root of the distribution archive \- so PAUSE currently indexes all .pm and .PL +files that are not either (a) specifically excluded by no_index (b) in +\&\f(CW\*(C`inc\*(C'\fR, \f(CW\*(C`xt\*(C'\fR, or \f(CW\*(C`t\*(C'\fR directories, or common 'mistake' directories such as +\&\f(CW\*(C`perl5\*(C'\fR. +.PP +Or: If you're trying to be PAUSE-like, make sure you skip \f(CW\*(C`inc\*(C'\fR, \f(CW\*(C`xt\*(C'\fR and +\&\f(CW\*(C`t\*(C'\fR as well as anything marked as no_index. +.PP +Also remember: If the META file contains a provides field, you shouldn't be +indexing anything in the first place \- just use that. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +.IP \(bu 4 +CPAN, <http://www.cpan.org/> +.IP \(bu 4 +JSON, <http://json.org/> +.IP \(bu 4 +YAML, <http://www.yaml.org/> +.IP \(bu 4 +CPAN +.IP \(bu 4 +CPANPLUS +.IP \(bu 4 +ExtUtils::MakeMaker +.IP \(bu 4 +Module::Build +.IP \(bu 4 +Module::Install +.IP \(bu 4 +CPAN::Meta::History::Meta_1_4 +.SH HISTORY +.IX Header "HISTORY" +Ken Williams wrote the original CPAN Meta Spec (also known as the +"META.yml spec") in 2003 and maintained it through several revisions +with input from various members of the community. In 2005, Randy +Sims redrafted it from HTML to POD for the version 1.2 release. Ken +continued to maintain the spec through version 1.4. +.PP +In late 2009, David Golden organized the version 2 proposal review +process. David and Ricardo Signes drafted the final version 2 spec +in April 2010 based on the version 1.4 spec and patches contributed +during the proposal process. +.SH AUTHORS +.IX Header "AUTHORS" +.IP \(bu 4 +David Golden <dagolden@cpan.org> +.IP \(bu 4 +Ricardo Signes <rjbs@cpan.org> +.IP \(bu 4 +Adam Kennedy <adamk@cpan.org> +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors. +.PP +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. |