1CPAN::Meta::Spec(3)   User Contributed Perl Documentation  CPAN::Meta::Spec(3)
2
3
4

NAME

6       CPAN::Meta::Spec - specification for CPAN distribution metadata
7

VERSION

9       version 2.150010
10

SYNOPSIS

12         my $distmeta = {
13           name => 'Module-Build',
14           abstract => 'Build and install Perl modules',
15           description =>  "Module::Build is a system for "
16             . "building, testing, and installing Perl modules. "
17             . "It is meant to ... blah blah blah ...",
18           version  => '0.36',
19           release_status => 'stable',
20           author   => [
21             'Ken Williams <kwilliams@cpan.org>',
22             'Module-Build List <module-build@perl.org>', # additional contact
23           ],
24           license  => [ 'perl_5' ],
25           prereqs => {
26             runtime => {
27               requires => {
28                 'perl'   => '5.006',
29                 'ExtUtils::Install' => '0',
30                 'File::Basename' => '0',
31                 'File::Compare'  => '0',
32                 'IO::File'   => '0',
33               },
34               recommends => {
35                 'Archive::Tar' => '1.00',
36                 'ExtUtils::Install' => '0.3',
37                 'ExtUtils::ParseXS' => '2.02',
38               },
39             },
40             build => {
41               requires => {
42                 'Test::More' => '0',
43               },
44             }
45           },
46           resources => {
47             license => ['http://dev.perl.org/licenses/'],
48           },
49           optional_features => {
50             domination => {
51               description => 'Take over the world',
52               prereqs     => {
53                 develop => { requires => { 'Genius::Evil'     => '1.234' } },
54                 runtime => { requires => { 'Machine::Weather' => '2.0'   } },
55               },
56             },
57           },
58           dynamic_config => 1,
59           keywords => [ qw/ toolchain cpan dual-life / ],
60           'meta-spec' => {
61             version => '2',
62             url     => 'https://metacpan.org/pod/CPAN::Meta::Spec',
63           },
64           generated_by => 'Module::Build version 0.36',
65         };
66

DESCRIPTION

68       This document describes version 2 of the CPAN distribution metadata
69       specification, also known as the "CPAN Meta Spec".
70
71       Revisions of this specification for typo corrections and prose
72       clarifications may be issued as CPAN::Meta::Spec 2.x.  These revisions
73       will never change semantics or add or remove specified behavior.
74
75       Distribution metadata describe important properties of Perl
76       distributions. Distribution building tools like Module::Build,
77       Module::Install, ExtUtils::MakeMaker or Dist::Zilla should create a
78       metadata file in accordance with this specification and include it with
79       the distribution for use by automated tools that index, examine,
80       package or install Perl distributions.
81

TERMINOLOGY

83       distribution
84           This is the primary object described by the metadata. In the
85           context of this document it usually refers to a collection of
86           modules, scripts, and/or documents that are distributed together
87           for other developers to use.  Examples of distributions are
88           "Class-Container", "libwww-perl", or "DBI".
89
90       module
91           This refers to a reusable library of code contained in a single
92           file.  Modules usually contain one or more packages and are often
93           referred to by the name of a primary package that can be mapped to
94           the file name. For example, one might refer to "File::Spec" instead
95           of File/Spec.pm
96
97       package
98           This refers to a namespace declared with the Perl "package"
99           statement.  In Perl, packages often have a version number property
100           given by the $VERSION variable in the namespace.
101
102       consumer
103           This refers to code that reads a metadata file, deserializes it
104           into a data structure in memory, or interprets a data structure of
105           metadata elements.
106
107       producer
108           This refers to code that constructs a metadata data structure,
109           serializes into a bytestream and/or writes it to disk.
110
111       must, should, may, etc.
112           These terms are interpreted as described in IETF RFC 2119.
113

DATA TYPES

