1=for :stopwords DOAP RDF 2 3=head1 NAME 4 5CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for META.yml 6 7=head1 PREFACE 8 9This is a historical copy of the version 1.0 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 19Conversion from the original HTML to POD format 20 21=item * 22 23Include list of valid licenses from L<Module::Build> 0.17 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 DESCRIPTION 34 35This document describes version 1.0 of the F<META.yml> specification. 36 37The META.yml file describes important properties of contributed Perl 38distributions such as the ones found on L<CPAN|http://www.cpan.org>. It is 39typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>. 40 41The fields in the F<META.yml> file are meant to be helpful to people 42maintaining module collections (like CPAN), for people writing 43installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to 44know some stuff about a distribution before downloading it and starting to 45install it. 46 47=head1 Format 48 49F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format. The 50reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in 51L<this thread|http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg406.html> 52on the MakeMaker mailing list. 53 54The first line of a F<META.yml> file should be a valid 55L<YAML document header|http://yaml.org/spec/history/2002-10-31.html#syntax-document> 56like C<"--- #YAML:1.0"> 57 58=head1 Fields 59 60The rest of the META.yml file is one big YAML 61L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>, 62whose keys are described here. 63 64=over 4 65 66=item name 67 68Example: C<Module-Build> 69 70The name of the distribution. Often created by taking the "main 71module" in the distribution and changing "::" to "-". Sometimes it's 72completely different, however, as in the case of the 73L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution. 74 75=item version 76 77Example: C<0.16> 78 79The version of the distribution to which the META.yml file refers. 80 81=item license 82 83Example: C<perl> 84 85The license under which this distribution may be used and 86redistributed. 87 88Must be one of the following licenses: 89 90=over 4 91 92=item perl 93 94The distribution may be copied and redistributed under the same terms as perl 95itself (this is by far the most common licensing option for modules on CPAN). 96This is a dual license, in which the user may choose between either the GPL 97version 1 or the Artistic version 1 license. 98 99=item gpl 100 101The distribution is distributed under the terms of the GNU General Public 102License version 2 (L<http://opensource.org/licenses/GPL-2.0>). 103 104=item lgpl 105 106The distribution is distributed under the terms of the GNU Lesser General 107Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>). 108 109=item artistic 110 111The distribution is licensed under the Artistic License version 1, as specified 112by the Artistic file in the standard perl distribution 113(L<http://opensource.org/licenses/Artistic-Perl-1.0>). 114 115=item bsd 116 117The distribution is licensed under the BSD 3-Clause License 118(L<http://opensource.org/licenses/BSD-3-Clause>). 119 120=item open_source 121 122The distribution is licensed under some other Open Source Initiative-approved 123license listed at L<http://www.opensource.org/licenses/>. 124 125=item unrestricted 126 127The distribution is licensed under a license that is B<not> approved by 128L<www.opensource.org|http://www.opensource.org/> but that allows distribution 129without restrictions. 130 131=item restrictive 132 133The distribution may not be redistributed without special permission from the 134author and/or copyright holder. 135 136=back 137 138=item distribution_type 139 140Example: C<module> 141 142What kind of stuff is contained in this distribution. Most things on 143CPAN are C<module>s (which can also mean a collection of 144modules), but some things are C<script>s. 145 146=item requires 147 148Example: 149 150 Data::Dumper: 0 151 File::Find: 1.03 152 153A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 154indicating the Perl modules this distribution requires for proper 155operation. The keys are the module names, and the values are version 156specifications as described in the 157L<documentation for Module::Build's "requires" parameter|Module::Build::API/requires>. 158 159I<Note: the exact nature of the fancy specifications like 160C<< ">= 1.2, != 1.5, < 2.0" >> is subject to 161change. Advance notice will be given here. The simple specifications 162like C<"1.2"> will not change in format.> 163 164=item recommends 165 166Example: 167 168 Data::Dumper: 0 169 File::Find: 1.03 170 171A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 172indicating the Perl modules this distribution recommends for enhanced 173operation. 174 175=item build_requires 176 177Example: 178 179 Data::Dumper: 0 180 File::Find: 1.03 181 182A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 183indicating the Perl modules required for building and/or testing of 184this distribution. These dependencies are not required after the 185module is installed. 186 187=item conflicts 188 189Example: 190 191 Data::Dumper: 0 192 File::Find: 1.03 193 194A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 195indicating the Perl modules that cannot be installed while this 196distribution is installed. This is a pretty uncommon situation. 197 198=item dynamic_config 199 200Example: C<0> 201 202A boolean flag indicating whether a F<Build.PL> or 203F<Makefile.PL> (or similar) must be executed, or whether this 204module can be built, tested and installed solely from consulting its 205metadata file. The main reason to set this to a true value if that 206your module performs some dynamic configuration (asking questions, 207sensing the environment, etc.) as part of its build/install process. 208 209Currently L<Module::Build> doesn't actually do anything with 210this flag - it's probably going to be up to higher-level tools like 211L<CPAN.pm|CPAN> to do something useful with it. It can potentially 212bring lots of security, packaging, and convenience improvements. 213 214=item generated_by 215 216Example: C<Module::Build version 0.16> 217 218Indicates the tool that was used to create this F<META.yml> file. It's 219good form to include both the name of the tool and its version, but 220this field is essentially opaque, at least for the moment. 221 222=back 223 224=head1 Related Projects 225 226=over 4 227 228=item DOAP 229 230An RDF vocabulary to describe software projects. L<http://usefulinc.com/doap>. 231 232=back 233 234=head1 History 235 236=over 4 237 238=item * 239 240B<March 14, 2003> (Pi day) - created version 1.0 of this document. 241 242=item * 243 244B<May 8, 2003> - added the "dynamic_config" field, which was missing from the 245initial version. 246 247=back 248