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