This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update CPAN-Meta to CPAN version 2.131490
[perl5.git] / cpan / CPAN-Meta / lib / CPAN / Meta / Spec.pm
1 # vi:tw=72
2 use 5.006;
3 use strict;
4 use warnings;
5 package CPAN::Meta::Spec;
6 our $VERSION = '2.131490'; # VERSION
7
8 1;
9
10 # ABSTRACT: specification for CPAN distribution metadata
11
12 __END__
13
14 =pod
15
16 =encoding utf-8
17
18 =head1 NAME
19
20 CPAN::Meta::Spec - specification for CPAN distribution metadata
21
22 =head1 VERSION
23
24 version 2.131490
25
26 =head1 SYNOPSIS
27
28   my $distmeta = {
29     name => 'Module-Build',
30     abstract => 'Build and install Perl modules',
31     description =>  "Module::Build is a system for "
32       . "building, testing, and installing Perl modules. "
33       . "It is meant to ... blah blah blah ...",
34     version  => '0.36',
35     release_status => 'stable',
36     author   => [
37       'Ken Williams <kwilliams@cpan.org>',
38       'Module-Build List <module-build@perl.org>', # additional contact
39     ],
40     license  => [ 'perl_5' ],
41     prereqs => {
42       runtime => {
43         requires => {
44           'perl'   => '5.006',
45           'ExtUtils::Install' => '0',
46           'File::Basename' => '0',
47           'File::Compare'  => '0',
48           'IO::File'   => '0',
49         },
50         recommends => {
51           'Archive::Tar' => '1.00',
52           'ExtUtils::Install' => '0.3',
53           'ExtUtils::ParseXS' => '2.02',
54         },
55       },
56       build => {
57         requires => {
58           'Test::More' => '0',
59         },
60       }
61     },
62     resources => {
63       license => ['http://dev.perl.org/licenses/'],
64     },
65     optional_features => {
66       domination => {
67         description => 'Take over the world',
68         prereqs     => {
69           develop => { requires => { 'Genius::Evil'     => '1.234' } },
70           runtime => { requires => { 'Machine::Weather' => '2.0'   } },
71         },
72       },
73     },
74     dynamic_config => 1,
75     keywords => [ qw/ toolchain cpan dual-life / ],
76     'meta-spec' => {
77       version => '2',
78       url     => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
79     },
80     generated_by => 'Module::Build version 0.36',
81   };
82
83 =head1 DESCRIPTION
84
85 This document describes version 2 of the CPAN distribution metadata
86 specification, also known as the "CPAN Meta Spec".
87
88 Revisions of this specification for typo corrections and prose
89 clarifications may be issued as CPAN::Meta::Spec 2.I<x>.  These
90 revisions will never change semantics or add or remove specified
91 behavior.
92
93 Distribution metadata describe important properties of Perl
94 distributions. Distribution building tools like Module::Build,
95 Module::Install, ExtUtils::MakeMaker or Dist::Zilla should create a
96 metadata file in accordance with this specification and include it with
97 the distribution for use by automated tools that index, examine, package
98 or install Perl distributions.
99
100 =head1 TERMINOLOGY
101
102 =over 4
103
104 =item distribution
105
106 This is the primary object described by the metadata. In the context of
107 this document it usually refers to a collection of modules, scripts,
108 and/or documents that are distributed together for other developers to
109 use.  Examples of distributions are C<Class-Container>, C<libwww-perl>,
110 or C<DBI>.
111
112 =item module
113
114 This refers to a reusable library of code contained in a single file.
115 Modules usually contain one or more packages and are often referred
116 to by the name of a primary package that can be mapped to the file
117 name. For example, one might refer to C<File::Spec> instead of
118 F<File/Spec.pm>
119
120 =item package
121
122 This refers to a namespace declared with the Perl C<package> statement.
123 In Perl, packages often have a version number property given by the
124 C<$VERSION> variable in the namespace.
125
126 =item consumer
127
128 This refers to code that reads a metadata file, deserializes it into a
129 data structure in memory, or interprets a data structure of metadata
130 elements.
131
132 =item producer
133
134 This refers to code that constructs a metadata data structure,
135 serializes into a bytestream and/or writes it to disk.
136
137 =item must, should, may, etc.
138
139 These terms are interpreted as described in IETF RFC 2119.
140
141 =back
142
143 =head1 DATA TYPES
144
145 Fields in the L</STRUCTURE> section describe data elements, each of
146 which has an associated data type as described herein.  There are four
147 primitive types: Boolean, String, List and Map.  Other types are
148 subtypes of primitives and define compound data structures or define
149 constraints on the values of a data element.
150
151 =head2 Boolean
152
153 A I<Boolean> is used to provide a true or false value.  It B<must> be
154 represented as a defined value.
155
156 =head2 String
157
158 A I<String> is data element containing a non-zero length sequence of
159 Unicode characters, such as an ordinary Perl scalar that is not a
160 reference.
161
162 =head2 List
163
164 A I<List> is an ordered collection of zero or more data elements.
165 Elements of a List may be of mixed types.
166
167 Producers B<must> represent List elements using a data structure which
168 unambiguously indicates that multiple values are possible, such as a
169 reference to a Perl array (an "arrayref").
170
171 Consumers expecting a List B<must> consider a String as equivalent to a
172 List of length 1.
173
174 =head2 Map
175
176 A I<Map> is an unordered collection of zero or more data elements
177 ("values"), indexed by associated String elements ("keys").  The Map's
178 value elements may be of mixed types.
179
180 =head2 License String
181
182 A I<License String> is a subtype of String with a restricted set of
183 values.  Valid values are described in detail in the description of
184 the L</license> field.
185
186 =head2 URL
187
188 I<URL> is a subtype of String containing a Uniform Resource Locator or
189 Identifier.  [ This type is called URL and not URI for historical reasons. ]
190
191 =head2 Version
192
193 A I<Version> is a subtype of String containing a value that describes
194 the version number of packages or distributions.  Restrictions on format
195 are described in detail in the L</Version Formats> section.
196
197 =head2 Version Range
198
199 The I<Version Range> type is a subtype of String.  It describes a range
200 of Versions that may be present or installed to fulfill prerequisites.
201 It is specified in detail in the L</Version Ranges> section.
202
203 =head1 STRUCTURE
204
205 The metadata structure is a data element of type Map.  This section
206 describes valid keys within the Map.
207
208 Any keys not described in this specification document (whether top-level
209 or within compound data structures described herein) are considered
210 I<custom keys> and B<must> begin with an "x" or "X" and be followed by an
211 underscore; i.e. they must match the pattern: C<< qr{\Ax_}i >>.  If a
212 custom key refers to a compound data structure, subkeys within it do not
213 need an "x_" or "X_" prefix.
214
215 Consumers of metadata may ignore any or all custom keys.  All other keys
216 not described herein are invalid and should be ignored by consumers.
217 Producers must not generate or output invalid keys.
218
219 For each key, an example is provided followed by a description.  The
220 description begins with the version of spec in which the key was added
221 or in which the definition was modified, whether the key is I<required>
222 or I<optional> and the data type of the corresponding data element.
223 These items are in parentheses, brackets and braces, respectively.
224
225 If a data type is a Map or Map subtype, valid subkeys will be described
226 as well.
227
228 Some fields are marked I<Deprecated>.  These are shown for historical
229 context and must not be produced in or consumed from any metadata structure
230 of version 2 or higher.
231
232 =head2 REQUIRED FIELDS
233
234 =head3 abstract
235
236 Example:
237
238   abstract => 'Build and install Perl modules'
239
240 (Spec 1.2) [required] {String}
241
242 This is a short description of the purpose of the distribution.
243
244 =head3 author
245
246 Example:
247
248   author => [ 'Ken Williams <kwilliams@cpan.org>' ]
249
250 (Spec 1.2) [required] {List of one or more Strings}
251
252 This List indicates the person(s) to contact concerning the
253 distribution. The preferred form of the contact string is:
254
255   contact-name <email-address>
256
257 This field provides a general contact list independent of other
258 structured fields provided within the L</resources> field, such as
259 C<bugtracker>.  The addressee(s) can be contacted for any purpose
260 including but not limited to (security) problems with the distribution,
261 questions about the distribution or bugs in the distribution.
262
263 A distribution's original author is usually the contact listed within
264 this field.  Co-maintainers, successor maintainers or mailing lists
265 devoted to the distribution may also be listed in addition to or instead
266 of the original author.
267
268 =head3 dynamic_config
269
270 Example:
271
272   dynamic_config => 1
273
274 (Spec 2) [required] {Boolean}
275
276 A boolean flag indicating whether a F<Build.PL> or F<Makefile.PL> (or
277 similar) must be executed to determine prerequisites.
278
279 This field should be set to a true value if the distribution performs
280 some dynamic configuration (asking questions, sensing the environment,
281 etc.) as part of its configuration.  This field should be set to a false
282 value to indicate that prerequisites included in metadata may be
283 considered final and valid for static analysis.
284
285 This field explicitly B<does not> indicate whether installation may be
286 safely performed without using a Makefile or Build file, as there may be
287 special files to install or custom installation targets (e.g. for
288 dual-life modules that exist on CPAN as well as in the Perl core).  This
289 field only defines whether prerequisites are complete as given in the
290 metadata.
291
292 =head3 generated_by
293
294 Example:
295
296   generated_by => 'Module::Build version 0.36'
297
298 (Spec 1.0) [required] {String}
299
300 This field indicates the tool that was used to create this metadata.
301 There are no defined semantics for this field, but it is traditional to
302 use a string in the form "Generating::Package version 1.23" or the
303 author's name, if the file was generated by hand.
304
305 =head3 license
306
307 Example:
308
309   license => [ 'perl_5' ]
310
311   license => [ 'apache_2', 'mozilla_1_0' ]
312
313 (Spec 2) [required] {List of one or more License Strings}
314
315 One or more licenses that apply to some or all of the files in the
316 distribution.  If multiple licenses are listed, the distribution
317 documentation should be consulted to clarify the interpretation of
318 multiple licenses.
319
320 The following list of license strings are valid:
321
322  string          description
323  -------------   -----------------------------------------------
324  agpl_3          GNU Affero General Public License, Version 3
325  apache_1_1      Apache Software License, Version 1.1
326  apache_2_0      Apache License, Version 2.0
327  artistic_1      Artistic License, (Version 1)
328  artistic_2      Artistic License, Version 2.0
329  bsd             BSD License (three-clause)
330  freebsd         FreeBSD License (two-clause)
331  gfdl_1_2        GNU Free Documentation License, Version 1.2
332  gfdl_1_3        GNU Free Documentation License, Version 1.3
333  gpl_1           GNU General Public License, Version 1
334  gpl_2           GNU General Public License, Version 2
335  gpl_3           GNU General Public License, Version 3
336  lgpl_2_1        GNU Lesser General Public License, Version 2.1
337  lgpl_3_0        GNU Lesser General Public License, Version 3.0
338  mit             MIT (aka X11) License
339  mozilla_1_0     Mozilla Public License, Version 1.0
340  mozilla_1_1     Mozilla Public License, Version 1.1
341  openssl         OpenSSL License
342  perl_5          The Perl 5 License (Artistic 1 & GPL 1 or later)
343  qpl_1_0         Q Public License, Version 1.0
344  ssleay          Original SSLeay License
345  sun             Sun Internet Standards Source License (SISSL)
346  zlib            zlib License
347
348 The following license strings are also valid and indicate other
349 licensing not described above:
350
351  string          description
352  -------------   -----------------------------------------------
353  open_source     Other Open Source Initiative (OSI) approved license
354  restricted      Requires special permission from copyright holder
355  unrestricted    Not an OSI approved license, but not restricted
356  unknown         License not provided in metadata
357
358 All other strings are invalid in the license field.
359
360 =head3 meta-spec
361
362 Example:
363
364   'meta-spec' => {
365     version => '2',
366     url     => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
367   }
368
369 (Spec 1.2) [required] {Map}
370
371 This field indicates the version of the CPAN Meta Spec that should be
372 used to interpret the metadata.  Consumers must check this key as soon
373 as possible and abort further metadata processing if the meta-spec
374 version is not supported by the consumer.
375
376 The following keys are valid, but only C<version> is required.
377
378 =over
379
380 =item version
381
382 This subkey gives the integer I<Version> of the CPAN Meta Spec against
383 which the document was generated.
384
385 =item url
386
387 This is a I<URL> of the metadata specification document corresponding to
388 the given version.  This is strictly for human-consumption and should
389 not impact the interpretation of the document.
390
391 =back
392
393 =head3 name
394
395 Example:
396
397   name => 'Module-Build'
398
399 (Spec 1.0) [required] {String}
400
401 This field is the name of the distribution.  This is often created by
402 taking the "main package" in the distribution and changing C<::> to
403 C<->, but the name may be completely unrelated to the packages within
404 the distribution.  C.f. L<http://search.cpan.org/dist/libwww-perl/>.
405
406 =head3 release_status
407
408 Example:
409
410   release_status => 'stable'
411
412 (Spec 2) [required] {String}
413
414 This field provides the  release status of this distribution.  If the
415 C<version> field contains an underscore character, then
416 C<release_status> B<must not> be "stable."
417
418 The C<release_status> field B<must> have one of the following values:
419
420 =over
421
422 =item stable
423
424 This indicates an ordinary, "final" release that should be indexed by PAUSE
425 or other indexers.
426
427 =item testing
428
429 This indicates a "beta" release that is substantially complete, but has an
430 elevated risk of bugs and requires additional testing.  The distribution
431 should not be installed over a stable release without an explicit request
432 or other confirmation from a user.  This release status may also be used
433 for "release candidate" versions of a distribution.
434
435 =item unstable
436
437 This indicates an "alpha" release that is under active development, but has
438 been released for early feedback or testing and may be missing features or
439 may have serious bugs.  The distribution should not be installed over a
440 stable release without an explicit request or other confirmation from a
441 user.
442
443 =back
444
445 Consumers B<may> use this field to determine how to index the
446 distribution for CPAN or other repositories in addition to or in
447 replacement of heuristics based on version number or file name.
448
449 =head3 version
450
451 Example:
452
453   version => '0.36'
454
455 (Spec 1.0) [required] {Version}
456
457 This field gives the version of the distribution to which the metadata
458 structure refers.
459
460 =head2 OPTIONAL FIELDS
461
462 =head3 description
463
464 Example:
465
466     description =>  "Module::Build is a system for "
467       . "building, testing, and installing Perl modules. "
468       . "It is meant to ... blah blah blah ...",
469
470 (Spec 2) [optional] {String}
471
472 A longer, more complete description of the purpose or intended use of
473 the distribution than the one provided by the C<abstract> key.
474
475 =head3 keywords
476
477 Example:
478
479   keywords => [ qw/ toolchain cpan dual-life / ]
480
481 (Spec 1.1) [optional] {List of zero or more Strings}
482
483 A List of keywords that describe this distribution.  Keywords
484 B<must not> include whitespace.
485
486 =head3 no_index
487
488 Example:
489
490   no_index => {
491     file      => [ 'My/Module.pm' ],
492     directory => [ 'My/Private' ],
493     package   => [ 'My::Module::Secret' ],
494     namespace => [ 'My::Module::Sample' ],
495   }
496
497 (Spec 1.2) [optional] {Map}
498
499 This Map describes any files, directories, packages, and namespaces that
500 are private to the packaging or implementation of the distribution and
501 should be ignored by indexing or search tools.
502
503 Valid subkeys are as follows:
504
505 =over
506
507 =item file
508
509 A I<List> of relative paths to files.  Paths B<must be> specified with
510 unix conventions.
511
512 =item directory
513
514 A I<List> of relative paths to directories.  Paths B<must be> specified
515 with unix conventions.
516
517 [ Note: previous editions of the spec had C<dir> instead of C<directory> ]
518
519 =item package
520
521 A I<List> of package names.
522
523 =item namespace
524
525 A I<List> of package namespaces, where anything below the namespace
526 must be ignored, but I<not> the namespace itself.
527
528 In the example above for C<no_index>, C<My::Module::Sample::Foo> would
529 be ignored, but C<My::Module::Sample> would not.
530
531 =back
532
533 =head3 optional_features
534
535 Example:
536
537   optional_features => {
538     sqlite => {
539       description => 'Provides SQLite support',
540       prereqs => {
541         runtime => {
542           requires => {
543             'DBD::SQLite' => '1.25'
544           }
545         }
546       }
547     }
548   }
549
550 (Spec 2) [optional] {Map}
551
552 This Map describes optional features with incremental prerequisites.
553 Each key of the C<optional_features> Map is a String used to identify
554 the feature and each value is a Map with additional information about
555 the feature.  Valid subkeys include:
556
557 =over
558
559 =item description
560
561 This is a String describing the feature.  Every optional feature
562 should provide a description
563
564 =item prereqs
565
566 This entry is required and has the same structure as that of the
567 C<L</prereqs>> key.  It provides a list of package requirements
568 that must be satisfied for the feature to be supported or enabled.
569
570 There is one crucial restriction:  the prereqs of an optional feature
571 B<must not> include C<configure> phase prereqs.
572
573 =back
574
575 Consumers B<must not> include optional features as prerequisites without
576 explicit instruction from users (whether via interactive prompting,
577 a function parameter or a configuration value, etc. ).
578
579 If an optional feature is used by a consumer to add additional
580 prerequisites, the consumer should merge the optional feature
581 prerequisites into those given by the C<prereqs> key using the same
582 semantics.  See L</Merging and Resolving Prerequisites> for details on
583 merging prerequisites.
584
585 I<Suggestion for disuse:> Because there is currently no way for a
586 distribution to specify a dependency on an optional feature of another
587 dependency, the use of C<optional_feature> is discouraged.  Instead,
588 create a separate, installable distribution that ensures the desired
589 feature is available.  For example, if C<Foo::Bar> has a "Baz" feature,
590 release a separate C<Foo-Bar-Baz> distribution that satisfies
591 requirements for the feature.
592
593 =head3 prereqs
594
595 Example:
596
597   prereqs => {
598     runtime => {
599       requires => {
600         'perl'          => '5.006',
601         'File::Spec'    => '0.86',
602         'JSON'          => '2.16',
603       },
604       recommends => {
605         'JSON::XS'      => '2.26',
606       },
607       suggests => {
608         'Archive::Tar'  => '0',
609       },
610     },
611     build => {
612       requires => {
613         'Alien::SDL'    => '1.00',
614       },
615     },
616     test => {
617       recommends => {
618         'Test::Deep'    => '0.10',
619       },
620     }
621   }
622
623 (Spec 2) [optional] {Map}
624
625 This is a Map that describes all the prerequisites of the distribution.
626 The keys are phases of activity, such as C<configure>, C<build>, C<test>
627 or C<runtime>.  Values are Maps in which the keys name the type of
628 prerequisite relationship such as C<requires>, C<recommends>, or
629 C<suggests> and the value provides a set of prerequisite relations.  The
630 set of relations B<must> be specified as a Map of package names to
631 version ranges.
632
633 The full definition for this field is given in the L</Prereq Spec>
634 section.
635
636 =head3 provides
637
638 Example:
639
640   provides => {
641     'Foo::Bar' => {
642       file    => 'lib/Foo/Bar.pm',
643       version => 0.27_02
644     },
645     'Foo::Bar::Blah' => {
646       file    => 'lib/Foo/Bar/Blah.pm',
647     },
648     'Foo::Bar::Baz' => {
649       file    => 'lib/Foo/Bar/Baz.pm',
650       version => 0.3,
651     },
652   }
653
654 (Spec 1.2) [optional] {Map}
655
656 This describes all packages provided by this distribution.  This
657 information is used by distribution and automation mechanisms like
658 PAUSE, CPAN, and search.cpan.org to build indexes saying in which
659 distribution various packages can be found.
660
661 The keys of C<provides> are package names that can be found within
662 the distribution.  If a package name key is provided, it must
663 have a Map with the following valid subkeys:
664
665 =over
666
667 =item file
668
669 This field is required.  It must contain a Unix-style relative file path
670 from the root of the distribution directory to a file that contains or
671 generates the package.
672
673 =item version
674
675 If it exists, this field must contains a I<Version> String for the
676 package.  If the package does not have a C<$VERSION>, this field must
677 be omitted.
678
679 =back
680
681 =head3 resources
682
683 Example:
684
685   resources => {
686     license     => [ 'http://dev.perl.org/licenses/' ],
687     homepage    => 'http://sourceforge.net/projects/module-build',
688     bugtracker  => {
689       web    => 'http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN-Meta',
690       mailto => 'meta-bugs@example.com',
691     },
692     repository  => {
693       url  => 'git://github.com/dagolden/cpan-meta.git',
694       web  => 'http://github.com/dagolden/cpan-meta',
695       type => 'git',
696     },
697     x_twitter   => 'http://twitter.com/cpan_linked/',
698   }
699
700 (Spec 2) [optional] {Map}
701
702 This field describes resources related to this distribution.
703
704 Valid subkeys include:
705
706 =over
707
708 =item homepage
709
710 The official home of this project on the web.
711
712 =item license
713
714 A List of I<URL>'s that relate to this distribution's license.  As with the
715 top-level C<license> field, distribution documentation should be consulted
716 to clarify the interpretation of multiple licenses provided here.
717
718 =item bugtracker
719
720 This entry describes the bug tracking system for this distribution.  It
721 is a Map with the following valid keys:
722
723   web    - a URL pointing to a web front-end for the bug tracker
724   mailto - an email address to which bugs can be sent
725
726 =item repository
727
728 This entry describes the source control repository for this distribution.  It
729 is a Map with the following valid keys:
730
731   url  - a URL pointing to the repository itself
732   web  - a URL pointing to a web front-end for the repository
733   type - a lowercase string indicating the VCS used
734
735 Because a url like C<http://myrepo.example.com/> is ambiguous as to
736 type, producers should provide a C<type> whenever a C<url> key is given.
737 The C<type> field should be the name of the most common program used
738 to work with the repository, e.g. git, svn, cvs, darcs, bzr or hg.
739
740 =back
741
742 =head2 DEPRECATED FIELDS
743
744 =head3 build_requires
745
746 I<(Deprecated in Spec 2)> [optional] {String}
747
748 Replaced by C<prereqs>
749
750 =head3 configure_requires
751
752 I<(Deprecated in Spec 2)> [optional] {String}
753
754 Replaced by C<prereqs>
755
756 =head3 conflicts
757
758 I<(Deprecated in Spec 2)> [optional] {String}
759
760 Replaced by C<prereqs>
761
762 =head3 distribution_type
763
764 I<(Deprecated in Spec 2)> [optional] {String}
765
766 This field indicated 'module' or 'script' but was considered
767 meaningless, since many distributions are hybrids of several kinds of
768 things.
769
770 =head3 license_uri
771
772 I<(Deprecated in Spec 1.2)> [optional] {URL}
773
774 Replaced by C<license> in C<resources>
775
776 =head3 private
777
778 I<(Deprecated in Spec 1.2)> [optional] {Map}
779
780 This field has been renamed to L</"no_index">.
781
782 =head3 recommends
783
784 I<(Deprecated in Spec 2)> [optional] {String}
785
786 Replaced by C<prereqs>
787
788 =head3 requires
789
790 I<(Deprecated in Spec 2)> [optional] {String}
791
792 Replaced by C<prereqs>
793
794 =head1 VERSION NUMBERS
795
796 =head2 Version Formats
797
798 This section defines the Version type, used by several fields in the
799 CPAN Meta Spec.
800
801 Version numbers must be treated as strings, not numbers.  For
802 example, C<1.200> B<must not> be serialized as C<1.2>.  Version
803 comparison should be delegated to the Perl L<version> module, version
804 0.80 or newer.
805
806 Unless otherwise specified, version numbers B<must> appear in one of two
807 formats:
808
809 =over
810
811 =item Decimal versions
812
813 Decimal versions are regular "decimal numbers", with some limitations.
814 They B<must> be non-negative and B<must> begin and end with a digit.  A
815 single underscore B<may> be included, but B<must> be between two digits.
816 They B<must not> use exponential notation ("1.23e-2").
817
818    version => '1.234'       # OK
819    version => '1.23_04'     # OK
820
821    version => '1.23_04_05'  # Illegal
822    version => '1.'          # Illegal
823    version => '.1'          # Illegal
824
825 =item Dotted-integer versions
826
827 Dotted-integer (also known as dotted-decimal) versions consist of
828 positive integers separated by full stop characters (i.e. "dots",
829 "periods" or "decimal points").  This are equivalent in format to Perl
830 "v-strings", with some additional restrictions on form.  They must be
831 given in "normal" form, which has a leading "v" character and at least
832 three integer components.  To retain a one-to-one mapping with decimal
833 versions, all components after the first B<should> be restricted to the
834 range 0 to 999.  The final component B<may> be separated by an
835 underscore character instead of a period.
836
837    version => 'v1.2.3'      # OK
838    version => 'v1.2_3'      # OK
839    version => 'v1.2.3.4'    # OK
840    version => 'v1.2.3_4'    # OK
841    version => 'v2009.10.31' # OK
842
843    version => 'v1.2'          # Illegal
844    version => '1.2.3'         # Illegal
845    version => 'v1.2_3_4'      # Illegal
846    version => 'v1.2009.10.31' # Not recommended
847
848 =back
849
850 =head2 Version Ranges
851
852 Some fields (prereq, optional_features) indicate the particular
853 version(s) of some other module that may be required as a prerequisite.
854 This section details the Version Range type used to provide this
855 information.
856
857 The simplest format for a Version Range is just the version
858 number itself, e.g. C<2.4>.  This means that B<at least> version 2.4
859 must be present.  To indicate that B<any> version of a prerequisite is
860 okay, even if the prerequisite doesn't define a version at all, use
861 the version C<0>.
862
863 Alternatively, a version range B<may> use the operators E<lt> (less than),
864 E<lt>= (less than or equal), E<gt> (greater than), E<gt>= (greater than
865 or equal), == (equal), and != (not equal).  For example, the
866 specification C<E<lt> 2.0> means that any version of the prerequisite
867 less than 2.0 is suitable.
868
869 For more complicated situations, version specifications B<may> be AND-ed
870 together using commas.  The specification C<E<gt>= 1.2, != 1.5, E<lt>
871 2.0> indicates a version that must be B<at least> 1.2, B<less than> 2.0,
872 and B<not equal to> 1.5.
873
874 =head1 PREREQUISITES
875
876 =head2 Prereq Spec
877
878 The C<prereqs> key in the top-level metadata and within
879 C<optional_features> define the relationship between a distribution and
880 other packages.  The prereq spec structure is a hierarchical data
881 structure which divides prerequisites into I<Phases> of activity in the
882 installation process and I<Relationships> that indicate how
883 prerequisites should be resolved.
884
885 For example, to specify that C<Data::Dumper> is C<required> during the
886 C<test> phase, this entry would appear in the distribution metadata:
887
888   prereqs => {
889     test => {
890       requires => {
891         'Data::Dumper' => '2.00'
892       }
893     }
894   }
895
896 =head3 Phases
897
898 Requirements for regular use must be listed in the C<runtime> phase.
899 Other requirements should be listed in the earliest stage in which they
900 are required and consumers must accumulate and satisfy requirements
901 across phases before executing the activity. For example, C<build>
902 requirements must also be available during the C<test> phase.
903
904   before action       requirements that must be met
905   ----------------    --------------------------------
906   perl Build.PL       configure
907   perl Makefile.PL
908
909   make                configure, runtime, build
910   Build
911
912   make test           configure, runtime, build, test
913   Build test
914
915 Consumers that install the distribution must ensure that
916 I<runtime> requirements are also installed and may install
917 dependencies from other phases.
918
919   after action        requirements that must be met
920   ----------------    --------------------------------
921   make install        runtime
922   Build install
923
924 =over
925
926 =item configure
927
928 The configure phase occurs before any dynamic configuration has been
929 attempted.  Libraries required by the configure phase B<must> be
930 available for use before the distribution building tool has been
931 executed.
932
933 =item build
934
935 The build phase is when the distribution's source code is compiled (if
936 necessary) and otherwise made ready for installation.
937
938 =item test
939
940 The test phase is when the distribution's automated test suite is run.
941 Any library that is needed only for testing and not for subsequent use
942 should be listed here.
943
944 =item runtime
945
946 The runtime phase refers not only to when the distribution's contents
947 are installed, but also to its continued use.  Any library that is a
948 prerequisite for regular use of this distribution should be indicated
949 here.
950
951 =item develop
952
953 The develop phase's prereqs are libraries needed to work on the
954 distribution's source code as its author does.  These tools might be
955 needed to build a release tarball, to run author-only tests, or to
956 perform other tasks related to developing new versions of the
957 distribution.
958
959 =back
960
961 =head3 Relationships
962
963 =over
964
965 =item requires
966
967 These dependencies B<must> be installed for proper completion of the
968 phase.
969
970 =item recommends
971
972 Recommended dependencies are I<strongly> encouraged and should be
973 satisfied except in resource constrained environments.
974
975 =item suggests
976
977 These dependencies are optional, but are suggested for enhanced operation
978 of the described distribution.
979
980 =item conflicts
981
982 These libraries cannot be installed when the phase is in operation.
983 This is a very rare situation, and the C<conflicts> relationship should
984 be used with great caution, or not at all.
985
986 =back
987
988 =head2 Merging and Resolving Prerequisites
989
990 Whenever metadata consumers merge prerequisites, either from different
991 phases or from C<optional_features>, they should merged in a way which
992 preserves the intended semantics of the prerequisite structure.  Generally,
993 this means concatenating the version specifications using commas, as
994 described in the L<Version Ranges> section.
995
996 Another subtle error that can occur in resolving prerequisites comes from
997 the way that modules in prerequisites are indexed to distribution files on
998 CPAN.  When a module is deleted from a distribution, prerequisites calling
999 for that module could indicate an older distribution should installed,
1000 potentially overwriting files from a newer distribution.
1001
1002 For example, as of Oct 31, 2009, the CPAN index file contained these
1003 module-distribution mappings:
1004
1005   Class::MOP                   0.94  D/DR/DROLSKY/Class-MOP-0.94.tar.gz
1006   Class::MOP::Class            0.94  D/DR/DROLSKY/Class-MOP-0.94.tar.gz
1007   Class::MOP::Class::Immutable 0.04  S/ST/STEVAN/Class-MOP-0.36.tar.gz
1008
1009 Consider the case where "Class::MOP" 0.94 is installed.  If a
1010 distribution specified "Class::MOP::Class::Immutable" as a prerequisite,
1011 it could result in Class-MOP-0.36.tar.gz being installed, overwriting
1012 any files from Class-MOP-0.94.tar.gz.
1013
1014 Consumers of metadata B<should> test whether prerequisites would result
1015 in installed module files being "downgraded" to an older version and
1016 B<may> warn users or ignore the prerequisite that would cause such a
1017 result.
1018
1019 =head1 SERIALIZATION
1020
1021 Distribution metadata should be serialized (as a hashref) as
1022 JSON-encoded data and packaged with distributions as the file
1023 F<META.json>.
1024
1025 In the past, the distribution metadata structure had been packed with
1026 distributions as F<META.yml>, a file in the YAML Tiny format (for which,
1027 see L<YAML::Tiny>).  Tools that consume distribution metadata from disk
1028 should be capable of loading F<META.yml>, but should prefer F<META.json>
1029 if both are found.
1030
1031 =head1 NOTES FOR IMPLEMENTORS
1032
1033 =head2 Extracting Version Numbers from Perl Modules
1034
1035 To get the version number from a Perl module, consumers should use the
1036 C<< MM->parse_version($file) >> method provided by
1037 L<ExtUtils::MakeMaker> or L<Module::Metadata>.  For example, for the
1038 module given by C<$mod>, the version may be retrieved in one of the
1039 following ways:
1040
1041   # via ExtUtils::MakeMaker
1042   my $file = MM->_installed_file_for_module($mod);
1043   my $version = MM->parse_version($file)
1044
1045 The private C<_installed_file_for_module> method may be replaced with
1046 other methods for locating a module in C<@INC>.
1047
1048   # via Module::Metadata
1049   my $info = Module::Metadata->new_from_module($mod);
1050   my $version = $info->version;
1051
1052 If only a filename is available, the following approach may be used:
1053
1054   # via Module::Build
1055   my $info = Module::Metadata->new_from_file($file);
1056   my $version = $info->version;
1057
1058 =head2 Comparing Version Numbers
1059
1060 The L<version> module provides the most reliable way to compare version
1061 numbers in all the various ways they might be provided or might exist
1062 within modules.  Given two strings containing version numbers, C<$v1> and
1063 C<$v2>, they should be converted to C<version> objects before using
1064 ordinary comparison operators.  For example:
1065
1066   use version;
1067   if ( version->new($v1) <=> version->new($v2) ) {
1068     print "Versions are not equal\n";
1069   }
1070
1071 If the only comparison needed is whether an installed module is of a
1072 sufficiently high version, a direct test may be done using the string
1073 form of C<eval> and the C<use> function.  For example, for module C<$mod>
1074 and version prerequisite C<$prereq>:
1075
1076   if ( eval "use $mod $prereq (); 1" ) {
1077     print "Module $mod version is OK.\n";
1078   }
1079
1080 If the values of C<$mod> and C<$prereq> have not been scrubbed, however,
1081 this presents security implications.
1082
1083 =head1 SEE ALSO
1084
1085 CPAN, L<http://www.cpan.org/>
1086
1087 CPAN.pm, L<http://search.cpan.org/dist/CPAN/>
1088
1089 CPANPLUS, L<http://search.cpan.org/dist/CPANPLUS/>
1090
1091 ExtUtils::MakeMaker, L<http://search.cpan.org/dist/ExtUtils-MakeMaker/>
1092
1093 Module::Build, L<http://search.cpan.org/dist/Module-Build/>
1094
1095 Module::Install, L<http://search.cpan.org/dist/Module-Install/>
1096
1097 JSON, L<http://json.org/>
1098
1099 YAML, L<http://www.yaml.org/>
1100
1101 =head1 CONTRIBUTORS
1102
1103 Ken Williams wrote the original CPAN Meta Spec (also known as the
1104 "META.yml spec") in 2003 and maintained it through several revisions
1105 with input from various members of the community.  In 2005, Randy
1106 Sims redrafted it from HTML to POD for the version 1.2 release.  Ken
1107 continued to maintain the spec through version 1.4.
1108
1109 In late 2009, David Golden organized the version 2 proposal review
1110 process.  David and Ricardo Signes drafted the final version 2 spec
1111 in April 2010 based on the version 1.4 spec and patches contributed
1112 during the proposal process.
1113
1114 Several others have contributed patches over the years.  The full list
1115 of contributors in the repository history currently includes:
1116
1117   2shortplanks
1118   Avar Arnfjord Bjarmason
1119   Christopher J. Madsen
1120   Damyan Ivanov
1121   David Golden
1122   Eric Wilhelm
1123   Ken Williams
1124   Lars DIECKOW
1125   Michael G. Schwern
1126   Randy Sims
1127   Ricardo Signes
1128
1129 =head1 AUTHORS
1130
1131 =over 4
1132
1133 =item *
1134
1135 David Golden <dagolden@cpan.org>
1136
1137 =item *
1138
1139 Ricardo Signes <rjbs@cpan.org>
1140
1141 =back
1142
1143 =head1 CONTRIBUTORS
1144
1145 =over 4
1146
1147 =item *
1148
1149 Ansgar Burchardt <ansgar@cpan.org>
1150
1151 =item *
1152
1153 Avar Arnfjord Bjarmason <avar@cpan.org>
1154
1155 =item *
1156
1157 Christopher J. Madsen <cjm@cpan.org>
1158
1159 =item *
1160
1161 Cory G Watson <gphat@cpan.org>
1162
1163 =item *
1164
1165 Damyan Ivanov <dam@cpan.org>
1166
1167 =item *
1168
1169 Eric Wilhelm <ewilhelm@cpan.org>
1170
1171 =item *
1172
1173 Gregor Hermann <gregoa@debian.org>
1174
1175 =item *
1176
1177 Ken Williams <kwilliams@cpan.org>
1178
1179 =item *
1180
1181 Kenichi Ishigaki <ishigaki@cpan.org>
1182
1183 =item *
1184
1185 Lars Dieckow <daxim@cpan.org>
1186
1187 =item *
1188
1189 Leon Timmermans <leont@cpan.org>
1190
1191 =item *
1192
1193 Mark Fowler <markf@cpan.org>
1194
1195 =item *
1196
1197 Michael G. Schwern <mschwern@cpan.org>
1198
1199 =item *
1200
1201 Randy Sims <randys@thepierianspring.org>
1202
1203 =back
1204
1205 =head1 COPYRIGHT AND LICENSE
1206
1207 This software is copyright (c) 2010 by David Golden and Ricardo Signes.
1208
1209 This is free software; you can redistribute it and/or modify it under
1210 the same terms as the Perl 5 programming language system itself.
1211
1212 =cut