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.120921
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     => 'http://search.cpan.org/perldoc?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.
124
125   String
126       A String is data element containing a non-zero length sequence of
127       Unicode characters, such as an ordinary Perl scalar that is not a
128       reference.
129
130   List
131       A List is an ordered collection of zero or more data elements.
132       Elements of a List may be of mixed types.
133
134       Producers must represent List elements using a data structure which
135       unambiguously indicates that multiple values are possible, such as a
136       reference to a Perl array (an "arrayref").
137
138       Consumers expecting a List must consider a String as equivalent to a
139       List of length 1.
140
141   Map
142       A Map is an unordered collection of zero or more data elements
143       ("values"), indexed by associated String elements ("keys").  The Map's
144       value elements may be of mixed types.
145
146   License String
147       A License String is a subtype of String with a restricted set of
148       values.  Valid values are described in detail in the description of the
149       "license" field.
150
151   URL
152       URL is a subtype of String containing a Uniform Resource Locator or
153       Identifier.  [ This type is called URL and not URI for historical
154       reasons. ]
155
156   Version
157       A Version is a subtype of String containing a value that describes the
158       version number of packages or distributions.  Restrictions on format
159       are described in detail in the "Version Formats" section.
160
161   Version Range
162       The Version Range type is a subtype of String.  It describes a range of
163       Versions that may be present or installed to fulfill prerequisites.  It
164       is specified in detail in the "Version Ranges" section.
165

STRUCTURE

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

VERSION NUMBERS

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

PREREQUISITES

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

SERIALIZATION

907       Distribution metadata should be serialized (as a hashref) as JSON-
908       encoded data and packaged with distributions as the file META.json.
909
910       In the past, the distribution metadata structure had been packed with
911       distributions as META.yml, a file in the YAML Tiny format (for which,
912       see YAML::Tiny).  Tools that consume distribution metadata from disk
913       should be capable of loading META.yml, but should prefer META.json if
914       both are found.
915

NOTES FOR IMPLEMENTORS

917   Extracting Version Numbers from Perl Modules
918       To get the version number from a Perl module, consumers should use the
919       "MM->parse_version($file)" method provided by ExtUtils::MakeMaker or
920       Module::Metadata.  For example, for the module given by $mod, the
921       version may be retrieved in one of the following ways:
922
923         # via ExtUtils::MakeMaker
924         my $file = MM->_installed_file_for_module($mod);
925         my $version = MM->parse_version($file)
926
927       The private "_installed_file_for_module" method may be replaced with
928       other methods for locating a module in @INC.
929
930         # via Module::Metadata
931         my $info = Module::Metadata->new_from_module($mod);
932         my $version = $info->version;
933
934       If only a filename is available, the following approach may be used:
935
936         # via Module::Build
937         my $info = Module::Metadata->new_from_file($file);
938         my $version = $info->version;
939
940   Comparing Version Numbers
941       The version module provides the most reliable way to compare version
942       numbers in all the various ways they might be provided or might exist
943       within modules.  Given two strings containing version numbers, $v1 and
944       $v2, they should be converted to "version" objects before using
945       ordinary comparison operators.  For example:
946
947         use version;
948         if ( version->new($v1) <=> version->new($v2) ) {
949           print "Versions are not equal\n";
950         }
951
952       If the only comparison needed is whether an installed module is of a
953       sufficiently high version, a direct test may be done using the string
954       form of "eval" and the "use" function.  For example, for module $mod
955       and version prerequisite $prereq:
956
957         if ( eval "use $mod $prereq (); 1" ) {
958           print "Module $mod version is OK.\n";
959         }
960
961       If the values of $mod and $prereq have not been scrubbed, however, this
962       presents security implications.
963

SEE ALSO

965       CPAN, <http://www.cpan.org/>
966
967       CPAN.pm, <http://search.cpan.org/dist/CPAN/>
968
969       CPANPLUS, <http://search.cpan.org/dist/CPANPLUS/>
970
971       ExtUtils::MakeMaker, <http://search.cpan.org/dist/ExtUtils-MakeMaker/>
972
973       Module::Build, <http://search.cpan.org/dist/Module-Build/>
974
975       Module::Install, <http://search.cpan.org/dist/Module-Install/>
976
977       JSON, <http://json.org/>
978
979       YAML, <http://www.yaml.org/>
980

CONTRIBUTORS

982       Ken Williams wrote the original CPAN Meta Spec (also known as the
983       "META.yml spec") in 2003 and maintained it through several revisions
984       with input from various members of the community.  In 2005, Randy Sims
985       redrafted it from HTML to POD for the version 1.2 release.  Ken
986       continued to maintain the spec through version 1.4.
987
988       In late 2009, David Golden organized the version 2 proposal review
989       process.  David and Ricardo Signes drafted the final version 2 spec in
990       April 2010 based on the version 1.4 spec and patches contributed during
991       the proposal process.
992
993       Several others have contributed patches over the years.  The full list
994       of contributors in the repository history currently includes:
995
996         2shortplanks
997         Avar Arnfjord Bjarmason
998         Christopher J. Madsen
999         Damyan Ivanov
1000         David Golden
1001         Eric Wilhelm
1002         Ken Williams
1003         Lars DIECKOW
1004         Michael G. Schwern
1005         Randy Sims
1006         Ricardo Signes
1007

AUTHORS

1009       ·   David Golden <dagolden@cpan.org>
1010
1011       ·   Ricardo Signes <rjbs@cpan.org>
1012
1014       This software is copyright (c) 2010 by David Golden and Ricardo Signes.
1015
1016       This is free software; you can redistribute it and/or modify it under
1017       the same terms as the Perl 5 programming language system itself.
1018
1019
1020
1021perl v5.16.3                      2012-04-01               CPAN::Meta::Spec(3)
Impressum