1=for :stopwords Ingy READMEs WTF licensure 2 3=head1 NAME 4 5CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml 6 7=head1 PREFACE 8 9This is a historical copy of the version 1.1 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.18 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.1 of the F<META.yml> specification. 36 37The F<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. 80This is a mandatory field. 81 82The version is essentially an arbitrary string, but I<must> be 83only ASCII characters, and I<strongly should> be of the format 84integer-dot-digit-digit, i.e. C<25.57>, optionally followed by 85underscore-digit-digit, i.e. C<25.57_04>. 86 87The standard tools that deal with module distribution (PAUSE, CPAN, 88etc.) form an identifier for each distribution by joining the 'name' 89and 'version' attributes with a dash (C<->) character. Tools 90who are prepared to deal with distributions that have no version 91numbers generally omit the dash as well. 92 93=item license 94 95Example: C<perl> 96 97a descriptive term for the licenses ... not authoritative, but must 98be consistent with licensure statements in the READMEs, documentation, etc. 99 100The license under which this distribution may be used and 101redistributed. 102 103Must be one of the following licenses: 104 105=over 4 106 107=item perl 108 109The distribution may be copied and redistributed under the same terms as perl 110itself (this is by far the most common licensing option for modules on CPAN). 111This is a dual license, in which the user may choose between either the GPL 112version 1 or the Artistic version 1 license. 113 114=item gpl 115 116The distribution is distributed under the terms of the GNU General Public 117License version 2 (L<http://opensource.org/licenses/GPL-2.0>). 118 119=item lgpl 120 121The distribution is distributed under the terms of the GNU Lesser General 122Public License version 2 (L<http://opensource.org/licenses/LGPL-2.1>). 123 124=item artistic 125 126The distribution is licensed under the Artistic License version 1, as specified 127by the Artistic file in the standard perl distribution 128(L<http://opensource.org/licenses/Artistic-Perl-1.0>). 129 130=item bsd 131 132The distribution is licensed under the BSD 3-Clause License 133(L<http://opensource.org/licenses/BSD-3-Clause>). 134 135=item open_source 136 137The distribution is licensed under some other Open Source Initiative-approved 138license listed at L<http://www.opensource.org/licenses/>. 139 140=item unrestricted 141 142The distribution is licensed under a license that is B<not> approved by 143L<www.opensource.org|http://www.opensource.org/> but that allows distribution 144without restrictions. 145 146=item restrictive 147 148The distribution may not be redistributed without special permission from the 149author and/or copyright holder. 150 151=back 152 153=item license_uri 154 155This should contain a URI where the exact terms of the license may be found. 156 157(change "unrestricted" to "redistributable"?) 158 159=item distribution_type 160 161Example: C<module> 162 163What kind of stuff is contained in this distribution. Most things on 164CPAN are C<module>s (which can also mean a collection of 165modules), but some things are C<script>s. 166 167This field is basically meaningless, and tools (like Module::Build or 168MakeMaker) will likely stop generating it in the future. 169 170=item private 171 172WTF is going on here? 173 174index_ignore: any application that indexes the contents of 175distributions (PAUSE, search.cpan.org) ought to ignore the items 176(packages, files, directories, namespace hierarchies). 177 178=item requires 179 180Example: 181 182 Data::Dumper: 0 183 File::Find: 1.03 184 185A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 186indicating the Perl modules this distribution requires for proper 187operation. The keys are the module names, and the values are version 188specifications as described in the 189L<documentation for Module::Build's "requires" parameter|Module::Build::API/requires>. 190 191I<Note: the exact nature of the fancy specifications like 192C<< ">= 1.2, != 1.5, < 2.0" >> is subject to 193change. Advance notice will be given here. The simple specifications 194like C<"1.2"> will not change in format.> 195 196=item recommends 197 198Example: 199 200 Data::Dumper: 0 201 File::Find: 1.03 202 203A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 204indicating the Perl modules this distribution recommends for enhanced 205operation. 206 207=item build_requires 208 209Example: 210 211 Data::Dumper: 0 212 File::Find: 1.03 213 214A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 215indicating the Perl modules required for building and/or testing of 216this distribution. These dependencies are not required after the 217module is installed. 218 219=item conflicts 220 221Example: 222 223 Data::Dumper: 0 224 File::Find: 1.03 225 226A YAML L<mapping|http://yaml.org/spec/history/2002-10-31.html#syntax-mapping> 227indicating the Perl modules that cannot be installed while this 228distribution is installed. This is a pretty uncommon situation. 229 230- possibly separate out test-time prereqs, complications include: can 231tests be meaningfully preserved for later running? are test-time 232prereqs in addition to build-time, or exclusive? 233 234- make official location for installed *distributions*, which can 235contain tests, etc. 236 237=item dynamic_config 238 239Example: C<0> 240 241A boolean flag indicating whether a F<Build.PL> or 242F<Makefile.PL> (or similar) must be executed, or whether this 243module can be built, tested and installed solely from consulting its 244metadata file. The main reason to set this to a true value if that 245your module performs some dynamic configuration (asking questions, 246sensing the environment, etc.) as part of its build/install process. 247 248Currently L<Module::Build> doesn't actually do anything with 249this flag - it's probably going to be up to higher-level tools like 250L<CPAN.pm|CPAN> to do something useful with it. It can potentially 251bring lots of security, packaging, and convenience improvements. 252 253=item generated_by 254 255Example: C<Module::Build version 0.16> 256 257Indicates the tool that was used to create this F<META.yml> file. It's 258good form to include both the name of the tool and its version, but 259this field is essentially opaque, at least for the moment. 260 261=back 262 263=head2 Ingy's suggestions 264 265=over 4 266 267=item short_description 268 269add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters 270 271=item description 272 273long version of abstract, should add? 274 275=item maturity 276 277alpha, beta, gamma, mature, stable 278 279=item author_id, owner_id 280 281=item categorization, keyword, chapter_id 282 283=item URL for further information 284 285could default to search.cpan.org on PAUSE 286 287=item namespaces 288 289can be specified for single elements by prepending 290dotted-form, i.e. "com.example.my_application.my_property". Default 291namespace for META.yml is probably "org.cpan.meta_author" or 292something. Precedent for this is Apple's Carbon namespaces, I think. 293 294=back 295 296=head1 History 297 298=over 4 299 300=item * 301 302B<March 14, 2003> (Pi day) - created version 1.0 of this document. 303 304=item * 305 306B<May 8, 2003> - added the "dynamic_config" field, which was missing from the 307initial version. 308 309=back 310