115       Fields in the "STRUCTURE" section describe data elements, each of which
116       has an associated data type as described herein.  There are four
117       primitive types: Boolean, String, List and Map.  Other types are
118       subtypes of primitives and define compound data structures or define
119       constraints on the values of a data element.
120
121   Boolean
122       A Boolean is used to provide a true or false value.  It must be
123       represented as a defined value that is either "1" or "0" or stringifies
124       to those values.
125
126   String
127       A String is data element containing a non-zero length sequence of
128       Unicode characters, such as an ordinary Perl scalar that is not a
129       reference.
130
131   List
132       A List is an ordered collection of zero or more data elements.
133       Elements of a List may be of mixed types.
134
135       Producers must represent List elements using a data structure which
136       unambiguously indicates that multiple values are possible, such as a
137       reference to a Perl array (an "arrayref").
138
139       Consumers expecting a List must consider a String as equivalent to a
140       List of length 1.
141
142   Map
143       A Map is an unordered collection of zero or more data elements
144       ("values"), indexed by associated String elements ("keys").  The Map's
145       value elements may be of mixed types.
146
147   License String
148       A License String is a subtype of String with a restricted set of
149       values.  Valid values are described in detail in the description of the
150       "license" field.
151
152   URL
153       URL is a subtype of String containing a Uniform Resource Locator or
154       Identifier.  [ This type is called URL and not URI for historical
155       reasons. ]
156
157   Version
158       A Version is a subtype of String containing a value that describes the
159       version number of packages or distributions.  Restrictions on format
160       are described in detail in the "Version Formats" section.
161
162   Version Range
163       The Version Range type is a subtype of String.  It describes a range of
164       Versions that may be present or installed to fulfill prerequisites.  It
165       is specified in detail in the "Version Ranges" section.
166

STRUCTURE

