In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/a770949e9fb75429772c3b99590c5599df3ff999?hp=7e7942b7bb27d449f31c691a6c1262f300514949>
- Log ----------------------------------------------------------------- commit a770949e9fb75429772c3b99590c5599df3ff999 Author: Chris 'BinGOs' Williams <[email protected]> Date: Mon Sep 29 13:14:11 2014 +0100 Regen Makefile.SH for CPAN-Meta update M Makefile.SH commit 719c8ab4d5d10e128d1e3329ecb50c29cd074ce3 Author: Chris 'BinGOs' Williams <[email protected]> Date: Mon Sep 29 12:18:01 2014 +0100 Regen META files following update of CPAN-Meta For future reference: Update cpan/CPAN-Meta Build perl ./perl -Ilib Porting/makemeta M META.json M META.yml commit 29fba1397042ef18f89fd15eba7cc9f00bc064ff Author: Chris 'BinGOs' Williams <[email protected]> Date: Mon Sep 29 12:12:47 2014 +0100 Update CPAN-Meta to CPAN version 2.142690 [DELTA] 2.142690 2014-09-26 11:06:34-04:00 America/New_York [DOCUMENTED] - Clarified that no_index is a list of exclusions, and that indexers should generally exclude 'inc', 'xt' and 't' as well. M MANIFEST M Porting/Maintainers.pl M cpan/CPAN-Meta/lib/CPAN/Meta.pm M cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm M cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm M cpan/CPAN-Meta/lib/CPAN/Meta/History.pm A cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod A cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod A cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod A cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod A cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_4.pod M cpan/CPAN-Meta/lib/CPAN/Meta/Merge.pm M cpan/CPAN-Meta/lib/CPAN/Meta/Prereqs.pm M cpan/CPAN-Meta/lib/CPAN/Meta/Spec.pm M cpan/CPAN-Meta/lib/CPAN/Meta/Validator.pm M cpan/CPAN-Meta/t/converter.t M cpan/CPAN-Meta/t/merge.t commit 7b060fdbaf8c0d22e561dd8d9e4b1b147997e707 Author: Chris 'BinGOs' Williams <[email protected]> Date: Mon Sep 29 12:10:58 2014 +0100 Update HTTP-Tiny to CPAN version 0.050 [DELTA] 0.050 2014-09-23 15:30:18-04:00 America/New_York [FIXED] - Fixed CONNECT requests for some proxies M Porting/Maintainers.pl M cpan/HTTP-Tiny/lib/HTTP/Tiny.pm commit 4177cbcef9e372eb623af46b4ffaaf9ff1c147c4 Author: Chris 'BinGOs' Williams <[email protected]> Date: Mon Sep 29 12:09:38 2014 +0100 Update experimental to CPAN version 0.011 [DELTA] 0.011 2014-09-27 14:08:47+02:00 Europe/Amsterdam Clarified which order to apply pragmas [Grant McLean] M Porting/Maintainers.pl M cpan/experimental/lib/experimental.pm ----------------------------------------------------------------------- Summary of changes: MANIFEST | 5 + META.json | 2 +- META.yml | 2 +- Makefile.SH | 11 +- Porting/Maintainers.pl | 6 +- cpan/CPAN-Meta/lib/CPAN/Meta.pm | 28 +- cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm | 29 +- cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm | 6 +- cpan/CPAN-Meta/lib/CPAN/Meta/History.pm | 6 +- cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod | 185 ++++++ cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod | 247 ++++++++ cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod | 658 ++++++++++++++++++++ cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod | 665 ++++++++++++++++++++ cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_4.pod | 719 ++++++++++++++++++++++ cpan/CPAN-Meta/lib/CPAN/Meta/Merge.pm | 11 +- cpan/CPAN-Meta/lib/CPAN/Meta/Prereqs.pm | 6 +- cpan/CPAN-Meta/lib/CPAN/Meta/Spec.pm | 29 +- cpan/CPAN-Meta/lib/CPAN/Meta/Validator.pm | 6 +- cpan/CPAN-Meta/t/converter.t | 1 - cpan/CPAN-Meta/t/merge.t | 6 + cpan/HTTP-Tiny/lib/HTTP/Tiny.pm | 21 +- cpan/experimental/lib/experimental.pm | 24 +- 22 files changed, 2614 insertions(+), 59 deletions(-) create mode 100644 cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod create mode 100644 cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod create mode 100644 cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod create mode 100644 cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod create mode 100644 cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_4.pod diff --git a/MANIFEST b/MANIFEST index f708f20..07c1d1a 100644 --- a/MANIFEST +++ b/MANIFEST @@ -237,6 +237,11 @@ cpan/CPAN/lib/CPAN/URL.pm cpan/CPAN/lib/CPAN/Version.pm Simple math with different flavors of version strings cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm +cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod +cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod +cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod +cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod +cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_4.pod cpan/CPAN-Meta/lib/CPAN/Meta/History.pm cpan/CPAN-Meta/lib/CPAN/Meta/Merge.pm cpan/CPAN-Meta/lib/CPAN/Meta.pm diff --git a/META.json b/META.json index 4715599..9ea508e 100644 --- a/META.json +++ b/META.json @@ -4,7 +4,7 @@ "[email protected]" ], "dynamic_config" : 1, - "generated_by" : "CPAN::Meta version 2.142060", + "generated_by" : "CPAN::Meta version 2.142690", "license" : [ "perl_5" ], diff --git a/META.yml b/META.yml index 8e821a9..17d7bdd 100644 --- a/META.yml +++ b/META.yml @@ -4,7 +4,7 @@ author: - [email protected] build_requires: {} dynamic_config: 1 -generated_by: 'CPAN::Meta version 2.142060, CPAN::Meta::Converter version 2.142060' +generated_by: 'CPAN::Meta version 2.142690, CPAN::Meta::Converter version 2.142690' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html diff --git a/Makefile.SH b/Makefile.SH index 81023f0..7b1fd5b 100755 --- a/Makefile.SH +++ b/Makefile.SH @@ -1322,11 +1322,12 @@ _cleaner2: -rmdir lib/Exporter lib/Encode/Unicode lib/Encode/MIME/Header -rmdir lib/Encode/MIME lib/Encode/KR lib/Encode/JP lib/Encode/CN -rmdir lib/Encode lib/Digest lib/Devel lib/Data lib/Config/Perl - -rmdir lib/Compress/Raw lib/Compress lib/Carp lib/CPAN/Meta - -rmdir lib/CPAN/LWP lib/CPAN/Kwalify lib/CPAN/HTTP lib/CPAN/FTP - -rmdir lib/CPAN/Exception lib/CPAN/API lib/CPAN lib/Attribute - -rmdir lib/Archive/Tar lib/Archive lib/App/Prove/State/Result - -rmdir lib/App/Prove/State lib/App/Prove lib/App + -rmdir lib/Compress/Raw lib/Compress lib/Carp lib/CPAN/Meta/History + -rmdir lib/CPAN/Meta lib/CPAN/LWP lib/CPAN/Kwalify lib/CPAN/HTTP + -rmdir lib/CPAN/FTP lib/CPAN/Exception lib/CPAN/API lib/CPAN + -rmdir lib/Attribute lib/Archive/Tar lib/Archive + -rmdir lib/App/Prove/State/Result lib/App/Prove/State lib/App/Prove + -rmdir lib/App _realcleaner: @$(LDLIBPTH) $(MAKE) _cleaner1 CLEAN=distclean diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index efc45a6..b2aa4dc 100755 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -288,7 +288,7 @@ use File::Glob qw(:case); # Note: When updating CPAN-Meta the META.* files will need to be regenerated # perl -Icpan/CPAN-Meta/lib Porting/makemeta 'CPAN::Meta' => { - 'DISTRIBUTION' => 'DAGOLDEN/CPAN-Meta-2.142060.tar.gz', + 'DISTRIBUTION' => 'DAGOLDEN/CPAN-Meta-2.142690.tar.gz', 'FILES' => q[cpan/CPAN-Meta], 'EXCLUDED' => [ qw[t/00-report-prereqs.t], @@ -413,7 +413,7 @@ use File::Glob qw(:case); }, 'experimental' => { - 'DISTRIBUTION' => 'LEONT/experimental-0.010.tar.gz', + 'DISTRIBUTION' => 'LEONT/experimental-0.011.tar.gz', 'FILES' => q[cpan/experimental], 'EXCLUDED' => [ qr{^t/release-.*\.t}, @@ -596,7 +596,7 @@ use File::Glob qw(:case); }, 'HTTP::Tiny' => { - 'DISTRIBUTION' => 'DAGOLDEN/HTTP-Tiny-0.049.tar.gz', + 'DISTRIBUTION' => 'DAGOLDEN/HTTP-Tiny-0.050.tar.gz', 'FILES' => q[cpan/HTTP-Tiny], 'EXCLUDED' => [ 't/00-report-prereqs.t', diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta.pm b/cpan/CPAN-Meta/lib/CPAN/Meta.pm index 0c9048a..f2a8936 100644 --- a/cpan/CPAN-Meta/lib/CPAN/Meta.pm +++ b/cpan/CPAN-Meta/lib/CPAN/Meta.pm @@ -2,8 +2,8 @@ use 5.006; use strict; use warnings; package CPAN::Meta; -our $VERSION = '2.142060'; # VERSION - +# VERSION +$CPAN::Meta::VERSION = '2.142690'; #pod =head1 SYNOPSIS #pod #pod use v5.10; @@ -641,7 +641,7 @@ CPAN::Meta - the distribution metadata for a CPAN dist =head1 VERSION -version 2.142060 +version 2.142690 =head1 SYNOPSIS @@ -1020,6 +1020,8 @@ Ricardo Signes <[email protected]> =head1 CONTRIBUTORS +=for stopwords Ansgar Burchardt Avar Arnfjord Bjarmason Christopher J. Madsen Chuck Adams Cory G Watson Damyan Ivanov Eric Wilhelm Graham Knop Gregor Hermann Karen Etheridge Kenichi Ishigaki Ken Will ... [132 chars truncated] + =over 4 =item * @@ -1052,6 +1054,10 @@ Eric Wilhelm <[email protected]> =item * +Graham Knop <[email protected]> + +=item * + Gregor Hermann <[email protected]> =item * @@ -1060,11 +1066,11 @@ Karen Etheridge <[email protected]> =item * -Ken Williams <[email protected]> +Kenichi Ishigaki <[email protected]> =item * -Kenichi Ishigaki <[email protected]> +Ken Williams <[email protected]> =item * @@ -1076,6 +1082,10 @@ Leon Timmermans <[email protected]> =item * +majensen <[email protected]> + +=item * + Mark Fowler <[email protected]> =item * @@ -1088,19 +1098,19 @@ Michael G. Schwern <[email protected]> =item * -Olaf Alders <[email protected]> +moznion <[email protected]> =item * -Olivier Mengue <[email protected]> +Olaf Alders <[email protected]> =item * -Randy Sims <[email protected]> +Olivier Mengue <[email protected]> =item * -moznion <[email protected]> +Randy Sims <[email protected]> =back diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm b/cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm index 83b6c59..1a92af4 100644 --- a/cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/Converter.pm @@ -2,8 +2,8 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Converter; -our $VERSION = '2.142060'; # VERSION - +# VERSION +$CPAN::Meta::Converter::VERSION = '2.142690'; #pod =head1 SYNOPSIS #pod #pod my $struct = decode_json_file('META.json'); @@ -24,9 +24,24 @@ our $VERSION = '2.142060'; # VERSION use CPAN::Meta::Validator; use CPAN::Meta::Requirements; -use version 0.88 (); use Parse::CPAN::Meta 1.4400 (); +# To help ExtUtils::MakeMaker bootstrap CPAN::Meta::Requirements on perls +# before 5.10, we fall back to the EUMM bundled compatibility version module if +# that's the only thing available. This shouldn't ever happen in a normal CPAN +# install of CPAN::Meta::Requirements, as version.pm will be picked up from +# prereqs and be available at runtime. + +BEGIN { + eval "use version ()"; ## no critic + if ( my $err = $@ ) { + eval "use ExtUtils::MakeMaker::version" or die $err; ## no critic + } +} + +# Perl 5.10.0 didn't have "is_qv" in version.pm +*_is_qv = version->can('is_qv') ? sub { $_[0]->is_qv } : sub { exists $_[0]->{qv} }; + sub _dclone { my $ref = shift; @@ -363,7 +378,7 @@ sub _clean_version { # XXX check defined $v and not just $v because version objects leak memory # in boolean context -- dagolden, 2012-02-03 if ( defined $v ) { - return $v->is_qv ? $v->normal : $element; + return _is_qv($v) ? $v->normal : $element; } else { return 0; @@ -373,8 +388,8 @@ sub _clean_version { sub _bad_version_hook { my ($v) = @_; $v =~ s{[a-z]+$}{}; # strip trailing alphabetics - my $vobj = eval { version->parse($v) }; - return defined($vobj) ? $vobj : version->parse(0); # or give up + my $vobj = eval { version->new($v) }; + return defined($vobj) ? $vobj : version->new(0); # or give up } sub _version_map { @@ -1479,7 +1494,7 @@ CPAN::Meta::Converter - Convert CPAN distribution metadata structures =head1 VERSION -version 2.142060 +version 2.142690 =head1 SYNOPSIS diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm b/cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm index db4f1ce..35476cf 100644 --- a/cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/Feature.pm @@ -2,8 +2,8 @@ use 5.006; use strict; use warnings; package CPAN::Meta::Feature; -our $VERSION = '2.142060'; # VERSION - +# VERSION +$CPAN::Meta::Feature::VERSION = '2.142690'; use CPAN::Meta::Prereqs; #pod =head1 DESCRIPTION @@ -78,7 +78,7 @@ CPAN::Meta::Feature - an optional feature provided by a CPAN distribution =head1 VERSION -version 2.142060 +version 2.142690 =head1 DESCRIPTION diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/History.pm b/cpan/CPAN-Meta/lib/CPAN/Meta/History.pm index 9d6c660..abf14f1 100644 --- a/cpan/CPAN-Meta/lib/CPAN/Meta/History.pm +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/History.pm @@ -3,8 +3,8 @@ use 5.006; use strict; use warnings; package CPAN::Meta::History; -our $VERSION = '2.142060'; # VERSION - +# VERSION +$CPAN::Meta::History::VERSION = '2.142690'; 1; # ABSTRACT: history of CPAN Meta Spec changes @@ -21,7 +21,7 @@ CPAN::Meta::History - history of CPAN Meta Spec changes =head1 VERSION -version 2.142060 +version 2.142690 =head1 DESCRIPTION diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod new file mode 100644 index 0000000..2e9568a --- /dev/null +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_0.pod @@ -0,0 +1,185 @@ +=for :stopwords DOAP RDF + +=head1 NAME + +CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.0 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Conversion from the original HTML to POD format + +=back + +=head1 DESCRIPTION + +This document describes version 1.0 of the F<META.yml> specification. + +The META.yml file describes important properties of contributed Perl +distributions such as the ones found on L<CPAN|http://www.cpan.org>. It is +typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>. + +The fields in the F<META.yml> file are meant to be helpful to people +maintaining module collections (like CPAN), for people writing +installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to +know some stuff about a distribution before downloading it and starting to +install it. + +=head1 Format + +F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format. The +reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in +L<this thread|http://archive.develooper.com/[email protected]/msg00405.html> +on the MakeMaker mailing list. + +The first line of a F<META.yml> file should be a valid L<YAML document header|http://www.yaml.org/spec/#.Document> +like C<"--- #YAML:1.0"> + +=head1 Fields + +The rest of the META.yml file is one big YAML +L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->, +whose keys are described here. + +=over 4 + +=item name + +Example: C<Module-Build> + +The name of the distribution. Often created by taking the "main +module" in the distribution and changing "::" to "-". Sometimes it's +completely different, however, as in the case of the +L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution. + +=item version + +Example: C<0.16> + +The version of the distribution to which the META.yml file refers. + +=item license + +Example: C<perl> + +The license under which this distribution may be used and +redistributed. See L<Module::Build> for the list of valid options. + + +=item distribution_type + +Example: C<module> + +What kind of stuff is contained in this distribution. Most things on +CPAN are C<module>s (which can also mean a collection of +modules), but some things are C<script>s. + +=item requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution requires for proper +operation. The keys are the module names, and the values are version +specifications as described in the L<Module::Build|documentation for Module::Build's "requires" parameter>. + +I<Note: the exact nature of the fancy specifications like +C<< ">= 1.2, != 1.5, < 2.0" >> is subject to +change. Advance notice will be given here. The simple specifications +like C<"1.2"> will not change in format.> + +=item recommends + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution recommends for enhanced +operation. + +=item build_requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules required for building and/or testing of +this distribution. These dependencies are not required after the +module is installed. + +=item conflicts + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules that cannot be installed while this +distribution is installed. This is a pretty uncommon situation. + +=item dynamic_config + +Example: C<0> + +A boolean flag indicating whether a F<Build.PL> or +F<Makefile.PL> (or similar) must be executed, or whether this +module can be built, tested and installed solely from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently L<Module::Build> doesn't actually do anything with +this flag - it's probably going to be up to higher-level tools like +L<CPAN|CPAN.pm> to do something useful with it. It can potentially +bring lots of security, packaging, and convenience improvements. + +=item generated_by + +Example: C<Module::Build version 0.16> + +Indicates the tool that was used to create this F<META.yml> file. It's +good form to include both the name of the tool and its version, but +this field is essentially opaque, at least for the moment. + +=back + +=head1 Related Projects + +=over 4 + +=item DOAP + +An RDF vocabulary to describe software projects. L<http://usefulinc.com/doap>. + +=back + +=head1 History + +=over 4 + +=item * + +B<March 14, 2003> (Pi day) - created version 1.0 of this document. + +=item * + +B<May 8, 2003> - added the "dynamic_config" field, which was missing from the +initial version. + +=back diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod new file mode 100644 index 0000000..2e5866d --- /dev/null +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_1.pod @@ -0,0 +1,247 @@ +=for :stopwords Ingy READMEs WTF licensure + +=head1 NAME + +CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.1 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Conversion from the original HTML to POD format + +=back + +=head1 DESCRIPTION + +This document describes version 1.1 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed Perl +distributions such as the ones found on L<CPAN|http://www.cpan.org>. It is +typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>. + +The fields in the F<META.yml> file are meant to be helpful to people +maintaining module collections (like CPAN), for people writing +installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to +know some stuff about a distribution before downloading it and starting to +install it. + +=head1 Format + +F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format. The +reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in +L<this thread|http://archive.develooper.com/[email protected]/msg00405.html> +on the MakeMaker mailing list. + +The first line of a F<META.yml> file should be a valid L<YAML document header|http://www.yaml.org/spec/#.Document> +like C<"--- #YAML:1.0"> + +=head1 Fields + +The rest of the META.yml file is one big YAML +L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->, +whose keys are described here. + +=over 4 + +=item name + +Example: C<Module-Build> + +The name of the distribution. Often created by taking the "main +module" in the distribution and changing "::" to "-". Sometimes it's +completely different, however, as in the case of the +L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution. + +=item version + +Example: C<0.16> + +The version of the distribution to which the META.yml file refers. +This is a mandatory field. + +The version is essentially an arbitrary string, but I<must> be +only ASCII characters, and I<strongly should> be of the format +integer-dot-digit-digit, i.e. C<25.57>, optionally followed by +underscore-digit-digit, i.e. C<25.57_04>. + +The standard tools that deal with module distribution (PAUSE, CPAN, +etc.) form an identifier for each distribution by joining the 'name' +and 'version' attributes with a dash (C<->) character. Tools +who are prepared to deal with distributions that have no version +numbers generally omit the dash as well. + +=item license + +Example: C<perl> + +a descriptive term for the licenses ... not authoritative, but must +be consistent with licensure statements in the READMEs, documentation, etc. + +The license under which this distribution may be used and +redistributed. See L<Module::Build> +for the list of valid options. + +=item license_uri + +This should contain a URI where the exact terms of the license may be found. + +(change "unrestricted" to "redistributable"?) + +=item distribution_type + +Example: C<module> + +What kind of stuff is contained in this distribution. Most things on +CPAN are C<module>s (which can also mean a collection of +modules), but some things are C<script>s. + +This field is basically meaningless, and tools (like Module::Build or +MakeMaker) will likely stop generating it in the future. + +=item private + +WTF is going on here? + +index_ignore: any application that indexes the contents of +distributions (PAUSE, search.cpan.org) ought to ignore the items +(packages, files, directories, namespace hierarchies). + +=item requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution requires for proper +operation. The keys are the module names, and the values are version +specifications as described in the L<Module::Build|documentation for Module::Build's "requires" parameter>. + +I<Note: the exact nature of the fancy specifications like +C<< ">= 1.2, != 1.5, < 2.0" >> is subject to +change. Advance notice will be given here. The simple specifications +like C<"1.2"> will not change in format.> + +=item recommends + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules this distribution recommends for enhanced +operation. + +=item build_requires + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules required for building and/or testing of +this distribution. These dependencies are not required after the +module is installed. + +=item conflicts + +Example: + + Data::Dumper: 0 + File::Find: 1.03 + +A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping-> +indicating the Perl modules that cannot be installed while this +distribution is installed. This is a pretty uncommon situation. + +- possibly separate out test-time prereqs, complications include: can +tests be meaningfully preserved for later running? are test-time +prereqs in addition to build-time, or exclusive? + +- make official location for installed *distributions*, which can +contain tests, etc. + +=item dynamic_config + +Example: C<0> + +A boolean flag indicating whether a F<Build.PL> or +F<Makefile.PL> (or similar) must be executed, or whether this +module can be built, tested and installed solely from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently L<Module::Build> doesn't actually do anything with +this flag - it's probably going to be up to higher-level tools like +L<CPAN|CPAN.pm> to do something useful with it. It can potentially +bring lots of security, packaging, and convenience improvements. + +=item generated_by + +Example: C<Module::Build version 0.16> + +Indicates the tool that was used to create this F<META.yml> file. It's +good form to include both the name of the tool and its version, but +this field is essentially opaque, at least for the moment. + +=back + +=head2 Ingy's suggestions + +=over 4 + +=item short_description + +add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters + +=item description + +long version of abstract, should add? + +=item maturity + +alpha, beta, gamma, mature, stable + +=item author_id, owner_id + +=item categorization, keyword, chapter_id + +=item URL for further information + +could default to search.cpan.org on PAUSE + +=item namespaces + +can be specified for single elements by prepending +dotted-form, i.e. "com.example.my_application.my_property". Default +namespace for META.yml is probably "org.cpan.meta_author" or +something. Precedent for this is Apple's Carbon namespaces, I think. + +=back + +=head1 History + +=over 4 + +=item * + +B<March 14, 2003> (Pi day) - created version 1.0 of this document. + +=item * + +B<May 8, 2003> - added the "dynamic_config" field, which was missing from the +initial version. + +=back diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod new file mode 100644 index 0000000..b0d6cf40 --- /dev/null +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_2.pod @@ -0,0 +1,658 @@ +=for :stopwords MailingList RWS subcontext + +=head1 NAME + +CPAN::Meta::History::Meta_1_2 - Version 1.2 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.2 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Various spelling corrections + +=back + +=head1 SYNOPSIS + + --- #YAML:1.0 + name: Module-Build + abstract: Build and install Perl modules + version: 0.20 + author: + - Ken Williams <[email protected]> + license: perl + distribution_type: module + requires: + Config: 0 + Cwd: 0 + Data::Dumper: 0 + ExtUtils::Install: 0 + File::Basename: 0 + File::Compare: 0 + File::Copy: 0 + File::Find: 0 + File::Path: 0 + File::Spec: 0 + IO::File: 0 + perl: 5.005_03 + recommends: + Archive::Tar: 1.00 + ExtUtils::Install: 0.3 + ExtUtils::ParseXS: 2.02 + Pod::Text: 0 + YAML: 0.35 + build_requires: + Test: 0 + urls: + license: http://dev.perl.org/licenses/ + meta-spec: + version: 1.2 + url: http://module-build.sourceforge.net/META-spec-v1.2.html + generated_by: Module::Build version 0.20 + +=head1 DESCRIPTION + +This document describes version 1.2 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed +Perl distributions such as the ones found on CPAN. It is typically +created by tools like Module::Build, Module::Install, and +ExtUtils::MakeMaker. + +The fields in the F<META.yml> file are meant to be helpful for people +maintaining module collections (like CPAN), for people writing +installation tools (like CPAN.pm or CPANPLUS), or just for people who +want to know some stuff about a distribution before downloading it and +starting to install it. + +I<Note: The latest stable version of this specification can always be +found at L<http://module-build.sourceforge.net/META-spec-current.html>, +and the latest development version (which may include things that +won't make it into the stable version can always be found at +L<http://module-build.sourceforge.net/META-spec-blead.html>.> + +=head1 FORMAT + +F<META.yml> files are written in the YAML format (see +L<http://www.yaml.org/>). + +See the following links to learn why we chose YAML instead of, say, +XML or Data::Dumper: + +=over 4 + +=item * + +Module::Build design plans + +L<http://nntp.x.perl.org/group/perl.makemaker/406> + +=item * + +Not keen on YAML + +L<http://nntp.x.perl.org/group/perl.module-authors/1353> + +=item * + +META Concerns + +L<http://nntp.x.perl.org/group/perl.module-authors/1385> + +=back + +=head1 TERMINOLOGY + +=over 4 + +=item distribution + +This is the primary object described by the F<META.yml> +specification. In the context of this document it usually refers to a +collection of modules, scripts, and/or documents that are distributed +for other developers to use. + +=item module + +This refers to a reusable library of code typically contained in a +single file. Currently, we primarily talk of perl modules, but this +specification should be open enough to apply to other languages as +well (ex. python, ruby). + +=back + +=head1 VERSION SPECIFICATIONS + +Some fields require a version specification (ex. L<"requires">, +L<"recommends">, L<"build_requires">, etc.). This section details the +version specifications that are currently supported. + +If a single version is listed, then that version is considered to be +the minimum version supported. + +If 0 is given as the version number, then any version is supported. + +Additionally, for more complicated requirements, the specification +supports a list of versions, each of which may be optionally preceded +by a relational operator. + +Supported operators include E<lt> (less than), E<lt>= (less than or +equal), E<gt> (greater than), E<gt>= (greater than or equal), == (equal), and != +(not equal). + +If a list is given then it is evaluated from left to right so that any +specifications in the list that conflict with a previous specification +are overridden by the later. + +Examples: + + >= 1.2, != 1.5, < 2.0 + +Any version from version 1.2 onward, except version 1.5, that also +precedes version 2.0. + +=head1 HEADER + +The first line of a F<META.yml> file should be a valid YAML document +header like C<"--- #YAML:1.0">. + +=head1 FIELDS + +The rest of the F<META.yml> file is one big YAML mapping whose keys +are described here. + +=head2 meta-spec + +Example: + + meta-spec: + version: 1.2 + url: http://module-build.sourceforge.net/META-spec-v1.2.html + +(Spec 1.1) [required] {URL} This field indicates the location of the +version of the META.yml specification used. + +=head2 name + +Example: + + name: Module-Build + +(Spec 1.0) [required] {string} The name of the distribution which is often +created by taking the "main module" in the distribution and changing +"::" to "-". Sometimes it's completely different, however, as in the +case of the libwww-perl distribution (see +L<http://search.cpan.org/author/GAAS/libwww-perl/>). + +=head2 version + +Example: + + version: 0.20 + +(Spec 1.0) [required] {version} The version of the distribution to which the +F<META.yml> file refers. + +=head2 abstract + +Example: + + abstract: Build and install Perl modules. + +(Spec 1.1) [required] {string} A short description of the purpose of the +distribution. + +=head2 author + +Example: + + author: + - Ken Williams <[email protected]> + +(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the +distribution. The preferred form is author-name <email-address>. + +=head2 license + +Example: + + license: perl + +(Spec 1.0) [required] {string} The license under which this distribution may be +used and redistributed. See L<Module::Build> for the list of valid +options. + +=head2 distribution_type + +Example: + + distribution_type: module + +(Spec 1.0) [optional] {string} What kind of stuff is contained in this +distribution. Most things on CPAN are C<module>s (which can also mean +a collection of modules), but some things are C<script>s. + +Unfortunately this field is basically meaningless, since many +distributions are hybrids of several kinds of things, or some new +thing, or subjectively different in focus depending on who's using +them. Tools like Module::Build and MakeMaker will likely stop +generating this field. + +=head2 requires + +Example: + + requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution requires for proper operation. The keys are the module +names, and the values are version specifications as described in +L<Module::Build> for the "requires" parameter. + +=head2 recommends + +Example: + + recommends: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution recommends for enhanced operation. + +I<ALTERNATIVE: It may be desirable to present to the user which +features depend on which modules so they can make an informed +decision about which recommended modules to install.> + +Example: + + optional_features: + - foo: + description: Provides the ability to blah. + requires: + Data::Dumper: 0 + File::Find: 1.03 + - bar: + description: This feature is not available on this platform. + excludes_os: MSWin32 + +I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features +which are made available when its requirements are met. For each +feature a description is provided along with any of L<"requires">, +L<"build_requires">, L<"conflicts">, L<"requires_packages">, +L<"requires_os">, and L<"excludes_os"> which have the same meaning in +this subcontext as described elsewhere in this document.> + +=head2 build_requires + +Example: + + build_requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +required for building and/or testing of this distribution. These +dependencies are not required after the module is installed. + +=head2 conflicts + +Example: + + conflicts: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that +cannot be installed while this distribution is installed. This is a +pretty uncommon situation. + +=head2 dynamic_config + +Example: + + dynamic_config: 0 + +(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> +or F<Makefile.PL> (or similar) must be executed when building this +distribution, or whether it can be built, tested and installed solely +from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently Module::Build doesn't actually do anything with this flag +- it's probably going to be up to higher-level tools like CPAN +to do something useful with it. It can potentially bring lots of +security, packaging, and convenience improvements. + +If this field is omitted, it defaults to 1 (true). + +=head2 private + +I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to +L</"no_index">. See below. + +=head2 provides + +Example: + + provides: + Foo::Bar: + file: lib/Foo/Bar.pm + version: 0.27_02 + Foo::Bar::Blah: + file: lib/Foo/Bar/Blah.pm + Foo::Bar::Baz: + file: lib/Foo/Bar/Baz.pm + version: 0.3 + +(Spec 1.1) [optional] {map} A YAML mapping that describes all packages +provided by this distribution. This information can be (and, in some +cases, is) used by distribution and automation mechanisms like PAUSE, +CPAN, and search.cpan.org to build indexes saying in which +distribution various packages can be found. + +When using tools like C<Module::Build> that can generate the +C<provides> mapping for your distribution automatically, make sure you +examine what it generates to make sure it makes sense - indexers will +usually trust the C<provides> field if it's present, rather than +scanning through the distribution files themselves to figure out +packages and versions. This is a good thing, because it means you can +use the C<provides> field to tell the indexers precisely what you want +indexed about your distribution, rather than relying on them to +essentially guess what you want indexed. + +=head2 no_index + +Example: + + no_index: + file: + - My/Module.pm + dir: + - My/Private + package: + - My::Module::Stuff + namespace: + - My::Module::Stuff + +(Spec 1.1) [optional] {map} A YAML mapping that describes any files, +directories, packages, and namespaces that are private +(i.e. implementation artifacts) that are not of interest to searching +and indexing tools. This is useful when no C<provides> field is +present. + +I<(Note: I'm not actually sure who looks at this field, or exactly +what they do with it. This spec could be off in some way from actual +usage.)> + +=head3 file + +(Spec 1.1) [optional] Exclude any listed file(s). + +=head3 dir + +(Spec 1.1) [optional] Exclude anything below the listed +directory(ies). + +=head3 package + +(Spec 1.1) [optional] Exclude the listed package(s). + +=head3 namespace + +(Spec 1.1) [optional] Excludes anything below the listed namespace(s), +but I<not> the listed namespace(s) its self. + +=head2 keywords + +Example: + + keywords: + - make + - build + - install + +(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe +this distribution. + +=head2 resources + +Example: + + resources: + license: http://dev.perl.org/licenses/ + homepage: http://sourceforge.net/projects/module-build + bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build + MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general + +(Spec 1.1) [optional] {map} A mapping of any URL resources related to +this distribution. All-lower-case keys, such as C<homepage>, +C<license>, and C<bugtracker>, are reserved by this specification, as +they have "official" meanings defined here in this specification. If +you'd like to add your own "special" entries (like the "MailingList" +entry above), use at least one upper-case letter. + +The current set of official keys is: + +=over 2 + +=item homepage + +The official home of this project on the web. + +=item license + +An URL for an official statement of this distribution's license. + +=item bugtracker + +An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. + +=back + + +=head2 generated_by + +Example: + + generated_by: Module::Build version 0.20 + +(Spec 1.0) [required] {string} Indicates the tool that was used to create this +F<META.yml> file. It's good form to include both the name of the tool +and its version, but this field is essentially opaque, at least for +the moment. If F<META.yml> was generated by hand, it is suggested that +the author be specified here. + +[Note: My F<meta_stats.pl> script which I use to gather statistics +regarding F<META.yml> usage prefers the form listed above, i.e. it +splits on /\s+version\s+/ taking the first field as the name of the +tool that generated the file and the second field as version of that +tool. RWS] + +=head1 SEE ALSO + +CPAN, L<http://www.cpan.org/> + +CPAN.pm, L<http://search.cpan.org/author/ANDK/CPAN/> + +CPANPLUS, L<http://search.cpan.org/author/KANE/CPANPLUS/> + +Data::Dumper, L<http://search.cpan.org/author/ILYAM/Data-Dumper/> + +ExtUtils::MakeMaker, L<http://search.cpan.org/author/MSCHWERN/ExtUtils-MakeMaker/> + +Module::Build, L<http://search.cpan.org/author/KWILLIAMS/Module-Build/> + +Module::Install, L<http://search.cpan.org/author/KWILLIAMS/Module-Install/> + +XML, L<http://www.w3.org/XML/> + +YAML, L<http://www.yaml.org/> + +=head1 HISTORY + +=over 4 + +=item March 14, 2003 (Pi day) + +=over 2 + +=item * + +Created version 1.0 of this document. + +=back + +=item May 8, 2003 + +=over 2 + +=item * + +Added the L</"dynamic_config"> field, which was missing from the initial +version. + +=back + +=item November 13, 2003 + +=over 2 + +=item * + +Added more YAML rationale articles. + +=item * + +Fixed existing link to YAML discussion thread to point to new +L<http://nntp.x.perl.org/group/> site. + +=item * + +Added and deprecated the L<"private"> field. + +=item * + +Added L<"abstract">, L<"configure">, L<"requires_packages">, +L<"requires_os">, L<"excludes_os">, and L<"no_index"> fields. + +=item * + +Bumped version. + +=back + +=item November 16, 2003 + +=over 2 + +=item * + +Added L<"generation">, L<"authored_by"> fields. + +=item * + +Add alternative proposal to the L<"recommends"> field. + +=item * + +Add proposal for a L<"requires_build_tools"> field. + +=back + +=item December 9, 2003 + +=over 2 + +=item * + +Added link to latest version of this specification on CPAN. + +=item * + +Added section L<"VERSION SPECIFICATIONS">. + +=item * + +Chang name from Module::Build::META-spec to CPAN::META::Specification. + +=item * + +Add proposal for L<"auto_regenerate"> field. + +=back + +=item December 15, 2003 + +=over 2 + +=item * + +Add L<"index"> field as a compliment to L<"no_index"> + +=item * + +Add L<"keywords"> field as a means to aid searching distributions. + +=item * + +Add L<"TERMINOLOGY"> section to explain certain terms that may be +ambiguous. + +=back + +=item July 26, 2005 + +=over 2 + +=item * + +Removed a bunch of items (generation, requires_build_tools, +requires_packages, configure, requires_os, excludes_os, +auto_regenerate) that have never actually been supported, but were +more like records of brainstorming. + +=item * + +Changed C<authored_by> to C<author>, since that's always been what +it's actually called in actual F<META.yml> files. + +=item * + +Added the "==" operator to the list of supported version-checking +operators. + +=item * + +Noted that the C<distribution_type> field is basically meaningless, +and shouldn't really be used. + +=item * + +Clarified C<dynamic_config> a bit. + +=back + +=item August 23, 2005 + +=over 2 + +=item * + +Removed the name C<CPAN::META::Specification>, since that implies a +module that doesn't actually exist. + +=back + +=back diff --git a/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod new file mode 100644 index 0000000..57bf7cf --- /dev/null +++ b/cpan/CPAN-Meta/lib/CPAN/Meta/History/Meta_1_3.pod @@ -0,0 +1,665 @@ +=for :stopwords MailingList PODs RWS subcontext + +=head1 NAME + +CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for META.yml + +=head1 PREFACE + +This is a historical copy of the version 1.3 specification for F<META.yml> +files, copyright by Ken Williams. + +Modifications from the original: + +=over + +=item * + +Various spelling corrections + +=back + +=head1 SYNOPSIS + + --- #YAML:1.0 + name: Module-Build + abstract: Build and install Perl modules + version: 0.20 + author: + - Ken Williams <[email protected]> + license: perl + distribution_type: module + requires: + Config: 0 + Cwd: 0 + Data::Dumper: 0 + ExtUtils::Install: 0 + File::Basename: 0 + File::Compare: 0 + File::Copy: 0 + File::Find: 0 + File::Path: 0 + File::Spec: 0 + IO::File: 0 + perl: 5.005_03 + recommends: + Archive::Tar: 1.00 + ExtUtils::Install: 0.3 + ExtUtils::ParseXS: 2.02 + Pod::Text: 0 + YAML: 0.35 + build_requires: + Test: 0 + urls: + license: http://dev.perl.org/licenses/ + meta-spec: + version: 1.3 + url: http://module-build.sourceforge.net/META-spec-v1.3.html + generated_by: Module::Build version 0.20 + +=head1 DESCRIPTION + +This document describes version 1.3 of the F<META.yml> specification. + +The F<META.yml> file describes important properties of contributed +Perl distributions such as the ones found on CPAN. It is typically +created by tools like Module::Build, Module::Install, and +ExtUtils::MakeMaker. + +The fields in the F<META.yml> file are meant to be helpful for people +maintaining module collections (like CPAN), for people writing +installation tools (like CPAN.pm or CPANPLUS), or just for people who +want to know some stuff about a distribution before downloading it and +starting to install it. + +I<Note: The latest stable version of this specification can always be +found at L<http://module-build.sourceforge.net/META-spec-current.html>, +and the latest development version (which may include things that +won't make it into the stable version) can always be found at +L<http://module-build.sourceforge.net/META-spec-blead.html>.> + +=head1 FORMAT + +F<META.yml> files are written in the YAML format (see +L<http://www.yaml.org/>). + +See the following links to learn why we chose YAML instead of, say, +XML or Data::Dumper: + +=over 4 + +=item Module::Build design plans + +L<http://nntp.x.perl.org/group/perl.makemaker/406> + +=item Not keen on YAML + +L<http://nntp.x.perl.org/group/perl.module-authors/1353> + +=item META Concerns + +L<http://nntp.x.perl.org/group/perl.module-authors/1385> + +=back + +=head1 TERMINOLOGY + +=over 4 + +=item distribution + +This is the primary object described by the F<META.yml> +specification. In the context of this document it usually refers to a +collection of modules, scripts, and/or documents that are distributed +together for other developers to use. Examples of distributions are +C<Class-Container>, C<libwww-perl>, or C<DBI>. + +=item module + +This refers to a reusable library of code typically contained in a +single file. Currently, we primarily talk of perl modules, but this +specification should be open enough to apply to other languages as +well (ex. python, ruby). Examples of modules are C<Class::Container>, +C<LWP::Simple>, or C<DBD::File>. + +=back + +=head1 HEADER + +The first line of a F<META.yml> file should be a valid YAML document +header like C<"--- #YAML:1.0">. + +=head1 FIELDS + +The rest of the F<META.yml> file is one big YAML mapping whose keys +are described here. + +=head2 meta-spec + +Example: + + meta-spec: + version: 1.3 + url: http://module-build.sourceforge.net/META-spec-v1.3.html + +(Spec 1.1) [required] {URL} This field indicates the location of the +version of the META.yml specification used. + +=head2 name + +Example: + + name: Module-Build + +(Spec 1.0) [required] {string} The name of the distribution which is often +created by taking the "main module" in the distribution and changing +"::" to "-". Sometimes it's completely different, however, as in the +case of the libwww-perl distribution (see +L<http://search.cpan.org/dist/libwww-perl/>). + +=head2 version + +Example: + + version: 0.20 + +(Spec 1.0) [required] {version} The version of the distribution to which the +F<META.yml> file refers. + +=head2 abstract + +Example: + + abstract: Build and install Perl modules. + +(Spec 1.1) [required] {string} A short description of the purpose of the +distribution. + +=head2 author + +Example: + + author: + - Ken Williams <[email protected]> + +(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the +distribution. The preferred form is author-name <email-address>. + +=head2 license + +Example: + + license: perl + +(Spec 1.0) [required] {string} The license under which this distribution may be +used and redistributed. See L<Module::Build> for the list of valid +options. + +=head2 distribution_type + +Example: + + distribution_type: module + +(Spec 1.0) [optional] {string} What kind of stuff is contained in this +distribution. Most things on CPAN are C<module>s (which can also mean +a collection of modules), but some things are C<script>s. + +Unfortunately this field is basically meaningless, since many +distributions are hybrids of several kinds of things, or some new +thing, or subjectively different in focus depending on who's using +them. Tools like Module::Build and MakeMaker will likely stop +generating this field. + +=head2 requires + +Example: + + requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution requires for proper operation. The keys are the module +names, and the values are version specifications as described in +L<VERSION SPECIFICATIONS>. + +=head2 recommends + +Example: + + recommends: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +this distribution recommends for enhanced operation. The keys are the +module names, and the values are version specifications as described +in L<VERSION SPECIFICATIONS>. + + + +I<ALTERNATIVE: It may be desirable to present to the user which +features depend on which modules so they can make an informed decision +about which recommended modules to install.> + +Example: + + optional_features: + - foo: + description: Provides the ability to blah. + requires: + Data::Dumper: 0 + File::Find: 1.03 + - bar: + description: This feature is not available on this platform. + excludes_os: MSWin32 + +I<(Spec 1.1) [optional] {map} A YAML sequence of names for optional features +which are made available when its requirements are met. For each +feature a description is provided along with any of L<"requires">, +L<"build_requires">, L<"conflicts">, L<"requires_packages">, +L<"requires_os">, and L<"excludes_os"> which have the same meaning in +this subcontext as described elsewhere in this document.> + +=head2 build_requires + +Example: + + build_requires: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +required for building and/or testing of this distribution. The keys +are the module names, and the values are version specifications as +described in L<VERSION SPECIFICATIONS>. These dependencies are not +required after the module is installed. + +=head2 conflicts + +Example: + + conflicts: + Data::Dumper: 0 + File::Find: 1.03 + +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that +cannot be installed while this distribution is installed. This is a +pretty uncommon situation. The keys for C<conflicts> are the module +names, and the values are version specifications as described in +L<VERSION SPECIFICATIONS>. + + +=head2 dynamic_config + +Example: + + dynamic_config: 0 + +(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a F<Build.PL> +or F<Makefile.PL> (or similar) must be executed when building this +distribution, or whether it can be built, tested and installed solely +from consulting its +metadata file. The main reason to set this to a true value is that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. + +Currently Module::Build doesn't actually do anything with this flag +- it's probably going to be up to higher-level tools like CPAN +to do something useful with it. It can potentially bring lots of +security, packaging, and convenience improvements. + +If this field is omitted, it defaults to 1 (true). + +=head2 private + +I<(Deprecated)> (Spec 1.0) [optional] {map} This field has been renamed to +L</"no_index">. See below. + +=head2 provides + +Example: + + provides: + Foo::Bar: + file: lib/Foo/Bar.pm + version: 0.27_02 + Foo::Bar::Blah: + file: lib/Foo/Bar/Blah.pm + Foo::Bar::Baz: + file: lib/Foo/Bar/Baz.pm + version: 0.3 + +(Spec 1.1) [optional] {map} A YAML mapping that describes all packages +provided by this distribution. This information can be (and, in some +cases, is) used by distribution and automation mechanisms like PAUSE, +CPAN, and search.cpan.org to build indexes saying in which +distribution various packages can be found. + +When using tools like C<Module::Build> that can generate the +C<provides> mapping for your distribution automatically, make sure you +examine what it generates to make sure it makes sense - indexers will +usually trust the C<provides> field if it's present, rather than +scanning through the distribution files themselves to figure out +packages and versions. This is a good thing, because it means you can +use the C<provides> field to tell the indexers precisely what you want +indexed about your distribution, rather than relying on them to +essentially guess what you want indexed. + +=head2 no_index + +Example: + + no_index: + file: + - My/Module.pm + directory: + - My/Private + package: + - My::Module::Stuff + namespace: + - My::Module::Stuff + +(Spec 1.1) [optional] {map} A YAML mapping that describes any files, +directories, packages, and namespaces that are private +(i.e. implementation artifacts) that are not of interest to searching +and indexing tools. This is useful when no C<provides> field is +present. + +For example, C<search.cpan.org> excludes items listed in C<no_index> +when searching for POD, meaning files in these directories will not +converted to HTML and made public - which is useful if you have +example or test PODs that you don't want the search engine to go +through. + +=head3 file + +(Spec 1.1) [optional] Exclude any listed file(s). + +=head3 directory + +(Spec 1.1) [optional] Exclude anything below the listed +directory(ies). + +[Note: previous editions of the spec had C<dir> instead of +C<directory>, but I think MakeMaker and various users started using +C<directory>, so in deference we switched to that.] + +=head3 package + +(Spec 1.1) [optional] Exclude the listed package(s). + +=head3 namespace + +(Spec 1.1) [optional] Excludes anything below the listed namespace(s), +but I<not> the listed namespace(s) its self. + +=head2 keywords + +Example: + + keywords: + - make + - build + - install + +(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe +this distribution. + +=head2 resources + +Example: + + resources: + license: http://dev.perl.org/licenses/ + homepage: http://sourceforge.net/projects/module-build + bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build + repository: http://sourceforge.net/cvs/?group_id=45731 + MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general + +(Spec 1.1) [optional] {map} A mapping of any URL resources related to +this distribution. All-lower-case keys, such as C<homepage>, +C<license>, and C<bugtracker>, are reserved by this specification, as +they have "official" meanings defined here in this specification. If +you'd like to add your own "special" entries (like the "MailingList" +entry above), use at least one upper-case letter. + +The current set of official keys is: + +=over 2 + +=item homepage + +The official home of this project on the web. + +=item license + +An URL for an official statement of this distribution's license. + +=item bugtracker + +An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. + +=back + + +=head2 generated_by + +Example: + + generated_by: Module::Build version 0.20 + +(Spec 1.0) [required] {string} Indicates the tool that was used to create this +F<META.yml> file. It's good form to include both the name of the tool +and its version, but this field is essentially opaque, at least for +the moment. If F<META.yml> was generated by hand, it is suggested that +the author be specified here. + +[Note: My F<meta_stats.pl> script which I use to gather statistics +regarding F<META.yml> usage prefers the form listed above, i.e. it +splits on /\s+version\s+/ taking the first field as the name of the +tool that generated the file and the second field as version of that +tool. RWS] + +=head1 VERSION SPECIFICATIONS + +Some fields require a version specification (ex. L<"requires">, +L<"recommends">, L<"build_requires">, etc.) to indicate the particular +versionZ<>(s) of some other module that may be required as a +prerequisite. This section details the version specification formats +that are currently supported. + +The simplest format for a version specification is just the version +number itself, e.g. C<2.4>. This means that B<at least> version 2.4 +must be present. To indicate that B<any> version of a prerequisite is +okay, even if the prerequisite doesn't define a version at all, use +the version C<0>. + +You may also use the operators E<lt> (less than), E<lt>= (less than or +equal), E<gt> (greater than), E<gt>= (greater than or equal), == +(equal), and != (not equal). For example, the specification C<E<lt> +2.0> means that any version of the prerequisite less than 2.0 is +suitable. + +For more complicated situations, version specifications may be AND-ed +together using commas. The specification C<E<gt>= 1.2, != 1.5, E<lt> +2.0> indicates a version that must be B<at least> 1.2, B<less than> +2.0, and B<not equal to> 1.5. + +=head1 SEE ALSO + +CPAN, L<http://www.cpan.org/> + +CPAN.pm, L<http://search.cpan.org/dist/CPAN/> + +CPANPLUS, L<http://search.cpan.org/dist/CPANPLUS/> + +Data::Dumper, L<http://search.cpan.org/dist/Data-Dumper/> + +ExtUtils::MakeMaker, L<http://search.cpan.org/dist/ExtUtils-MakeMaker/> + +Module::Build, L<http://search.cpan.org/dist/Module-Build/> + +Module::Install, L<http://search.cpan.org/dist/Module-Install/> + +XML, L<http://www.w3.org/XML/> + +YAML, L<http://www.yaml.org/> + +=head1 HISTORY + +=over 4 + +=item March 14, 2003 (Pi day) + +=over 2 + +=item * + +Created version 1.0 of this document. + +=back + +=item May 8, 2003 + +=over 2 + +=item * + +Added the L</"dynamic_config"> field, which was missing from the initial +version. + +=back + +=item November 13, 2003 + +=over 2 + +=item * + +Added more YAML rationale articles. + +=item * + +Fixed existing link to YAML discussion thread to point to new +L<http://nntp.x.perl.org/group/> site. + +=item * + +Added and deprecated the L<"private"> field. + +=item * + +Added L<"abstract">, L<"configure">, L<"requires_packages">, +L<"requires_os">, L<"excludes_os">, and L<"no_index"> fields. + +=item * + +Bumped version. + +=back + +=item November 16, 2003 + +=over 2 + +=item * + +Added L<"generation">, L<"authored_by"> fields. + +=item * + +Add alternative proposal to the L<"recommends"> field. + +=item * + +Add proposal for a L<"requires_build_tools"> field. + +=back + **** PATCH TRUNCATED AT 2000 LINES -- 1121 NOT SHOWN **** -- Perl5 Master Repository
