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