1CPAN::Meta::Spec(3) User Contributed Perl Documentation CPAN::Meta::Spec(3)
2
6 CPAN::Meta::Spec - specification for CPAN distribution metadata
7
9 version 2.120921
10
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
68 This document describes version 2 of the CPAN distribution metadata
69 specification, also known as the "CPAN Meta Spec".
70 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 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
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 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 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 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 producer
108 This refers to code that constructs a metadata data structure,
109 serializes into a bytestream and/or writes it to disk.
110 must, should, may, etc.
112 These terms are interpreted as described in IETF RFC 2119.
113
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 Boolean
122 A Boolean is used to provide a true or false value. It must be
123 represented as a defined value.
124 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 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 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 Consumers expecting a List must consider a String as equivalent to a
139 List of length 1.
140 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 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 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 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 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
167 The metadata structure is a data element of type Map. This section
168 describes valid keys within the Map.
169 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 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 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 If a data type is a Map or Map subtype, valid subkeys will be described
188 as well.
189 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 REQUIRED FIELDS
195 abstract
196 Example:
198 abstract => 'Build and install Perl modules'
200 (Spec 1.2) [required] {String}
202 This is a short description of the purpose of the distribution.
204 author
206 Example:
208 author => [ 'Ken Williams <kwilliams@cpan.org>' ]
210 (Spec 1.2) [required] {List of one or more Strings}
212 This List indicates the person(s) to contact concerning the
214 distribution. The preferred form of the contact string is:
215 contact-name <email-address>
217 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 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 dynamic_config
230 Example:
232 dynamic_config => 1
234 (Spec 2) [required] {Boolean}
236 A boolean flag indicating whether a Build.PL or Makefile.PL (or
238 similar) must be executed to determine prerequisites.
239 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 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 generated_by
254 Example:
256 generated_by => 'Module::Build version 0.36'
258 (Spec 1.0) [required] {String}
260 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 license
267 Example:
269 license => [ 'perl_5' ]
271 license => [ 'apache_2', 'mozilla_1_0' ]
273 (Spec 2) [required] {List of one or more License Strings}
275 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 The following list of license strings are valid:
282 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 The following license strings are also valid and indicate other
310 licensing not described above:
311 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 All other strings are invalid in the license field.
320 meta-spec
322 Example:
324 'meta-spec' => {
326 version => '2',
327 url => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
328 }
329 (Spec 1.2) [required] {Map}
331 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 The following keys are valid, but only "version" is required.
338 version
340 This subkey gives the integer Version of the CPAN Meta Spec against
341 which the document was generated.
342 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 name
348 Example:
350 name => 'Module-Build'
352 (Spec 1.0) [required] {String}
354 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 release_status
361 Example:
363 release_status => 'stable'
365 (Spec 2) [required] {String}
367 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 The "release_status" field must have one of the following values:
373 stable
375 This indicates an ordinary, "final" release that should be indexed
376 by PAUSE or other indexers.
377 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 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 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 version
398 Example:
400 version => '0.36'
402 (Spec 1.0) [required] {Version}
404 This field gives the version of the distribution to which the metadata
406 structure refers.
407 OPTIONAL FIELDS
409 description
410 Example:
412 description => "Module::Build is a system for "
414 . "building, testing, and installing Perl modules. "
415 . "It is meant to ... blah blah blah ...",
416 (Spec 2) [optional] {String}
418 A longer, more complete description of the purpose or intended use of
420 the distribution than the one provided by the "abstract" key.
421 keywords
423 Example:
425 keywords => [ qw/ toolchain cpan dual-life / ]
427 (Spec 1.1) [optional] {List of zero or more Strings}
429 A List of keywords that describe this distribution. Keywords must not
431 include whitespace.
432 no_index
434 Example:
436 no_index => {
438 file => [ 'My/Module.pm' ],
439 directory => [ 'My/Private' ],
440 package => [ 'My::Module::Secret' ],
441 namespace => [ 'My::Module::Sample' ],
442 }
443 (Spec 1.2) [optional] {Map}
445 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 Valid subkeys are as follows:
451 file
453 A List of relative paths to files. Paths must be specified with
454 unix conventions.
455 directory
457 A List of relative paths to directories. Paths must be specified
458 with unix conventions.
459 [ Note: previous editions of the spec had "dir" instead of
461 "directory" ]
462 package
464 A List of package names.
465 namespace
467 A List of package namespaces, where anything below the namespace
468 must be ignored, but not the namespace itself.
469 In the example above for "no_index", "My::Module::Sample::Foo"
471 would be ignored, but "My::Module::Sample" would not.
472 optional_features
474 Example:
476 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 (Spec 2) [optional] {Map}
491 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 description
498 This is a String describing the feature. Every optional feature
499 should provide a description
500 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 There is one crucial restriction: the prereqs of an optional
507 feature must not include "configure" phase prereqs.
508 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 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 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 prereqs
528 Example:
530 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 (Spec 2) [optional] {Map}
558 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 The full definition for this field is given in the "Prereq Spec"
568 section.
569 provides
571 Example:
573 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 (Spec 1.2) [optional] {Map}
589 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 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 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 version
604 This field contains a Version String for the package, if one
605 exists.
606 resources
608 Example:
610 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 (Spec 2) [optional] {Map}
627 This field describes resources related to this distribution.
629 Valid subkeys include:
631 homepage
633 The official home of this project on the web.
634 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 bugtracker
642 This entry describes the bug tracking system for this distribution.
643 It is a Map with the following valid keys:
644 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 repository
649 This entry describes the source control repository for this
650 distribution. It is a Map with the following valid keys:
651 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 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 DEPRECATED FIELDS
663 build_requires
664 (Deprecated in Spec 2) [optional] {String}
666 Replaced by "prereqs"
668 configure_requires
670 (Deprecated in Spec 2) [optional] {String}
672 Replaced by "prereqs"
674 conflicts
676 (Deprecated in Spec 2) [optional] {String}
678 Replaced by "prereqs"
680 distribution_type
682 (Deprecated in Spec 2) [optional] {String}
684 This field indicated 'module' or 'script' but was considered
686 meaningless, since many distributions are hybrids of several kinds of
687 things.
688 license_uri
690 (Deprecated in Spec 1.2) [optional] {URL}
692 Replaced by "license" in "resources"
694 private
696 (Deprecated in Spec 1.2) [optional] {Map}
698 This field has been renamed to "no_index".
700 recommends
702 (Deprecated in Spec 2) [optional] {String}
704 Replaced by "prereqs"
706 requires
708 (Deprecated in Spec 2) [optional] {String}
710 Replaced by "prereqs"
712
714 Version Formats
715 This section defines the Version type, used by several fields in the
716 CPAN Meta Spec.
717 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 Unless otherwise specified, version numbers must appear in one of two
723 formats:
724 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 version => '1.234' # OK
732 version => '1.23_04' # OK
733 version => '1.23_04_05' # Illegal
735 version => '1.' # Illegal
736 version => '.1' # Illegal
737 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 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 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 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 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 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 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
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 For example, to specify that "Data::Dumper" is "required" during the
791 "test" phase, this entry would appear in the distribution metadata:
792 prereqs => {
794 test => {
795 requires => {
796 'Data::Dumper' => '2.00'
797 }
798 }
799 }
800 Phases
802 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 before action requirements that must be met
810 ---------------- --------------------------------
811 perl Build.PL configure
812 perl Makefile.PL
813 make configure, runtime, build
815 Build
816 make test configure, runtime, build, test
818 Build test
819 Consumers that install the distribution must ensure that runtime
821 requirements are also installed and may install dependencies from other
822 phases.
823 after action requirements that must be met
825 ---------------- --------------------------------
826 make install runtime
827 Build install
828 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 build
836 The build phase is when the distribution's source code is compiled
837 (if necessary) and otherwise made ready for installation.
838 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 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 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 Relationships
858 requires
860 These dependencies must be installed for proper completion of the
861 phase.
862 recommends
864 Recommended dependencies are strongly encouraged and should be
865 satisfied except in resource constrained environments.
866 suggests
868 These dependencies are optional, but are suggested for enhanced
869 operation of the described distribution.
870 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 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 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 For example, as of Oct 31, 2009, the CPAN index file contained these
891 module-distribution mappings:
892 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 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 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
907 Distribution metadata should be serialized (as a hashref) as JSON-
908 encoded data and packaged with distributions as the file META.json.
909 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
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 # via ExtUtils::MakeMaker
924 my $file = MM->_installed_file_for_module($mod);
925 my $version = MM->parse_version($file)
926 The private "_installed_file_for_module" method may be replaced with
928 other methods for locating a module in @INC.
929 # via Module::Metadata
931 my $info = Module::Metadata->new_from_module($mod);
932 my $version = $info->version;
933 If only a filename is available, the following approach may be used:
935 # via Module::Build
937 my $info = Module::Metadata->new_from_file($file);
938 my $version = $info->version;
939 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 use version;
948 if ( version->new($v1) <=> version->new($v2) ) {
949 print "Versions are not equal\n";
950 }
951 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 if ( eval "use $mod $prereq (); 1" ) {
958 print "Module $mod version is OK.\n";
959 }
960 If the values of $mod and $prereq have not been scrubbed, however, this
962 presents security implications.
963
965 CPAN, <http://www.cpan.org/>
966 CPAN.pm, <http://search.cpan.org/dist/CPAN/>
968 CPANPLUS, <http://search.cpan.org/dist/CPANPLUS/>
970 ExtUtils::MakeMaker, <http://search.cpan.org/dist/ExtUtils-MakeMaker/>
972 Module::Build, <http://search.cpan.org/dist/Module-Build/>
974 Module::Install, <http://search.cpan.org/dist/Module-Install/>
976 JSON, <http://json.org/>
978 YAML, <http://www.yaml.org/>
980
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 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 Several others have contributed patches over the years. The full list
994 of contributors in the repository history currently includes:
995 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
1009 · David Golden <dagolden@cpan.org>
1010 · Ricardo Signes <rjbs@cpan.org>
1012
1014 This software is copyright (c) 2010 by David Golden and Ricardo Signes.
1015 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.
1018perl v5.16.3 2012-04-01 CPAN::Meta::Spec(3)