1=for :stopwords MailingList PODs RWS subcontext 2 3=head1 NAME 4 5CPAN::Meta::History::Meta_1_4 - Version 1.4 metadata specification for META.yml 6 7=head1 PREFACE 8 9This is a historical copy of the version 1.4 specification for F<META.yml> 10files, copyright by Ken Williams and licensed under the same terms as Perl 11itself. 12 13Modifications from the original: 14 15=over 16 17=item * 18 19Various spelling corrections 20 21=item * 22 23Include list of valid licenses from L<Module::Build> 0.2807 rather than 24linking to the module, with minor updates to text and links to reflect 25versions at the time of publication. 26 27=item * 28 29Fixed some dead links to point to active resources. 30 31=back 32 33=head1 SYNOPSIS 34 35 --- #YAML:1.0 36 name: Module-Build 37 abstract: Build and install Perl modules 38 version: 0.20 39 author: 40 - Ken Williams <kwilliams@cpan.org> 41 license: perl 42 distribution_type: module 43 requires: 44 Config: 0 45 Cwd: 0 46 Data::Dumper: 0 47 ExtUtils::Install: 0 48 File::Basename: 0 49 File::Compare: 0 50 File::Copy: 0 51 File::Find: 0 52 File::Path: 0 53 File::Spec: 0 54 IO::File: 0 55 perl: 5.005_03 56 recommends: 57 Archive::Tar: 1.00 58 ExtUtils::Install: 0.3 59 ExtUtils::ParseXS: 2.02 60 Pod::Text: 0 61 YAML: 0.35 62 build_requires: 63 Test: 0 64 resources: 65 license: http://dev.perl.org/licenses/ 66 meta-spec: 67 version: 1.4 68 url: http://module-build.sourceforge.net/META-spec-v1.3.html 69 generated_by: Module::Build version 0.20 70 71=head1 DESCRIPTION 72 73This document describes version 1.4 of the F<META.yml> specification. 74 75The F<META.yml> file describes important properties of contributed 76Perl distributions such as the ones found on CPAN. It is typically 77created by tools like Module::Build, Module::Install, and 78ExtUtils::MakeMaker. 79 80The fields in the F<META.yml> file are meant to be helpful for people 81maintaining module collections (like CPAN), for people writing 82installation tools (like CPAN.pm or CPANPLUS), or just for people who 83want to know some stuff about a distribution before downloading it and 84starting to install it. 85 86I<Note: The latest stable version of this specification can always be 87found at L<http://module-build.sourceforge.net/META-spec-current.html>, 88and the latest development version (which may include things that 89won't make it into the stable version) can always be found at 90L<http://module-build.sourceforge.net/META-spec-blead.html>.> 91 92=head1 FORMAT 93 94F<META.yml> files are written in the YAML format (see 95L<http://www.yaml.org/>). 96 97See the following links to learn why we chose YAML instead of, say, 98XML or Data::Dumper: 99 100=over 4 101 102=item * 103 104L<Module::Build design plans|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html> 105 106=item * 107 108L<Not keen on YAML|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1353.html> 109 110=item * 111 112L<META Concerns|http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1385.html> 113 114=back 115 116=head1 TERMINOLOGY 117 118=over 4 119 120=item distribution 121 122This is the primary object described by the F<META.yml> 123specification. In the context of this document it usually refers to a 124collection of modules, scripts, and/or documents that are distributed 125together for other developers to use. Examples of distributions are 126C<Class-Container>, C<libwww-perl>, or C<DBI>. 127 128=item module 129 130This refers to a reusable library of code typically contained in a 131single file. Currently, we primarily talk of perl modules, but this 132specification should be open enough to apply to other languages as 133well (ex. python, ruby). Examples of modules are C<Class::Container>, 134C<LWP::Simple>, or C<DBD::File>. 135 136=back 137 138=head1 HEADER 139 140The first line of a F<META.yml> file should be a valid YAML document 141header like C<"--- #YAML:1.0">. 142 143=head1 FIELDS 144 145The rest of the F<META.yml> file is one big YAML mapping whose keys 146are described here. 147 148=head2 meta-spec 149 150Example: 151 152 meta-spec: 153 version: 1.4 154 url: http://module-build.sourceforge.net/META-spec-v1.3.html 155 156(Spec 1.1) [required] {URL} This field indicates the location of the 157version of the META.yml specification used. 158 159=head2 name 160 161Example: 162 163 name: Module-Build 164 165(Spec 1.0) [required] {string} The name of the distribution which is often 166created by taking the "main module" in the distribution and changing 167"::" to "-". Sometimes it's completely different, however, as in the 168case of the libwww-perl distribution (see 169L<http://search.cpan.org/dist/libwww-perl/>). 170 171=head2 version 172 173Example: 174 175 version: 0.20 176 177(Spec 1.0) [required] {version} The version of the distribution to which the 178F<META.yml> file refers. 179 180=head2 abstract 181 182Example: 183 184 abstract: Build and install Perl modules. 185 186(Spec 1.1) [required] {string} A short description of the purpose of the 187distribution. 188 189=head2 author 190 191Example: 192 193 author: 194 - Ken Williams <kwilliams@cpan.org> 195 196(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the 197distribution. The preferred form is author-name <email-address>. 198 199=head2 license 200 201Example: 202 203 license: perl 204 205(Spec 1.0) [required] {string} The license under which this 206distribution may be used and redistributed. 207 208Must be one of the following licenses: 209 210=over 4 211 212=item apache 213 214The distribution is licensed under the Apache Software License version 1.1 215(L<http://opensource.org/licenses/Apache-1.1>). 216 217=item artistic 218 219The distribution is licensed under the Artistic License version 1, as specified 220by the Artistic file in the standard perl distribution 221(L<http://opensource.org/licenses/Artistic-Perl-1.0>). 222 223=item bsd 224 225The distribution is licensed under the BSD 3-Clause License 226(L<http://opensource.org/licenses/BSD-3-Clause>). 227 228=item gpl 229 230The distribution is distributed under the terms of the GNU General Public 231License version 2 (L<http://opensource.org/licenses/GPL-2.0>). 232 233=item lgpl 234 235The distribution is distributed under the terms of the GNU Lesser General 236Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>). 237 238=item mit 239 240The distribution is licensed under the MIT License 241(L<http://opensource.org/licenses/MIT>). 242 243=item mozilla 244 245The distribution is licensed under the Mozilla Public License. 246(L<http://opensource.org/licenses/MPL-1.0> or 247L<http://opensource.org/licenses/MPL-1.1>) 248 249=item open_source 250 251The distribution is licensed under some other Open Source Initiative-approved 252license listed at L<http://www.opensource.org/licenses/>. 253 254=item perl 255 256The distribution may be copied and redistributed under the same terms as perl 257itself (this is by far the most common licensing option for modules on CPAN). 258This is a dual license, in which the user may choose between either the GPL or 259the Artistic license. 260 261=item restrictive 262 263The distribution may not be redistributed without special permission from the 264author and/or copyright holder. 265 266=item unrestricted 267 268The distribution is licensed under a license that is not approved by 269L<www.opensource.org|http://www.opensource.org/> but that allows distribution 270without restrictions. 271 272=back 273 274=head2 distribution_type 275 276Example: 277 278 distribution_type: module 279 280(Spec 1.0) [optional] {string} What kind of stuff is contained in this 281distribution. Most things on CPAN are C<module>s (which can also mean 282a collection of modules), but some things are C<script>s. 283 284Unfortunately this field is basically meaningless, since many 285distributions are hybrids of several kinds of things, or some new 286thing, or subjectively different in focus depending on who's using 287them. Tools like Module::Build and MakeMaker will likely stop 288generating this field. 289 290=head2 requires 291 292Example: 293 294 requires: 295 Data::Dumper: 0 296 File::Find: 1.03 297 298(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl 299prerequisites this distribution requires for proper operation. The 300keys are the names of the prerequisites (module names or 'perl'), and 301the values are version specifications as described in L<VERSION 302SPECIFICATIONS>. 303 304=head2 recommends 305 306Example: 307 308 recommends: 309 Data::Dumper: 0 310 File::Find: 1.03 311 312(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl 313prerequisites this distribution recommends for enhanced operation. 314The keys are the names of the prerequisites (module names or 'perl'), 315and the values are version specifications as described in L<VERSION 316SPECIFICATIONS>. 317 318 319 320I<ALTERNATIVE: It may be desirable to present to the user which 321features depend on which modules so they can make an informed decision 322about which recommended modules to install.> 323 324Example: 325 326 optional_features: 327 foo: 328 description: Provides the ability to blah. 329 requires: 330 Data::Dumper: 0 331 File::Find: 1.03 332 333I<(Spec 1.1) [optional] {map} A YAML mapping of names for optional features 334which are made available when its requirements are met. For each 335feature a description is provided along with any of L</requires>, 336L</build_requires>, and L</conflicts>, which have the same meaning in 337this subcontext as described elsewhere in this document.> 338 339=head2 build_requires 340 341Example: 342 343 build_requires: 344 Data::Dumper: 0 345 File::Find: 1.03 346 347(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl 348prerequisites required for building and/or testing of this 349distribution. The keys are the names of the prerequisites (module 350names or 'perl'), and the values are version specifications as 351described in L</"VERSION SPECIFICATIONS">. These dependencies are not 352required after the distribution is installed. 353 354=head2 configure_requires 355 356Example: 357 358 configure_requires: 359 Module::Build: 0.2809 360 Data::Dumper: 0 361 File::Find: 1.03 362 363(Spec 1.4) [optional] {map} A YAML mapping indicating the Perl prerequisites 364required before configuring this distribution. The keys are the 365names of the prerequisites (module names or 'perl'), and the values are version 366specifications as described in L</"VERSION SPECIFICATIONS">. These 367dependencies are not required after the distribution is installed. 368 369=head2 conflicts 370 371Example: 372 373 conflicts: 374 Data::Dumper: 0 375 File::Find: 1.03 376 377(Spec 1.0) [optional] {map} A YAML mapping indicating any items that 378cannot be installed while this distribution is installed. This is a 379pretty uncommon situation. The keys for C<conflicts> are the item 380names (module names or 'perl'), and the values are version 381specifications as described in L</"VERSION SPECIFICATIONS">. 382 383 384=head2 dynamic_config 385 386Example: 387 388 dynamic_config: 0 389 390(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> 391or F<Makefile.PL> (or similar) must be executed when building this 392distribution, or whether it can be built, tested and installed solely 393from consulting its 394metadata file. The main reason to set this to a true value is that 395your module performs some dynamic configuration (asking questions, 396sensing the environment, etc.) as part of its build/install process. 397 398Currently Module::Build doesn't actually do anything with this flag 399- it's probably going to be up to higher-level tools like CPAN 400to do something useful with it. It can potentially bring lots of 401security, packaging, and convenience improvements. 402 403If this field is omitted, it defaults to 1 (true). 404 405=head2 private 406 407I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to 408L</no_index>. See below. 409 410=head2 provides 411 412Example: 413 414 provides: 415 Foo::Bar: 416 file: lib/Foo/Bar.pm 417 version: 0.27_02 418 Foo::Bar::Blah: 419 file: lib/Foo/Bar/Blah.pm 420 Foo::Bar::Baz: 421 file: lib/Foo/Bar/Baz.pm 422 version: 0.3 423 424(Spec 1.1) [optional] {map} A YAML mapping that describes all packages 425provided by this distribution. This information can be (and, in some 426cases, is) used by distribution and automation mechanisms like PAUSE, 427CPAN, and search.cpan.org to build indexes saying in which 428distribution various packages can be found. 429 430When using tools like L<Module::Build> that can generate the 431C<provides> mapping for your distribution automatically, make sure you 432examine what it generates to make sure it makes sense - indexers will 433usually trust the C<provides> field if it's present, rather than 434scanning through the distribution files themselves to figure out 435packages and versions. This is a good thing, because it means you can 436use the C<provides> field to tell the indexers precisely what you want 437indexed about your distribution, rather than relying on them to 438essentially guess what you want indexed. 439 440=head2 no_index 441 442Example: 443 444 no_index: 445 file: 446 - My/Module.pm 447 directory: 448 - My/Private 449 package: 450 - My::Module::Stuff 451 namespace: 452 - My::Module::Stuff 453 454(Spec 1.1) [optional] {map} A YAML mapping that describes any files, 455directories, packages, and namespaces that are private 456(i.e. implementation artifacts) that are not of interest to searching 457and indexing tools. This is useful when no C<provides> field is 458present. 459 460For example, L<http://search.cpan.org/> excludes items listed in C<no_index> 461when searching for POD, meaning files in these directories will not 462converted to HTML and made public - which is useful if you have 463example or test PODs that you don't want the search engine to go 464through. 465 466=head3 file 467 468(Spec 1.1) [optional] Exclude any listed file(s). 469 470=head3 directory 471 472(Spec 1.1) [optional] Exclude anything below the listed 473directory(ies). 474 475[Note: previous editions of the spec had C<dir> instead of 476C<directory>, but I think MakeMaker and various users started using 477C<directory>, so in deference we switched to that.] 478 479=head3 package 480 481(Spec 1.1) [optional] Exclude the listed package(s). 482 483=head3 namespace 484 485(Spec 1.1) [optional] Excludes anything below the listed namespace(s), 486but I<not> the listed namespace(s) its self. 487 488=head2 keywords 489 490Example: 491 492 keywords: 493 - make 494 - build 495 - install 496 497(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe 498this distribution. 499 500=head2 resources 501 502Example: 503 504 resources: 505 license: http://dev.perl.org/licenses/ 506 homepage: http://sourceforge.net/projects/module-build 507 bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build 508 repository: http://sourceforge.net/cvs/?group_id=45731 509 MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general 510 511(Spec 1.1) [optional] {map} A mapping of any URL resources related to 512this distribution. All-lower-case keys, such as C<homepage>, 513C<license>, and C<bugtracker>, are reserved by this specification, as 514they have "official" meanings defined here in this specification. If 515you'd like to add your own "special" entries (like the "MailingList" 516entry above), use at least one upper-case letter. 517 518The current set of official keys is: 519 520=over 2 521 522=item homepage 523 524The official home of this project on the web. 525 526=item license 527 528An URL for an official statement of this distribution's license. 529 530=item bugtracker 531 532An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. 533 534=back 535 536 537=head2 generated_by 538 539Example: 540 541 generated_by: Module::Build version 0.20 542 543(Spec 1.0) [required] {string} Indicates the tool that was used to create this 544F<META.yml> file. It's good form to include both the name of the tool 545and its version, but this field is essentially opaque, at least for 546the moment. If F<META.yml> was generated by hand, it is suggested that 547the author be specified here. 548 549[Note: My F<meta_stats.pl> script which I use to gather statistics 550regarding F<META.yml> usage prefers the form listed above, i.e. it 551splits on /\s+version\s+/ taking the first field as the name of the 552tool that generated the file and the second field as version of that 553tool. RWS] 554 555=head1 VERSION SPECIFICATIONS 556 557Some fields require a version specification (ex. L</requires>, 558L</recommends>, L</build_requires>, etc.) to indicate the particular 559versionZ<>(s) of some other module that may be required as a 560prerequisite. This section details the version specification formats 561that are currently supported. 562 563The simplest format for a version specification is just the version 564number itself, e.g. C<2.4>. This means that B<at least> version 2.4 565must be present. To indicate that B<any> version of a prerequisite is 566okay, even if the prerequisite doesn't define a version at all, use 567the version C<0>. 568 569You may also use the operators E<lt> (less than), E<lt>= (less than or 570equal), E<gt> (greater than), E<gt>= (greater than or equal), == 571(equal), and != (not equal). For example, the specification C<E<lt> 5722.0> means that any version of the prerequisite less than 2.0 is 573suitable. 574 575For more complicated situations, version specifications may be AND-ed 576together using commas. The specification C<E<gt>= 1.2, != 1.5, E<lt> 5772.0> indicates a version that must be B<at least> 1.2, B<less than> 5782.0, and B<not equal to> 1.5. 579 580=head1 SEE ALSO 581 582L<CPAN|http://www.cpan.org/> 583 584L<CPAN.pm|CPAN> 585 586L<CPANPLUS> 587 588L<Data::Dumper> 589 590L<ExtUtils::MakeMaker> 591 592L<Module::Build> 593 594L<Module::Install> 595 596L<XML|http://www.w3.org/XML/> 597 598L<YAML|http://www.yaml.org/> 599 600=head1 HISTORY 601 602=over 4 603 604=item March 14, 2003 (Pi day) 605 606=over 2 607 608=item * 609 610Created version 1.0 of this document. 611 612=back 613 614=item May 8, 2003 615 616=over 2 617 618=item * 619 620Added the L</dynamic_config> field, which was missing from the initial 621version. 622 623=back 624 625=item November 13, 2003 626 627=over 2 628 629=item * 630 631Added more YAML rationale articles. 632 633=item * 634 635Fixed existing link to YAML discussion thread to point to new 636L<http://nntp.x.perl.org/group/> site. 637 638=item * 639 640Added and deprecated the L</private> field. 641 642=item * 643 644Added L</abstract>, C<configure>, C<requires_packages>, 645C<requires_os>, C<excludes_os>, and L</no_index> fields. 646 647=item * 648 649Bumped version. 650 651=back 652 653=item November 16, 2003 654 655=over 2 656 657=item * 658 659Added C<generation>, C<authored_by> fields. 660 661=item * 662 663Add alternative proposal to the L</recommends> field. 664 665=item * 666 667Add proposal for a C<requires_build_tools> field. 668 669=back 670 671=item December 9, 2003 672 673=over 2 674 675=item * 676 677Added link to latest version of this specification on CPAN. 678 679=item * 680 681Added section L</"VERSION SPECIFICATIONS">. 682 683=item * 684 685Chang name from Module::Build::META-spec to CPAN::META::Specification. 686 687=item * 688 689Add proposal for C<auto_regenerate> field. 690 691=back 692 693=item December 15, 2003 694 695=over 2 696 697=item * 698 699Add C<index> field as a compliment to L</no_index> 700 701=item * 702 703Add L</keywords> field as a means to aid searching distributions. 704 705=item * 706 707Add L</TERMINOLOGY> section to explain certain terms that may be 708ambiguous. 709 710=back 711 712=item July 26, 2005 713 714=over 2 715 716=item * 717 718Removed a bunch of items (generation, requires_build_tools, 719requires_packages, configure, requires_os, excludes_os, 720auto_regenerate) that have never actually been supported, but were 721more like records of brainstorming. 722 723=item * 724 725Changed C<authored_by> to L</author>, since that's always been what 726it's actually called in actual F<META.yml> files. 727 728=item * 729 730Added the "==" operator to the list of supported version-checking 731operators. 732 733=item * 734 735Noted that the L</distribution_type> field is basically meaningless, 736and shouldn't really be used. 737 738=item * 739 740Clarified L</dynamic_config> a bit. 741 742=back 743 744=item August 23, 2005 745 746=over 2 747 748=item * 749 750Removed the name C<CPAN::META::Specification>, since that implies a 751module that doesn't actually exist. 752 753=back 754 755=item June 12, 2007 756 757=over 2 758 759=item * 760 761Added L</configure_requires>. 762 763=back 764 765=back 766