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.102400
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 author => [
20 'Ken Williams <kwilliams@cpan.org>',
21 'Module-Build List <module-build@perl.org>', # additional contact
22 ],
23 license => [ 'perl_5' ],
24 prereqs => {
25 runtime => {
26 requires => {
27 'perl' => '5.006',
28 'ExtUtils::Install' => '0',
29 'File::Basename' => '0',
30 'File::Compare' => '0',
31 'IO::File' => '0',
32 },
33 recommends => {
34 'Archive::Tar' => '1.00',
35 'ExtUtils::Install' => '0.3',
36 'ExtUtils::ParseXS' => '2.02',
37 },
38 },
39 build => {
40 requires => {
41 'Test::More' => '0',
42 },
43 }
44 },
45 resources => {
46 license => ['http://dev.perl.org/licenses/'],
47 },
48 optional_features => {
49 domination => {
50 description => 'Take over the world',
51 prereqs => {
52 develop => { requires => { 'Genius::Evil' => '1.234' } },
53 runtime => { requires => { 'Machine::Weather' => '2.0' } },
54 },
55 },
56 },
57 dynamic_config => 1,
58 keywords => [ qw/ toolchain cpan dual-life / ],
59 'meta-spec' => {
60 version => '2',
61 url => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
62 },
63 generated_by => 'Module::Build version 0.36',
64 };
65
67 This document describes version 2 of the CPAN distribution metadata
68 specification, also known as the "CPAN Meta Spec".
69 Revisions of this specification for typo corrections and prose
71 clarifications may be issued as CPAN::Meta::Spec 2.x. These revisions
72 will never change semantics or add or remove specified behavior.
73 Distribution metadata describe important properties of Perl
75 distributions. Distribution building tools like Module::Build,
76 Module::Install, ExtUtils::MakeMaker or Dist::Zilla should create a
77 metadata file in accordance with this specification and include it with
78 the distribution for use by automated tools that index, examine,
79 package or install Perl distributions.
80
82 distribution
83 This is the primary object described by the metadata. In the
84 context of this document it usually refers to a collection of
85 modules, scripts, and/or documents that are distributed together
86 for other developers to use. Examples of distributions are
87 "Class-Container", "libwww-perl", or "DBI".
88 module
90 This refers to a reusable library of code contained in a single
91 file. Modules usually contain one or more packages and are often
92 referred to by the name of a primary package that can be mapped to
93 the file name. For example, one might refer to "File::Spec" instead
94 of File/Spec.pm
95 package
97 This refers to a namespace declared with the Perl "package"
98 statement. In Perl, packages often have a version number property
99 given by the $VERSION variable in the namespace.
100 consumer
102 This refers to code that reads a metadata file, deserializes it
103 into a data structure in memory, or interprets a data structure of
104 metadata elements.
105 producer
107 This refers to code that constructs a metadata data structure,
108 serializes into a bytestream and/or writes it to disk.
109 must, should, may, etc.
111 These terms are interpreted as described in IETF RFC 2119.
112
114 Fields in the "STRUCTURE" section describe data elements, each of which
115 has an associated data type as described herein. There are four
116 primitive types: Boolean, String, List and Map. Other types are
117 subtypes of primitives and define compound data structures or define
118 constraints on the values of a data element.
119 Boolean
121 A Boolean is used to provide a true or false value. It must be
122 represented as a defined value.
123 String
125 A String is data element containing a non-zero length sequence of
126 Unicode characters, such as an ordinary Perl scalar that is not a
127 reference.
128 List
130 A List is an ordered collection of zero or more data elements.
131 Elements of a List may be of mixed types.
132 Producers must represent List elements using a data structure which
134 unambiguously indicates that multiple values are possible, such as a
135 reference to a Perl array (an "arrayref").
136 Consumers expecting a List must consider a String as equivalent to a
138 List of length 1.
139 Map
141 A Map is an unordered collection of zero or more data elements
142 ("values"), indexed by associated String elements ("keys"). The Map's
143 value elements may be of mixed types.
144 License String
146 A License String is a subtype of String with a restricted set of
147 values. Valid values are described in detail in the description of the
148 "license" field.
149 URL
151 URL is a subtype of String containing a Uniform Resource Locator or
152 Identifier. [ This type is called URL and not URI for historical
153 reasons. ]
154 Version
156 A Version is a subtype of String containing a value that describes the
157 version number of packages or distributions. Restrictions on format
158 are described in detail in the "Version Formats" section.
159 Version Range
161 The Version Range type is a subtype of String. It describes a range of
162 Versions that may be present or installed to fulfill prerequisites. It
163 is specified in detail in the "Version Ranges" section.
164
166 The metadata structure is a data element of type Map. This section
167 describes valid keys within the Map.
168 Any keys not described in this specification document (whether top-
170 level or within compound data structures described herein) are
171 considered custom keys and must begin with an "x" or "X" and be
172 followed by an underscore; i.e. they must match the pattern:
173 "qr{\Ax_}i". If a custom key refers to a compound data structure,
174 subkeys within it do not need an "x_" or "X_" prefix.
175 Consumers of metadata may ignore any or all custom keys. All other
177 keys not described herein are invalid and should be ignored by
178 consumers. Producers must not generate or output invalid keys.
179 For each key, an example is provided followed by a description. The
181 description begins with the version of spec in which the key was added
182 or in which the definition was modified, whether the key is required or
183 optional and the data type of the corresponding data element. These
184 items are in parentheses, brackets and braces, respectively.
185 If a data type is a Map or Map subtype, valid subkeys will be described
187 as well.
188 Some fields are marked Deprecated. These are shown for historical
190 context and must not be produced in or consumed from any metadata
191 structure of version 2 or higher.
192 REQUIRED FIELDS
194 abstract
195 Example:
197 abstract => 'Build and install Perl modules'
199 (Spec 1.2) [required] {String}
201 This is a short description of the purpose of the distribution.
203 author
205 Example:
207 author => [ 'Ken Williams <kwilliams@cpan.org>' ]
209 (Spec 1.2) [required] {List of one or more Strings}
211 This List indicates the person(s) to contact concerning the
213 distribution. The preferred form of the contact string is:
214 contact-name <email-address>
216 This field provides a general contact list independent of other
218 structured fields provided within the "resources" field, such as
219 "bugtracker". The addressee(s) can be contacted for any purpose
220 including but not limited to (security) problems with the distribution,
221 questions about the distribution or bugs in the distribution.
222 A distribution's original author is usually the contact listed within
224 this field. Co-maintainers, successor maintainers or mailing lists
225 devoted to the distribution may also be listed in addition to or
226 instead of the original author.
227 dynamic_config
229 Example:
231 dynamic_config => 1
233 (Spec 2) [required] {Boolean}
235 A boolean flag indicating whether a Build.PL or Makefile.PL (or
237 similar) must be executed to determine prerequisites.
238 This field should be set to a true value if the distribution performs
240 some dynamic configuration (asking questions, sensing the environment,
241 etc.) as part of its configuration. This field should be set to a
242 false value to indicate that prerequisites included in metadata may be
243 considered final and valid for static analysis.
244 This field explicitly does not indicate whether installation may be
246 safely performed without using a Makefile or Build file, as there may
247 be special files to install or custom installation targets (e.g. for
248 dual-life modules that exist on CPAN as well as in the Perl core).
249 This field only defines whether prerequisites are complete as given in
250 the metadata.
251 generated_by
253 Example:
255 generated_by => 'Module::Build version 0.36'
257 (Spec 1.0) [required] {String}
259 This field indicates the tool that was used to create this metadata.
261 There are no defined semantics for this field, but it is traditional to
262 use a string in the form "Generating::Package version 1.23" or the
263 author's name, if the file was generated by hand.
264 license
266 Example:
268 license => [ 'perl_5' ]
270 license => [ 'apache_2', 'mozilla_1_0' ]
272 (Spec 2) [required] {List of one or more License Strings}
274 One or more licenses that apply to some or all of the files in the
276 distribution. If multiple licenses are listed, the distribution
277 documentation should be consulted to clarify the interpretation of
278 multiple licenses.
279 The following list of license strings are valid:
281 string description
283 ------------- -----------------------------------------------
284 agpl_3 GNU Affero General Public License, Version 3
285 apache_1_1 Apache Software License, Version 1.1
286 apache_2_0 Apache License, Version 2.0
287 artistic_1 Artistic License, (Version 1)
288 artistic_2 Artistic License, Version 2.0
289 bsd BSD License (three-clause)
290 freebsd FreeBSD License (two-clause)
291 gfdl_1_2 GNU Free Documentation License, Version 1.2
292 gfdl_1_3 GNU Free Documentation License, Version 1.3
293 gpl_1 GNU General Public License, Version 1
294 gpl_2 GNU General Public License, Version 2
295 gpl_3 GNU General Public License, Version 3
296 lgpl_2_1 GNU Lesser General Public License, Version 2.1
297 lgpl_3_0 GNU Lesser General Public License, Version 3.0
298 mit MIT (aka X11) License
299 mozilla_1_0 Mozilla Public License, Version 1.0
300 mozilla_1_1 Mozilla Public License, Version 1.1
301 openssl OpenSSL License
302 perl_5 The Perl 5 License (Artistic 1 & GPL 1 or later)
303 qpl_1_0 Q Public License, Version 1.0
304 ssleay Original SSLeay License
305 sun Sun Internet Standards Source License (SISSL)
306 zlib zlib License
307 The following license strings are also valid and indicate other
309 licensing not described above:
310 string description
312 ------------- -----------------------------------------------
313 open_source Other Open Source Initiative (OSI) approved license
314 restricted Requires special permission from copyright holder
315 unrestricted Not an OSI approved license, but not restricted
316 unknown License not provided in metadata
317 All other strings are invalid in the license field.
319 meta-spec
321 Example:
323 'meta-spec' => {
325 version => '2',
326 url => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec',
327 }
328 (Spec 1.2) [required] {Map}
330 This field indicates the version of the CPAN Meta Spec that should be
332 used to interpret the metadata. Consumers must check this key as soon
333 as possible and abort further metadata processing if the meta-spec
334 version is not supported by the consumer.
335 The following keys are valid, but only "version" is required.
337 version
339 This subkey gives the integer Version of the CPAN Meta Spec against
340 which the document was generated.
341 url This is a URL of the metadata specification document corresponding
343 to the given version. This is strictly for human-consumption and
344 should not impact the interpretation of the document.
345 name
347 Example:
349 name => 'Module-Build'
351 (Spec 1.0) [required] {String}
353 This field is the name of the distribution. This is often created by
355 taking the "main package" in the distribution and changing "::" to "-",
356 but the name may be completely unrelated to the packages within the
357 distribution. C.f. http://search.cpan.org/dist/libwww-perl/
358 <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 convetions.
455 directory
457 A List of relative paths to directories. Paths must be specified
458 with unix convetions.
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 preqreqs of an optional
507 feature must not include "configure" phase prereqs.
508 Consumers must not include optional features as prerequisites without
510 explict 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 relative file
600 path from the root of the distribution to the module containing the
601 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://github.com/dagolden/cpan-meta-spec/issues',
616 mailto => 'meta-bugs@example.com',
617 },
618 repository => {
619 url => 'git://github.com/dagolden/cpan-meta-spec.git',
620 web => 'http://github.com/dagolden/cpan-meta-spec',
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 the Module::Build::ModuleInfo module provided with Module::Build. For
921 example, for the module given by $mod, the version may be retrieved in
922 one of the following ways:
923 # via ExtUtils::MakeMaker
925 my $file = MM->_installed_file_for_module($mod);
926 my $version = MM->parse_version($file)
927 The private "_installed_file_for_module" method may be replaced with
929 other methods for locating a module in @INC.
930 # via Module::Build
932 my $info = Module::Build::ModuleInfo->new_from_module($mod);
933 my $version = $info->version;
934 If only a filename is available, the following approach may be used:
936 # via Module::Build
938 my $info = Module::Build::ModuleInfo->new_from_file($file);
939 my $version = $info->version;
940 Comparing Version Numbers
942 The version module provides the most reliable way to compare version
943 numbers in all the various ways they might be provided or might exist
944 within modules. Given two strings containing version numbers, $v1 and
945 $v2, they should be converted to "version" objects before using
946 ordinary comparison operators. For example:
947 use version;
949 if ( version->new($v1) <=> version->new($v2) ) {
950 print "Versions are not equal\n";
951 }
952 If the only comparison needed is whether an installed module is of a
954 sufficiently high version, a direct test may be done using the string
955 form of "eval" and the "use" function. For example, for module $mod
956 and version prerequisite $prereq:
957 if ( eval "use $mod $prereq (); 1" ) {
959 print "Module $mod version is OK.\n";
960 }
961 If the values of $mod and $prereq have not been scrubbed, however, this
963 presents security implications.
964
966 CPAN, <http://www.cpan.org/>
967 CPAN.pm, <http://search.cpan.org/dist/CPAN/>
969 CPANPLUS, <http://search.cpan.org/dist/CPANPLUS/>
971 ExtUtils::MakeMaker, http://search.cpan.org/dist/ExtUtils-MakeMaker/
973 <http://search.cpan.org/dist/ExtUtils-MakeMaker/>
974 Module::Build, http://search.cpan.org/dist/Module-Build/
976 <http://search.cpan.org/dist/Module-Build/>
977 Module::Install, http://search.cpan.org/dist/Module-Install/
979 <http://search.cpan.org/dist/Module-Install/>
980 JSON, <http://json.org/>
982 YAML, <http://www.yaml.org/>
984
986 Ken Williams wrote the original CPAN Meta Spec (also known as the
987 "META.yml spec") in 2003 and maintained it through several revisions
988 with input from various members of the community. In 2005, Randy Sims
989 redrafted it from HTML to POD for the version 1.2 release. Ken
990 continued to maintain the spec through version 1.4.
991 In late 2009, David Golden organized the version 2 proposal review
993 process. David and Ricardo Signes drafted the final version 2 spec in
994 April 2010 based on the version 1.4 spec and patches contributed during
995 the proposal process.
996 Several others have contributed patches over the years. The full list
998 of contributors in the repository history currently includes:
999 2shortplanks
1001 Avar Arnfjord Bjarmason
1002 Christopher J. Madsen
1003 Damyan Ivanov
1004 David Golden
1005 Eric Wilhelm
1006 Ken Williams
1007 Lars DIECKOW
1008 Michael G. Schwern
1009 Randy Sims
1010 Ricardo Signes
1011
1013 · David Golden <dagolden@cpan.org>
1014 · Ricardo Signes <rjbs@cpan.org>
1016
1018 This software is copyright (c) 2010 by David Golden and Ricardo Signes.
1019 This is free software; you can redistribute it and/or modify it under
1021 the same terms as the Perl 5 programming language system itself.
1022perl v5.12.1 2010-08-28 CPAN::Meta::Spec(3)