168       The metadata structure is a data element of type Map.  This section
169       describes valid keys within the Map.
170
171       Any keys not described in this specification document (whether top-
172       level or within compound data structures described herein) are
173       considered custom keys and must begin with an "x" or "X" and be
174       followed by an underscore; i.e. they must match the pattern:
175       "qr{\Ax_}i".  If a custom key refers to a compound data structure,
176       subkeys within it do not need an "x_" or "X_" prefix.
177
178       Consumers of metadata may ignore any or all custom keys.  All other
179       keys not described herein are invalid and should be ignored by
180       consumers.  Producers must not generate or output invalid keys.
181
182       For each key, an example is provided followed by a description.  The
183       description begins with the version of spec in which the key was added
184       or in which the definition was modified, whether the key is required or
185       optional and the data type of the corresponding data element.  These
186       items are in parentheses, brackets and braces, respectively.
187
188       If a data type is a Map or Map subtype, valid subkeys will be described
189       as well.
190
191       Some fields are marked Deprecated.  These are shown for historical
192       context and must not be produced in or consumed from any metadata
193       structure of version 2 or higher.
194
195   REQUIRED FIELDS
196       abstract
197
198       Example:
199
200         abstract => 'Build and install Perl modules'
201
202       (Spec 1.2) [required] {String}
203
204       This is a short description of the purpose of the distribution.
205
206       author
207
208       Example:
209
210         author => [ 'Ken Williams <kwilliams@cpan.org>' ]
211
212       (Spec 1.2) [required] {List of one or more Strings}
213
214       This List indicates the person(s) to contact concerning the
215       distribution. The preferred form of the contact string is:
216
217         contact-name <email-address>
218
219       This field provides a general contact list independent of other
220       structured fields provided within the "resources" field, such as
221       "bugtracker".  The addressee(s) can be contacted for any purpose
222       including but not limited to (security) problems with the distribution,
223       questions about the distribution or bugs in the distribution.
224
225       A distribution's original author is usually the contact listed within
226       this field.  Co-maintainers, successor maintainers or mailing lists
227       devoted to the distribution may also be listed in addition to or
228       instead of the original author.
229
230       dynamic_config
231
232       Example:
233
234         dynamic_config => 1
235
236       (Spec 2) [required] {Boolean}
237
238       A boolean flag indicating whether a Build.PL or Makefile.PL (or
239       similar) must be executed to determine prerequisites.
240
241       This field should be set to a true value if the distribution performs
242       some dynamic configuration (asking questions, sensing the environment,
243       etc.) as part of its configuration.  This field should be set to a
244       false value to indicate that prerequisites included in metadata may be
245       considered final and valid for static analysis.
246
247       Note: when this field is true, post-configuration prerequisites are not
248       guaranteed to bear any relation whatsoever to those stated in the
249       metadata, and relying on them doing so is an error. See also
250       "Prerequisites for dynamically configured distributions" in the
251       implementors' notes.
252
253       This field explicitly does not indicate whether installation may be
254       safely performed without using a Makefile or Build file, as there may
255       be special files to install or custom installation targets (e.g. for
256       dual-life modules that exist on CPAN as well as in the Perl core).
257       This field only defines whether or not prerequisites are exactly as
258       given in the metadata.
259
260       generated_by
261
262       Example:
263
264         generated_by => 'Module::Build version 0.36'
265
266       (Spec 1.0) [required] {String}
267
268       This field indicates the tool that was used to create this metadata.
269       There are no defined semantics for this field, but it is traditional to
270       use a string in the form "Generating::Package version 1.23" or the
271       author's name, if the file was generated by hand.
272
273       license
274
275       Example:
276
277         license => [ 'perl_5' ]
278
279         license => [ 'apache_2_0', 'mozilla_1_0' ]
280
281       (Spec 2) [required] {List of one or more License Strings}
282
283       One or more licenses that apply to some or all of the files in the
284       distribution.  If multiple licenses are listed, the distribution
285       documentation should be consulted to clarify the interpretation of
286       multiple licenses.
287
288       The following list of license strings are valid:
289
290        string          description
291        -------------   -----------------------------------------------
292        agpl_3          GNU Affero General Public License, Version 3
293        apache_1_1      Apache Software License, Version 1.1
294        apache_2_0      Apache License, Version 2.0
295        artistic_1      Artistic License, (Version 1)
296        artistic_2      Artistic License, Version 2.0
297        bsd             BSD License (three-clause)
298        freebsd         FreeBSD License (two-clause)
299        gfdl_1_2        GNU Free Documentation License, Version 1.2
300        gfdl_1_3        GNU Free Documentation License, Version 1.3
301        gpl_1           GNU General Public License, Version 1
302        gpl_2           GNU General Public License, Version 2
303        gpl_3           GNU General Public License, Version 3
304        lgpl_2_1        GNU Lesser General Public License, Version 2.1
305        lgpl_3_0        GNU Lesser General Public License, Version 3.0
306        mit             MIT (aka X11) License
307        mozilla_1_0     Mozilla Public License, Version 1.0
308        mozilla_1_1     Mozilla Public License, Version 1.1
309        openssl         OpenSSL License
310        perl_5          The Perl 5 License (Artistic 1 & GPL 1 or later)
311        qpl_1_0         Q Public License, Version 1.0
312        ssleay          Original SSLeay License
313        sun             Sun Internet Standards Source License (SISSL)
314        zlib            zlib License
315
316       The following license strings are also valid and indicate other
317       licensing not described above:
318
319        string          description
320        -------------   -----------------------------------------------
321        open_source     Other Open Source Initiative (OSI) approved license
322        restricted      Requires special permission from copyright holder
323        unrestricted    Not an OSI approved license, but not restricted
324        unknown         License not provided in metadata
325
326       All other strings are invalid in the license field.
327
328       meta-spec
329
330       Example:
331
332         'meta-spec' => {
333           version => '2',
334           url     => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
335         }
336
337       (Spec 1.2) [required] {Map}
338
339       This field indicates the version of the CPAN Meta Spec that should be
340       used to interpret the metadata.  Consumers must check this key as soon
341       as possible and abort further metadata processing if the meta-spec
342       version is not supported by the consumer.
343
344       The following keys are valid, but only "version" is required.
345
346       version
347           This subkey gives the integer Version of the CPAN Meta Spec against
348           which the document was generated.
349
350       url This is a URL of the metadata specification document corresponding
351           to the given version.  This is strictly for human-consumption and
352           should not impact the interpretation of the document.
353
354           For the version 2 spec, either of these are recommended:
355
356           ·   "https://metacpan.org/pod/CPAN::Meta::Spec"
357
358           ·   "http://search.cpan.org/perldoc?CPAN::Meta::Spec"
359
360       name
361
362       Example:
363
364         name => 'Module-Build'
365
366       (Spec 1.0) [required] {String}
367
368       This field is the name of the distribution.  This is often created by
369       taking the "main package" in the distribution and changing "::" to "-",
370       but the name may be completely unrelated to the packages within the
371       distribution.  For example, LWP::UserAgent is distributed as part of
372       the distribution name "libwww-perl".
373
374       release_status
375
376       Example:
377
378         release_status => 'stable'
379
380       (Spec 2) [required] {String}
381
382       This field provides the  release status of this distribution.  If the
383       "version" field contains an underscore character, then "release_status"
384       must not be "stable."
385
386       The "release_status" field must have one of the following values:
387
388       stable
389           This indicates an ordinary, "final" release that should be indexed
390           by PAUSE or other indexers.
391
392       testing
393           This indicates a "beta" release that is substantially complete, but
394           has an elevated risk of bugs and requires additional testing.  The
395           distribution should not be installed over a stable release without
396           an explicit request or other confirmation from a user.  This
397           release status may also be used for "release candidate" versions of
398           a distribution.
399
400       unstable
401           This indicates an "alpha" release that is under active development,
402           but has been released for early feedback or testing and may be
403           missing features or may have serious bugs.  The distribution should
404           not be installed over a stable release without an explicit request
405           or other confirmation from a user.
406
407       Consumers may use this field to determine how to index the distribution
408       for CPAN or other repositories in addition to or in replacement of
409       heuristics based on version number or file name.
410
411       version
412
413       Example:
414
415         version => '0.36'
416
417       (Spec 1.0) [required] {Version}
418
419       This field gives the version of the distribution to which the metadata
420       structure refers.
421
422   OPTIONAL FIELDS
423       description
424
425       Example:
426
427           description =>  "Module::Build is a system for "
428             . "building, testing, and installing Perl modules. "
429             . "It is meant to ... blah blah blah ...",
430
431       (Spec 2) [optional] {String}
432
433       A longer, more complete description of the purpose or intended use of
434       the distribution than the one provided by the "abstract" key.
435
436       keywords
437
438       Example:
439
440         keywords => [ qw/ toolchain cpan dual-life / ]
441
442       (Spec 1.1) [optional] {List of zero or more Strings}
443
444       A List of keywords that describe this distribution.  Keywords must not
445       include whitespace.
446
447       no_index
448
449       Example:
450
451         no_index => {
452           file      => [ 'My/Module.pm' ],
453           directory => [ 'My/Private' ],
454           package   => [ 'My::Module::Secret' ],
455           namespace => [ 'My::Module::Sample' ],
456         }
457
458       (Spec 1.2) [optional] {Map}
459
460       This Map describes any files, directories, packages, and namespaces
461       that are private to the packaging or implementation of the distribution
462       and should be ignored by indexing or search tools. Note that this is a
463       list of exclusions, and the spec does not define what to include - see
464       "Indexing distributions a la PAUSE" in the implementors notes for more
465       information.
466
467       Valid subkeys are as follows:
468
469       file
470           A List of relative paths to files.  Paths must be specified with
471           unix conventions.
472
473       directory
474           A List of relative paths to directories.  Paths must be specified
475           with unix conventions.
476
477           [ Note: previous editions of the spec had "dir" instead of
478           "directory" ]
479
480       package
481           A List of package names.
482
483       namespace
484           A List of package namespaces, where anything below the namespace
485           must be ignored, but not the namespace itself.
486
487           In the example above for "no_index", "My::Module::Sample::Foo"
488           would be ignored, but "My::Module::Sample" would not.
489
490       optional_features
491
492       Example:
493
494         optional_features => {
495           sqlite => {
496             description => 'Provides SQLite support',
497             prereqs => {
498               runtime => {
499                 requires => {
500                   'DBD::SQLite' => '1.25'
501                 }
502               }
503             }
504           }
505         }
506
507       (Spec 2) [optional] {Map}
508
509       This Map describes optional features with incremental prerequisites.
510       Each key of the "optional_features" Map is a String used to identify
511       the feature and each value is a Map with additional information about
512       the feature.  Valid subkeys include:
513
514       description
515           This is a String describing the feature.  Every optional feature
516           should provide a description
517
518       prereqs
519           This entry is required and has the same structure as that of the
520           "prereqs" key.  It provides a list of package requirements that
521           must be satisfied for the feature to be supported or enabled.
522
523           There is one crucial restriction:  the prereqs of an optional
524           feature must not include "configure" phase prereqs.
525
526       Consumers must not include optional features as prerequisites without
527       explicit instruction from users (whether via interactive prompting, a
528       function parameter or a configuration value, etc. ).
529
530       If an optional feature is used by a consumer to add additional
531       prerequisites, the consumer should merge the optional feature
532       prerequisites into those given by the "prereqs" key using the same
533       semantics.  See "Merging and Resolving Prerequisites" for details on
534       merging prerequisites.
535
536       Suggestion for disuse: Because there is currently no way for a
537       distribution to specify a dependency on an optional feature of another
538       dependency, the use of "optional_feature" is discouraged.  Instead,
539       create a separate, installable distribution that ensures the desired
540       feature is available.  For example, if "Foo::Bar" has a "Baz" feature,
541       release a separate "Foo-Bar-Baz" distribution that satisfies
542       requirements for the feature.
543
544       prereqs
545
546       Example:
547
548         prereqs => {
549           runtime => {
550             requires => {
551               'perl'          => '5.006',
552               'File::Spec'    => '0.86',
553               'JSON'          => '2.16',
554             },
555             recommends => {
556               'JSON::XS'      => '2.26',
557             },
558             suggests => {
559               'Archive::Tar'  => '0',
560             },
561           },
562           build => {
563             requires => {
564               'Alien::SDL'    => '1.00',
565             },
566           },
567           test => {
568             recommends => {
569               'Test::Deep'    => '0.10',
570             },
571           }
572         }
573
574       (Spec 2) [optional] {Map}
575
576       This is a Map that describes all the prerequisites of the distribution.
577       The keys are phases of activity, such as "configure", "build", "test"
578       or "runtime".  Values are Maps in which the keys name the type of
579       prerequisite relationship such as "requires", "recommends", or
580       "suggests" and the value provides a set of prerequisite relations.  The
581       set of relations must be specified as a Map of package names to version
582       ranges.
583
584       The full definition for this field is given in the "Prereq Spec"
585       section.
586
587       provides
588
589       Example:
590
591         provides => {
592           'Foo::Bar' => {
593             file    => 'lib/Foo/Bar.pm',
594             version => '0.27_02',
595           },
596           'Foo::Bar::Blah' => {
597             file    => 'lib/Foo/Bar/Blah.pm',
598           },
599           'Foo::Bar::Baz' => {
600             file    => 'lib/Foo/Bar/Baz.pm',
601             version => '0.3',
602           },
603         }
604
605       (Spec 1.2) [optional] {Map}
606
607       This describes all packages provided by this distribution.  This
608       information is used by distribution and automation mechanisms like
609       PAUSE, CPAN, metacpan.org and search.cpan.org to build indexes saying
610       in which distribution various packages can be found.
611
612       The keys of "provides" are package names that can be found within the
613       distribution.  If a package name key is provided, it must have a Map
614       with the following valid subkeys:
615
616       file
617           This field is required.  It must contain a Unix-style relative file
618           path from the root of the distribution directory to a file that
619           contains or generates the package.  It may be given as "META.yml"
620           or "META.json" to claim a package for indexing without needing a
621           "*.pm".
622
623       version
624           If it exists, this field must contains a Version String for the
625           package.  If the package does not have a $VERSION, this field must
626           be omitted.
627
628       resources
629
630       Example:
631
632         resources => {
633           license     => [ 'http://dev.perl.org/licenses/' ],
634           homepage    => 'http://sourceforge.net/projects/module-build',
635           bugtracker  => {
636             web    => 'http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN-Meta',
637             mailto => 'meta-bugs@example.com',
638           },
639           repository  => {
640             url  => 'git://github.com/dagolden/cpan-meta.git',
641             web  => 'http://github.com/dagolden/cpan-meta',
642             type => 'git',
643           },
644           x_twitter   => 'http://twitter.com/cpan_linked/',
645         }
646
647       (Spec 2) [optional] {Map}
648
649       This field describes resources related to this distribution.
650
651       Valid subkeys include:
652
653       homepage
654           The official home of this project on the web.
655
656       license
657           A List of URL's that relate to this distribution's license.  As
658           with the top-level "license" field, distribution documentation
659           should be consulted to clarify the interpretation of multiple
660           licenses provided here.
661
662       bugtracker
663           This entry describes the bug tracking system for this distribution.
664           It is a Map with the following valid keys:
665
666             web    - a URL pointing to a web front-end for the bug tracker
667             mailto - an email address to which bugs can be sent
668
669       repository
670           This entry describes the source control repository for this
671           distribution.  It is a Map with the following valid keys:
672
673             url  - a URL pointing to the repository itself
674             web  - a URL pointing to a web front-end for the repository
675             type - a lowercase string indicating the VCS used
676
677           Because a url like "http://myrepo.example.com/" is ambiguous as to
678           type, producers should provide a "type" whenever a "url" key is
679           given.  The "type" field should be the name of the most common
680           program used to work with the repository, e.g. "git", "svn", "cvs",
681           "darcs", "bzr" or "hg".
682
683   DEPRECATED FIELDS
684       build_requires
685
686       (Deprecated in Spec 2) [optional] {String}
687
688       Replaced by "prereqs"
689
690       configure_requires
691
692       (Deprecated in Spec 2) [optional] {String}
693
694       Replaced by "prereqs"
695
696       conflicts
697
698       (Deprecated in Spec 2) [optional] {String}
699
700       Replaced by "prereqs"
701
702       distribution_type
703
704       (Deprecated in Spec 2) [optional] {String}
705
706       This field indicated 'module' or 'script' but was considered
707       meaningless, since many distributions are hybrids of several kinds of
708       things.
709
710       license_uri
711
712       (Deprecated in Spec 1.2) [optional] {URL}
713
714       Replaced by "license" in "resources"
715
716       private
717
718       (Deprecated in Spec 1.2) [optional] {Map}
719
720       This field has been renamed to "no_index".
721
722       recommends
723
724       (Deprecated in Spec 2) [optional] {String}
725
726       Replaced by "prereqs"
727
728       requires
729
730       (Deprecated in Spec 2) [optional] {String}
731
732       Replaced by "prereqs"
733

