1=for :stopwords MailingList RWS subcontext 2 3=head1 NAME 4 5CPAN::Meta::History::Meta_1_2 - Version 1.2 metadata specification for META.yml 6 7=head1 PREFACE 8 9This is a historical copy of the version 1.2 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.2611 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.2 68 url: http://module-build.sourceforge.net/META-spec-v1.2.html 69 generated_by: Module::Build version 0.20 70 71=head1 DESCRIPTION 72 73This document describes version 1.2 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 125for other developers to use. 126 127=item module 128 129This refers to a reusable library of code typically contained in a 130single file. Currently, we primarily talk of perl modules, but this 131specification should be open enough to apply to other languages as 132well (ex. python, ruby). 133 134=back 135 136=head1 VERSION SPECIFICATIONS 137 138Some fields require a version specification (ex. L</requires>, 139L</recommends>, L</build_requires>, etc.). This section details the 140version specifications that are currently supported. 141 142If a single version is listed, then that version is considered to be 143the minimum version supported. 144 145If 0 is given as the version number, then any version is supported. 146 147Additionally, for more complicated requirements, the specification 148supports a list of versions, each of which may be optionally preceded 149by a relational operator. 150 151Supported operators include E<lt> (less than), E<lt>= (less than or 152equal), E<gt> (greater than), E<gt>= (greater than or equal), == (equal), and != 153(not equal). 154 155If a list is given then it is evaluated from left to right so that any 156specifications in the list that conflict with a previous specification 157are overridden by the later. 158 159Examples: 160 161 >= 1.2, != 1.5, < 2.0 162 163Any version from version 1.2 onward, except version 1.5, that also 164precedes version 2.0. 165 166=head1 HEADER 167 168The first line of a F<META.yml> file should be a valid YAML document 169header like C<"--- #YAML:1.0">. 170 171=head1 FIELDS 172 173The rest of the F<META.yml> file is one big YAML mapping whose keys 174are described here. 175 176=head2 meta-spec 177 178Example: 179 180 meta-spec: 181 version: 1.2 182 url: http://module-build.sourceforge.net/META-spec-v1.2.html 183 184(Spec 1.1) [required] {URL} This field indicates the location of the 185version of the META.yml specification used. 186 187=head2 name 188 189Example: 190 191 name: Module-Build 192 193(Spec 1.0) [required] {string} The name of the distribution which is often 194created by taking the "main module" in the distribution and changing 195"::" to "-". Sometimes it's completely different, however, as in the 196case of the libwww-perl distribution (see 197L<http://search.cpan.org/author/GAAS/libwww-perl/>). 198 199=head2 version 200 201Example: 202 203 version: 0.20 204 205(Spec 1.0) [required] {version} The version of the distribution to which the 206F<META.yml> file refers. 207 208=head2 abstract 209 210Example: 211 212 abstract: Build and install Perl modules. 213 214(Spec 1.1) [required] {string} A short description of the purpose of the 215distribution. 216 217=head2 author 218 219Example: 220 221 author: 222 - Ken Williams <kwilliams@cpan.org> 223 224(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the 225distribution. The preferred form is author-name <email-address>. 226 227=head2 license 228 229Example: 230 231 license: perl 232 233(Spec 1.0) [required] {string} The license under which this distribution may be 234used and redistributed. 235 236Must be one of the following licenses: 237 238=over 4 239 240=item perl 241 242The distribution may be copied and redistributed under the same terms as perl 243itself (this is by far the most common licensing option for modules on CPAN). 244This is a dual license, in which the user may choose between either the GPL 245version 1 or the Artistic version 1 license. 246 247=item gpl 248 249The distribution is distributed under the terms of the GNU General Public 250License version 2 (L<http://opensource.org/licenses/GPL-2.0>). 251 252=item lgpl 253 254The distribution is distributed under the terms of the GNU Lesser General 255Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>). 256 257=item artistic 258 259The distribution is licensed under the Artistic License version 1, as specified 260by the Artistic file in the standard perl distribution 261(L<http://opensource.org/licenses/Artistic-Perl-1.0>). 262 263=item bsd 264 265The distribution is licensed under the BSD 3-Clause License 266(L<http://opensource.org/licenses/BSD-3-Clause>). 267 268=item open_source 269 270The distribution is licensed under some other Open Source Initiative-approved 271license listed at L<http://www.opensource.org/licenses/>. 272 273=item unrestricted 274 275The distribution is licensed under a license that is B<not> approved by 276L<www.opensource.org|http://www.opensource.org/> but that allows distribution 277without restrictions. 278 279=item restrictive 280 281The distribution may not be redistributed without special permission from the 282author and/or copyright holder. 283 284=back 285 286=head2 distribution_type 287 288Example: 289 290 distribution_type: module 291 292(Spec 1.0) [optional] {string} What kind of stuff is contained in this 293distribution. Most things on CPAN are C<module>s (which can also mean 294a collection of modules), but some things are C<script>s. 295 296Unfortunately this field is basically meaningless, since many 297distributions are hybrids of several kinds of things, or some new 298thing, or subjectively different in focus depending on who's using 299them. Tools like Module::Build and MakeMaker will likely stop 300generating this field. 301 302=head2 requires 303 304Example: 305 306 requires: 307 Data::Dumper: 0 308 File::Find: 1.03 309 310(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this 311distribution requires for proper operation. The keys are the module 312names, and the values are version specifications as described in 313L<Module::Build> for the "requires" parameter. 314 315=head2 recommends 316 317Example: 318 319 recommends: 320 Data::Dumper: 0 321 File::Find: 1.03 322 323(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this 324distribution recommends for enhanced operation. 325 326I<ALTERNATIVE: It may be desirable to present to the user which 327features depend on which modules so they can make an informed 328decision about which recommended modules to install.> 329 330Example: 331 332 optional_features: 333 - foo: 334 description: Provides the ability to blah. 335 requires: 336 Data::Dumper: 0 337 File::Find: 1.03 338 - bar: 339 description: This feature is not available on this platform. 340 excludes_os: MSWin32 341 342I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features 343which are made available when its requirements are met. For each 344feature a description is provided along with any of L</requires>, 345L</build_requires>, L</conflicts>, C<requires_packages>, 346C<requires_os>, and C<excludes_os> which have the same meaning in 347this subcontext as described elsewhere in this document.> 348 349=head2 build_requires 350 351Example: 352 353 build_requires: 354 Data::Dumper: 0 355 File::Find: 1.03 356 357(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules 358required for building and/or testing of this distribution. These 359dependencies are not required after the module is installed. 360 361=head2 conflicts 362 363Example: 364 365 conflicts: 366 Data::Dumper: 0 367 File::Find: 1.03 368 369(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that 370cannot be installed while this distribution is installed. This is a 371pretty uncommon situation. 372 373=head2 dynamic_config 374 375Example: 376 377 dynamic_config: 0 378 379(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> 380or F<Makefile.PL> (or similar) must be executed when building this 381distribution, or whether it can be built, tested and installed solely 382from consulting its 383metadata file. The main reason to set this to a true value if that 384your module performs some dynamic configuration (asking questions, 385sensing the environment, etc.) as part of its build/install process. 386 387Currently Module::Build doesn't actually do anything with this flag 388- it's probably going to be up to higher-level tools like CPAN 389to do something useful with it. It can potentially bring lots of 390security, packaging, and convenience improvements. 391 392If this field is omitted, it defaults to 1 (true). 393 394=head2 private 395 396I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to 397L</no_index>. See below. 398 399=head2 provides 400 401Example: 402 403 provides: 404 Foo::Bar: 405 file: lib/Foo/Bar.pm 406 version: 0.27_02 407 Foo::Bar::Blah: 408 file: lib/Foo/Bar/Blah.pm 409 Foo::Bar::Baz: 410 file: lib/Foo/Bar/Baz.pm 411 version: 0.3 412 413(Spec 1.1) [optional] {map} A YAML mapping that describes all packages 414provided by this distribution. This information can be (and, in some 415cases, is) used by distribution and automation mechanisms like PAUSE, 416CPAN, and search.cpan.org to build indexes saying in which 417distribution various packages can be found. 418 419When using tools like L<Module::Build> that can generate the 420C<provides> mapping for your distribution automatically, make sure you 421examine what it generates to make sure it makes sense - indexers will 422usually trust the C<provides> field if it's present, rather than 423scanning through the distribution files themselves to figure out 424packages and versions. This is a good thing, because it means you can 425use the C<provides> field to tell the indexers precisely what you want 426indexed about your distribution, rather than relying on them to 427essentially guess what you want indexed. 428 429=head2 no_index 430 431Example: 432 433 no_index: 434 file: 435 - My/Module.pm 436 dir: 437 - My/Private 438 package: 439 - My::Module::Stuff 440 namespace: 441 - My::Module::Stuff 442 443(Spec 1.1) [optional] {map} A YAML mapping that describes any files, 444directories, packages, and namespaces that are private 445(i.e. implementation artifacts) that are not of interest to searching 446and indexing tools. This is useful when no C<provides> field is 447present. 448 449I<(Note: I'm not actually sure who looks at this field, or exactly 450what they do with it. This spec could be off in some way from actual 451usage.)> 452 453=head3 file 454 455(Spec 1.1) [optional] Exclude any listed file(s). 456 457=head3 dir 458 459(Spec 1.1) [optional] Exclude anything below the listed 460directory(ies). 461 462=head3 package 463 464(Spec 1.1) [optional] Exclude the listed package(s). 465 466=head3 namespace 467 468(Spec 1.1) [optional] Excludes anything below the listed namespace(s), 469but I<not> the listed namespace(s) its self. 470 471=head2 keywords 472 473Example: 474 475 keywords: 476 - make 477 - build 478 - install 479 480(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe 481this distribution. 482 483=head2 resources 484 485Example: 486 487 resources: 488 license: http://dev.perl.org/licenses/ 489 homepage: http://sourceforge.net/projects/module-build 490 bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build 491 MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general 492 493(Spec 1.1) [optional] {map} A mapping of any URL resources related to 494this distribution. All-lower-case keys, such as C<homepage>, 495C<license>, and C<bugtracker>, are reserved by this specification, as 496they have "official" meanings defined here in this specification. If 497you'd like to add your own "special" entries (like the "MailingList" 498entry above), use at least one upper-case letter. 499 500The current set of official keys is: 501 502=over 2 503 504=item homepage 505 506The official home of this project on the web. 507 508=item license 509 510An URL for an official statement of this distribution's license. 511 512=item bugtracker 513 514An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. 515 516=back 517 518 519=head2 generated_by 520 521Example: 522 523 generated_by: Module::Build version 0.20 524 525(Spec 1.0) [required] {string} Indicates the tool that was used to create this 526F<META.yml> file. It's good form to include both the name of the tool 527and its version, but this field is essentially opaque, at least for 528the moment. If F<META.yml> was generated by hand, it is suggested that 529the author be specified here. 530 531[Note: My F<meta_stats.pl> script which I use to gather statistics 532regarding F<META.yml> usage prefers the form listed above, i.e. it 533splits on /\s+version\s+/ taking the first field as the name of the 534tool that generated the file and the second field as version of that 535tool. RWS] 536 537=head1 SEE ALSO 538 539L<CPAN|http://www.cpan.org/> 540 541L<CPAN.pm|CPAN> 542 543L<CPANPLUS> 544 545L<Data::Dumper> 546 547L<ExtUtils::MakeMaker> 548 549L<Module::Build> 550 551L<Module::Install> 552 553L<XML|http://www.w3.org/XML/> 554 555L<YAML|http://www.yaml.org/> 556 557=head1 HISTORY 558 559=over 4 560 561=item March 14, 2003 (Pi day) 562 563=over 2 564 565=item * 566 567Created version 1.0 of this document. 568 569=back 570 571=item May 8, 2003 572 573=over 2 574 575=item * 576 577Added the L</dynamic_config> field, which was missing from the initial 578version. 579 580=back 581 582=item November 13, 2003 583 584=over 2 585 586=item * 587 588Added more YAML rationale articles. 589 590=item * 591 592Fixed existing link to YAML discussion thread to point to new 593L<http://nntp.x.perl.org/group/> site. 594 595=item * 596 597Added and deprecated the L</private> field. 598 599=item * 600 601Added L</abstract>, C<configure>, C<requires_packages>, 602C<requires_os>, C<excludes_os>, and L</no_index> fields. 603 604=item * 605 606Bumped version. 607 608=back 609 610=item November 16, 2003 611 612=over 2 613 614=item * 615 616Added C<generation>, C<authored_by> fields. 617 618=item * 619 620Add alternative proposal to the L</recommends> field. 621 622=item * 623 624Add proposal for a C<requires_build_tools> field. 625 626=back 627 628=item December 9, 2003 629 630=over 2 631 632=item * 633 634Added link to latest version of this specification on CPAN. 635 636=item * 637 638Added section L</"VERSION SPECIFICATIONS">. 639 640=item * 641 642Chang name from Module::Build::META-spec to CPAN::META::Specification. 643 644=item * 645 646Add proposal for C<auto_regenerate> field. 647 648=back 649 650=item December 15, 2003 651 652=over 2 653 654=item * 655 656Add C<index> field as a compliment to L</no_index> 657 658=item * 659 660Add L</keywords> field as a means to aid searching distributions. 661 662=item * 663 664Add L</TERMINOLOGY> section to explain certain terms that may be 665ambiguous. 666 667=back 668 669=item July 26, 2005 670 671=over 2 672 673=item * 674 675Removed a bunch of items (generation, requires_build_tools, 676requires_packages, configure, requires_os, excludes_os, 677auto_regenerate) that have never actually been supported, but were 678more like records of brainstorming. 679 680=item * 681 682Changed C<authored_by> to L</author>, since that's always been what 683it's actually called in actual F<META.yml> files. 684 685=item * 686 687Added the "==" operator to the list of supported version-checking 688operators. 689 690=item * 691 692Noted that the L</distribution_type> field is basically meaningless, 693and shouldn't really be used. 694 695=item * 696 697Clarified L</dynamic_config> a bit. 698 699=back 700 701=item August 23, 2005 702 703=over 2 704 705=item * 706 707Removed the name C<CPAN::META::Specification>, since that implies a 708module that doesn't actually exist. 709 710=back 711 712=back 713