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