VERSION NUMBERS

735   Version Formats
736       This section defines the Version type, used by several fields in the
737       CPAN Meta Spec.
738
739       Version numbers must be treated as strings, not numbers.  For example,
740       1.200 must not be serialized as 1.2.  Version comparison should be
741       delegated to the Perl version module, version 0.80 or newer.
742
743       Unless otherwise specified, version numbers must appear in one of two
744       formats:
745
746       Decimal versions
747           Decimal versions are regular "decimal numbers", with some
748           limitations.  They must be non-negative and must begin and end with
749           a digit.  A single underscore may be included, but must be between
750           two digits.  They must not use exponential notation ("1.23e-2").
751
752              version => '1.234'       # OK
753              version => '1.23_04'     # OK
754
755              version => '1.23_04_05'  # Illegal
756              version => '1.'          # Illegal
757              version => '.1'          # Illegal
758
759       Dotted-integer versions
760           Dotted-integer (also known as dotted-decimal) versions consist of
761           positive integers separated by full stop characters (i.e. "dots",
762           "periods" or "decimal points").  This are equivalent in format to
763           Perl "v-strings", with some additional restrictions on form.  They
764           must be given in "normal" form, which has a leading "v" character
765           and at least three integer components.  To retain a one-to-one
766           mapping with decimal versions, all components after the first
767           should be restricted to the range 0 to 999.  The final component
768           may be separated by an underscore character instead of a period.
769
770              version => 'v1.2.3'      # OK
771              version => 'v1.2_3'      # OK
772              version => 'v1.2.3.4'    # OK
773              version => 'v1.2.3_4'    # OK
774              version => 'v2009.10.31' # OK
775
776              version => 'v1.2'          # Illegal
777              version => '1.2.3'         # Illegal
778              version => 'v1.2_3_4'      # Illegal
779              version => 'v1.2009.10.31' # Not recommended
780
781   Version Ranges
782       Some fields (prereq, optional_features) indicate the particular
783       version(s) of some other module that may be required as a prerequisite.
784       This section details the Version Range type used to provide this
785       information.
786
787       The simplest format for a Version Range is just the version number
788       itself, e.g. 2.4.  This means that at least version 2.4 must be
789       present.  To indicate that any version of a prerequisite is okay, even
790       if the prerequisite doesn't define a version at all, use the version 0.
791
792       Alternatively, a version range may use the operators < (less than), <=
793       (less than or equal), > (greater than), >= (greater than or equal), ==
794       (equal), and != (not equal).  For example, the specification "< 2.0"
795       means that any version of the prerequisite less than 2.0 is suitable.
796
797       For more complicated situations, version specifications may be AND-ed
798       together using commas.  The specification ">= 1.2, != 1.5, < 2.0"
799       indicates a version that must be at least 1.2, less than 2.0, and not
800       equal to 1.5.
801

