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