1=for :stopwords MailingList PODs RWS subcontext 2 3=head1 NAME 4 5CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for META.yml 6 7=head1 PREFACE 8 9This is a historical copy of the version 1.3 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.2805 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 urls: 65 license: http://dev.perl.org/licenses/ 66 meta-spec: 67 version: 1.3 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.3 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.3 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 distribution may be 206used 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 259version 1 or the Artistic version 1 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 modules this 299distribution requires for proper operation. The keys are the module 300names, and the values are version specifications as described in 301L</"VERSION SPECIFICATIONS">. 302 303=head2 recommends 304 305Example: 306 307 recommends: 308 Data::Dumper: 0 309 File::Find: 1.03 310 311(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules 312this distribution recommends for enhanced operation. The keys are the 313module names, and the values are version specifications as described 314in L</"VERSION SPECIFICATIONS">. 315 316 317 318I<ALTERNATIVE: It may be desirable to present to the user which 319features depend on which modules so they can make an informed decision 320about which recommended modules to install.> 321 322Example: 323 324 optional_features: 325 - foo: 326 description: Provides the ability to blah. 327 requires: 328 Data::Dumper: 0 329 File::Find: 1.03 330 - bar: 331 description: This feature is not available on this platform. 332 excludes_os: MSWin32 333 334I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features 335which are made available when its requirements are met. For each 336feature a description is provided along with any of L</requires>, 337L</build_requires>, L</conflicts>, C<requires_packages>, 338C<requires_os>, and C<excludes_os> which have the same meaning in 339this subcontext as described elsewhere in this document.> 340 341=head2 build_requires 342 343Example: 344 345 build_requires: 346 Data::Dumper: 0 347 File::Find: 1.03 348 349(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules 350required for building and/or testing of this distribution. The keys 351are the module names, and the values are version specifications as 352described in L</"VERSION SPECIFICATIONS">. These dependencies are not 353required after the module is installed. 354 355=head2 conflicts 356 357Example: 358 359 conflicts: 360 Data::Dumper: 0 361 File::Find: 1.03 362 363(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that 364cannot be installed while this distribution is installed. This is a 365pretty uncommon situation. The keys for C<conflicts> are the module 366names, and the values are version specifications as described in 367L</"VERSION SPECIFICATIONS">. 368 369 370=head2 dynamic_config 371 372Example: 373 374 dynamic_config: 0 375 376(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> 377or F<Makefile.PL> (or similar) must be executed when building this 378distribution, or whether it can be built, tested and installed solely 379from consulting its 380metadata file. The main reason to set this to a true value is that 381your module performs some dynamic configuration (asking questions, 382sensing the environment, etc.) as part of its build/install process. 383 384Currently Module::Build doesn't actually do anything with this flag 385- it's probably going to be up to higher-level tools like CPAN 386to do something useful with it. It can potentially bring lots of 387security, packaging, and convenience improvements. 388 389If this field is omitted, it defaults to 1 (true). 390 391=head2 private 392 393I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to 394L</no_index>. See below. 395 396=head2 provides 397 398Example: 399 400 provides: 401 Foo::Bar: 402 file: lib/Foo/Bar.pm 403 version: 0.27_02 404 Foo::Bar::Blah: 405 file: lib/Foo/Bar/Blah.pm 406 Foo::Bar::Baz: 407 file: lib/Foo/Bar/Baz.pm 408 version: 0.3 409 410(Spec 1.1) [optional] {map} A YAML mapping that describes all packages 411provided by this distribution. This information can be (and, in some 412cases, is) used by distribution and automation mechanisms like PAUSE, 413CPAN, and search.cpan.org to build indexes saying in which 414distribution various packages can be found. 415 416When using tools like L<Module::Build> that can generate the 417C<provides> mapping for your distribution automatically, make sure you 418examine what it generates to make sure it makes sense - indexers will 419usually trust the C<provides> field if it's present, rather than 420scanning through the distribution files themselves to figure out 421packages and versions. This is a good thing, because it means you can 422use the C<provides> field to tell the indexers precisely what you want 423indexed about your distribution, rather than relying on them to 424essentially guess what you want indexed. 425 426=head2 no_index 427 428Example: 429 430 no_index: 431 file: 432 - My/Module.pm 433 directory: 434 - My/Private 435 package: 436 - My::Module::Stuff 437 namespace: 438 - My::Module::Stuff 439 440(Spec 1.1) [optional] {map} A YAML mapping that describes any files, 441directories, packages, and namespaces that are private 442(i.e. implementation artifacts) that are not of interest to searching 443and indexing tools. This is useful when no C<provides> field is 444present. 445 446For example, L<http://search.cpan.org/> excludes items listed in C<no_index> 447when searching for POD, meaning files in these directories will not 448converted to HTML and made public - which is useful if you have 449example or test PODs that you don't want the search engine to go 450through. 451 452=head3 file 453 454(Spec 1.1) [optional] Exclude any listed file(s). 455 456=head3 directory 457 458(Spec 1.1) [optional] Exclude anything below the listed 459directory(ies). 460 461[Note: previous editions of the spec had C<dir> instead of 462C<directory>, but I think MakeMaker and various users started using 463C<directory>, so in deference we switched to that.] 464 465=head3 package 466 467(Spec 1.1) [optional] Exclude the listed package(s). 468 469=head3 namespace 470 471(Spec 1.1) [optional] Excludes anything below the listed namespace(s), 472but I<not> the listed namespace(s) its self. 473 474=head2 keywords 475 476Example: 477 478 keywords: 479 - make 480 - build 481 - install 482 483(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe 484this distribution. 485 486=head2 resources 487 488Example: 489 490 resources: 491 license: http://dev.perl.org/licenses/ 492 homepage: http://sourceforge.net/projects/module-build 493 bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build 494 repository: http://sourceforge.net/cvs/?group_id=45731 495 MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general 496 497(Spec 1.1) [optional] {map} A mapping of any URL resources related to 498this distribution. All-lower-case keys, such as C<homepage>, 499C<license>, and C<bugtracker>, are reserved by this specification, as 500they have "official" meanings defined here in this specification. If 501you'd like to add your own "special" entries (like the "MailingList" 502entry above), use at least one upper-case letter. 503 504The current set of official keys is: 505 506=over 2 507 508=item homepage 509 510The official home of this project on the web. 511 512=item license 513 514An URL for an official statement of this distribution's license. 515 516=item bugtracker 517 518An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. 519 520=back 521 522 523=head2 generated_by 524 525Example: 526 527 generated_by: Module::Build version 0.20 528 529(Spec 1.0) [required] {string} Indicates the tool that was used to create this 530F<META.yml> file. It's good form to include both the name of the tool 531and its version, but this field is essentially opaque, at least for 532the moment. If F<META.yml> was generated by hand, it is suggested that 533the author be specified here. 534 535[Note: My F<meta_stats.pl> script which I use to gather statistics 536regarding F<META.yml> usage prefers the form listed above, i.e. it 537splits on /\s+version\s+/ taking the first field as the name of the 538tool that generated the file and the second field as version of that 539tool. RWS] 540 541=head1 VERSION SPECIFICATIONS 542 543Some fields require a version specification (ex. L</requires>, 544L</recommends>, L</build_requires>, etc.) to indicate the particular 545versionZ<>(s) of some other module that may be required as a 546prerequisite. This section details the version specification formats 547that are currently supported. 548 549The simplest format for a version specification is just the version 550number itself, e.g. C<2.4>. This means that B<at least> version 2.4 551must be present. To indicate that B<any> version of a prerequisite is 552okay, even if the prerequisite doesn't define a version at all, use 553the version C<0>. 554 555You may also use the operators E<lt> (less than), E<lt>= (less than or 556equal), E<gt> (greater than), E<gt>= (greater than or equal), == 557(equal), and != (not equal). For example, the specification C<E<lt> 5582.0> means that any version of the prerequisite less than 2.0 is 559suitable. 560 561For more complicated situations, version specifications may be AND-ed 562together using commas. The specification C<E<gt>= 1.2, != 1.5, E<lt> 5632.0> indicates a version that must be B<at least> 1.2, B<less than> 5642.0, and B<not equal to> 1.5. 565 566=head1 SEE ALSO 567 568L<CPAN|http://www.cpan.org/> 569 570L<CPAN.pm|CPAN> 571 572L<CPANPLUS> 573 574L<Data::Dumper> 575 576L<ExtUtils::MakeMaker> 577 578L<Module::Build> 579 580L<Module::Install> 581 582L<XML|http://www.w3.org/XML/> 583 584L<YAML|http://www.yaml.org/> 585 586=head1 HISTORY 587 588=over 4 589 590=item March 14, 2003 (Pi day) 591 592=over 2 593 594=item * 595 596Created version 1.0 of this document. 597 598=back 599 600=item May 8, 2003 601 602=over 2 603 604=item * 605 606Added the L</dynamic_config> field, which was missing from the initial 607version. 608 609=back 610 611=item November 13, 2003 612 613=over 2 614 615=item * 616 617Added more YAML rationale articles. 618 619=item * 620 621Fixed existing link to YAML discussion thread to point to new 622L<http://nntp.x.perl.org/group/> site. 623 624=item * 625 626Added and deprecated the L</private> field. 627 628=item * 629 630Added L</abstract>, C<configure>, C<requires_packages>, 631C<requires_os>, C<excludes_os>, and L</no_index> fields. 632 633=item * 634 635Bumped version. 636 637=back 638 639=item November 16, 2003 640 641=over 2 642 643=item * 644 645Added C<generation>, C<authored_by> fields. 646 647=item * 648 649Add alternative proposal to the L</recommends> field. 650 651=item * 652 653Add proposal for a C<requires_build_tools> field. 654 655=back 656 657=item December 9, 2003 658 659=over 2 660 661=item * 662 663Added link to latest version of this specification on CPAN. 664 665=item * 666 667Added section L</"VERSION SPECIFICATIONS">. 668 669=item * 670 671Chang name from Module::Build::META-spec to CPAN::META::Specification. 672 673=item * 674 675Add proposal for C<auto_regenerate> field. 676 677=back 678 679=item December 15, 2003 680 681=over 2 682 683=item * 684 685Add C<index> field as a compliment to L</no_index> 686 687=item * 688 689Add L</keywords> field as a means to aid searching distributions. 690 691=item * 692 693Add L</TERMINOLOGY> section to explain certain terms that may be 694ambiguous. 695 696=back 697 698=item July 26, 2005 699 700=over 2 701 702=item * 703 704Removed a bunch of items (generation, requires_build_tools, 705requires_packages, configure, requires_os, excludes_os, 706auto_regenerate) that have never actually been supported, but were 707more like records of brainstorming. 708 709=item * 710 711Changed C<authored_by> to L</author>, since that's always been what 712it's actually called in actual F<META.yml> files. 713 714=item * 715 716Added the "==" operator to the list of supported version-checking 717operators. 718 719=item * 720 721Noted that the L</distribution_type> field is basically meaningless, 722and shouldn't really be used. 723 724=item * 725 726Clarified L</dynamic_config> a bit. 727 728=back 729 730=item August 23, 2005 731 732=over 2 733 734=item * 735 736Removed the name C<CPAN::META::Specification>, since that implies a 737module that doesn't actually exist. 738 739=back 740 741=back 742