PREREQUISITES

803   Prereq Spec
804       The "prereqs" key in the top-level metadata and within
805       "optional_features" define the relationship between a distribution and
806       other packages.  The prereq spec structure is a hierarchical data
807       structure which divides prerequisites into Phases of activity in the
808       installation process and Relationships that indicate how prerequisites
809       should be resolved.
810
811       For example, to specify that "Data::Dumper" is "required" during the
812       "test" phase, this entry would appear in the distribution metadata:
813
814         prereqs => {
815           test => {
816             requires => {
817               'Data::Dumper' => '2.00'
818             }
819           }
820         }
821
822       Phases
823
824       Requirements for regular use must be listed in the "runtime" phase.
825       Other requirements should be listed in the earliest stage in which they
826       are required and consumers must accumulate and satisfy requirements
827       across phases before executing the activity. For example, "build"
828       requirements must also be available during the "test" phase.
829
830         before action       requirements that must be met
831         ----------------    --------------------------------
832         perl Build.PL       configure
833         perl Makefile.PL
834
835         make                configure, runtime, build
836         Build
837
838         make test           configure, runtime, build, test
839         Build test
840
841       Consumers that install the distribution must ensure that runtime
842       requirements are also installed and may install dependencies from other
843       phases.
844
845         after action        requirements that must be met
846         ----------------    --------------------------------
847         make install        runtime
848         Build install
849
850       configure
851           The configure phase occurs before any dynamic configuration has
852           been attempted.  Libraries required by the configure phase must be
853           available for use before the distribution building tool has been
854           executed.
855
856       build
857           The build phase is when the distribution's source code is compiled
858           (if necessary) and otherwise made ready for installation.
859
860       test
861           The test phase is when the distribution's automated test suite is
862           run.  Any library that is needed only for testing and not for
863           subsequent use should be listed here.
864
865       runtime
866           The runtime phase refers not only to when the distribution's
867           contents are installed, but also to its continued use.  Any library
868           that is a prerequisite for regular use of this distribution should
869           be indicated here.
870
871       develop
872           The develop phase's prereqs are libraries needed to work on the
873           distribution's source code as its author does.  These tools might
874           be needed to build a release tarball, to run author-only tests, or
875           to perform other tasks related to developing new versions of the
876           distribution.
877
878       Relationships
879
880       requires
881           These dependencies must be installed for proper completion of the
882           phase.
883
884       recommends
885           Recommended dependencies are strongly encouraged and should be
886           satisfied except in resource constrained environments.
887
888       suggests
889           These dependencies are optional, but are suggested for enhanced
890           operation of the described distribution.
891
892       conflicts
893           These libraries cannot be installed when the phase is in operation.
894           This is a very rare situation, and the "conflicts" relationship
895           should be used with great caution, or not at all.
896
897   Merging and Resolving Prerequisites
898       Whenever metadata consumers merge prerequisites, either from different
899       phases or from "optional_features", they should merged in a way which
900       preserves the intended semantics of the prerequisite structure.
901       Generally, this means concatenating the version specifications using
902       commas, as described in the "Version Ranges" section.
903
904       Another subtle error that can occur in resolving prerequisites comes
905       from the way that modules in prerequisites are indexed to distribution
906       files on CPAN.  When a module is deleted from a distribution,
907       prerequisites calling for that module could indicate an older
908       distribution should be installed, potentially overwriting files from a
909       newer distribution.
910
911       For example, as of Oct 31, 2009, the CPAN index file contained these
912       module-distribution mappings:
913
914         Class::MOP                   0.94  D/DR/DROLSKY/Class-MOP-0.94.tar.gz
915         Class::MOP::Class            0.94  D/DR/DROLSKY/Class-MOP-0.94.tar.gz
916         Class::MOP::Class::Immutable 0.04  S/ST/STEVAN/Class-MOP-0.36.tar.gz
917
918       Consider the case where "Class::MOP" 0.94 is installed.  If a
919       distribution specified "Class::MOP::Class::Immutable" as a
920       prerequisite, it could result in Class-MOP-0.36.tar.gz being installed,
921       overwriting any files from Class-MOP-0.94.tar.gz.
922
923       Consumers of metadata should test whether prerequisites would result in
924       installed module files being "downgraded" to an older version and may
925       warn users or ignore the prerequisite that would cause such a result.
926

SERIALIZATION

928       Distribution metadata should be serialized (as a hashref) as JSON-
929       encoded data and packaged with distributions as the file META.json.
930
931       In the past, the distribution metadata structure had been packed with
932       distributions as META.yml, a file in the YAML Tiny format (for which,
933       see YAML::Tiny).  Tools that consume distribution metadata from disk
934       should be capable of loading META.yml, but should prefer META.json if
935       both are found.
936

NOTES FOR IMPLEMENTORS

938   Extracting Version Numbers from Perl Modules
939       To get the version number from a Perl module, consumers should use the
940       "MM->parse_version($file)" method provided by ExtUtils::MakeMaker or
941       Module::Metadata.  For example, for the module given by $mod, the
942       version may be retrieved in one of the following ways:
943
944         # via ExtUtils::MakeMaker
945         my $file = MM->_installed_file_for_module($mod);
946         my $version = MM->parse_version($file)
947
948       The private "_installed_file_for_module" method may be replaced with
949       other methods for locating a module in @INC.
950
951         # via Module::Metadata
952         my $info = Module::Metadata->new_from_module($mod);
953         my $version = $info->version;
954
955       If only a filename is available, the following approach may be used:
956
957         # via Module::Build
958         my $info = Module::Metadata->new_from_file($file);
959         my $version = $info->version;
960
961   Comparing Version Numbers
962       The version module provides the most reliable way to compare version
963       numbers in all the various ways they might be provided or might exist
964       within modules.  Given two strings containing version numbers, $v1 and
965       $v2, they should be converted to "version" objects before using
966       ordinary comparison operators.  For example:
967
968         use version;
969         if ( version->new($v1) <=> version->new($v2) ) {
970           print "Versions are not equal\n";
971         }
972
973       If the only comparison needed is whether an installed module is of a
974       sufficiently high version, a direct test may be done using the string
975       form of "eval" and the "use" function.  For example, for module $mod
976       and version prerequisite $prereq:
977
978         if ( eval "use $mod $prereq (); 1" ) {
979           print "Module $mod version is OK.\n";
980         }
981
982       If the values of $mod and $prereq have not been scrubbed, however, this
983       presents security implications.
984
985   Prerequisites for dynamically configured distributions
986       When "dynamic_config" is true, it is an error to presume that the
987       prerequisites given in distribution metadata will have any relationship
988       whatsoever to the actual prerequisites of the distribution.
989
990       In practice, however, one can generally expect such prerequisites to be
991       one of two things:
992
993       ·   The minimum prerequisites for the distribution, to which dynamic
994           configuration will only add items
995
996       ·   Whatever the distribution configured with on the releaser's machine
997           at release time
998
999       The second case often turns out to have identical results to the first
1000       case, albeit only by accident.
1001
1002       As such, consumers may use this data for informational analysis, but
1003       presenting it to the user as canonical or relying on it as such is
1004       invariably the height of folly.
1005
1006   Indexing distributions a la PAUSE
1007       While no_index tells you what must be ignored when indexing, this spec
1008       holds no opinion on how you should get your initial candidate list of
1009       things to possibly index. For "normal" distributions you might consider
1010       simply indexing the contents of lib/, but there are many fascinating
1011       oddities on CPAN and many dists from the days when it was normal to put
1012       the main .pm file in the root of the distribution archive - so PAUSE
1013       currently indexes all .pm and .PL files that are not either (a)
1014       specifically excluded by no_index (b) in "inc", "xt", or "t"
1015       directories, or common 'mistake' directories such as "perl5".
1016
1017       Or: If you're trying to be PAUSE-like, make sure you skip "inc", "xt"
1018       and "t" as well as anything marked as no_index.
1019
1020       Also remember: If the META file contains a provides field, you
1021       shouldn't be indexing anything in the first place - just use that.
1022

SEE ALSO

1024       ·   CPAN, <http://www.cpan.org/>
1025
1026       ·   JSON, <http://json.org/>
1027
1028       ·   YAML, <http://www.yaml.org/>
1029
1030       ·   CPAN
1031
1032       ·   CPANPLUS
1033
1034       ·   ExtUtils::MakeMaker
1035
1036       ·   Module::Build
1037
1038       ·   Module::Install
1039
1040       ·   CPAN::Meta::History::Meta_1_4
1041

HISTORY

1043       Ken Williams wrote the original CPAN Meta Spec (also known as the
1044       "META.yml spec") in 2003 and maintained it through several revisions
1045       with input from various members of the community.  In 2005, Randy Sims
1046       redrafted it from HTML to POD for the version 1.2 release.  Ken
1047       continued to maintain the spec through version 1.4.
1048
1049       In late 2009, David Golden organized the version 2 proposal review
1050       process.  David and Ricardo Signes drafted the final version 2 spec in
1051       April 2010 based on the version 1.4 spec and patches contributed during
1052       the proposal process.
1053

AUTHORS

1055       ·   David Golden <dagolden@cpan.org>
1056
1057       ·   Ricardo Signes <rjbs@cpan.org>
1058
1059       ·   Adam Kennedy <adamk@cpan.org>
1060
1062       This software is copyright (c) 2010 by David Golden, Ricardo Signes,
1063       Adam Kennedy and Contributors.
1064
1065       This is free software; you can redistribute it and/or modify it under
1066       the same terms as the Perl 5 programming language system itself.
1067
1068
1069
1070perl v5.26.3                      2016-08-18               CPAN::Meta::Spec(3)
Impressum