Update CPAN-Meta to CPAN release 2.150005
[perl.git] / cpan / CPAN-Meta / lib / CPAN / Meta / History / Meta_1_1.pod
1 =for :stopwords Ingy READMEs WTF licensure
2
3 =head1 NAME
4
5 CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for META.yml
6
7 =head1 PREFACE
8
9 This is a historical copy of the version 1.1 specification for F<META.yml>
10 files, copyright by Ken Williams and licensed under the same terms as Perl
11 itself.
12
13 Modifications from the original:
14
15 =over
16
17 =item *
18
19 Conversion from the original HTML to POD format
20
21 =item *
22
23 Include list of valid licenses from L<Module::Build> 0.18 rather than
24 linking to the module.
25
26 =back
27
28 =head1 DESCRIPTION
29
30 This document describes version 1.1 of the F<META.yml> specification.
31
32 The F<META.yml> file describes important properties of contributed Perl
33 distributions such as the ones found on L<CPAN|http://www.cpan.org>.  It is
34 typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>.
35
36 The fields in the F<META.yml> file are meant to be helpful to people
37 maintaining module collections (like CPAN), for people writing
38 installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to
39 know some stuff about a distribution before downloading it and starting to
40 install it.
41
42 =head1 Format
43
44 F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format.  The
45 reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in
46 L<this thread|http://archive.develooper.com/makemaker@perl.org/msg00405.html>
47 on the MakeMaker mailing list.
48
49 The first line of a F<META.yml> file should be a valid L<YAML document header|http://www.yaml.org/spec/#.Document>
50 like C<"--- #YAML:1.0">
51
52 =head1 Fields
53
54 The rest of the META.yml file is one big YAML
55 L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->,
56 whose keys are described here.
57
58 =over 4
59
60 =item name
61
62 Example: C<Module-Build>
63
64 The name of the distribution.  Often created by taking the "main
65 module" in the distribution and changing "::" to "-".  Sometimes it's
66 completely different, however, as in the case of the
67 L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution.
68
69 =item version
70
71 Example: C<0.16>
72
73 The version of the distribution to which the META.yml file refers.
74 This is a mandatory field.
75
76 The version is essentially an arbitrary string, but I<must> be
77 only ASCII characters, and I<strongly should> be of the format
78 integer-dot-digit-digit, i.e. C<25.57>, optionally followed by
79 underscore-digit-digit, i.e. C<25.57_04>.
80
81 The standard tools that deal with module distribution (PAUSE, CPAN,
82 etc.) form an identifier for each distribution by joining the 'name'
83 and 'version' attributes with a dash (C<->) character.  Tools
84 who are prepared to deal with distributions that have no version
85 numbers generally omit the dash as well.
86
87 =item license
88
89 Example: C<perl>
90
91 a descriptive term for the licenses ... not authoritative, but must
92 be consistent with licensure statements in the READMEs, documentation, etc.
93
94 The license under which this distribution may be used and
95 redistributed.
96
97 Must be one of the following licenses:
98
99 =over 4
100
101 =item perl
102
103 The distribution may be copied and redistributed under the same terms as perl
104 itself (this is by far the most common licensing option for modules on CPAN).
105 This is a dual license, in which the user may choose between either the GPL or
106 the Artistic license.
107
108 =item gpl
109
110 The distribution is distributed under the terms of the Gnu General Public
111 License (L<http://www.opensource.org/licenses/gpl-license.php>).
112
113 =item lgpl
114
115 The distribution is distributed under the terms of the Gnu Lesser General
116 Public License (L<http://www.opensource.org/licenses/lgpl-license.php>).
117
118 =item artistic
119
120 The distribution is licensed under the Artistic License, as specified by the
121 Artistic file in the standard perl distribution.
122
123 =item bsd
124
125 The distribution is licensed under the BSD License
126 (L<http://www.opensource.org/licenses/bsd-license.php>).
127
128 =item open_source
129
130 The distribution is licensed under some other Open Source Initiative-approved
131 license listed at L<http://www.opensource.org/licenses/>.
132
133 =item unrestricted
134
135 The distribution is licensed under a license that is B<not> approved by
136 L<www.opensource.org|http://www.opensource.org> but that allows distribution
137 without restrictions.
138
139 =item restrictive
140
141 The distribution may not be redistributed without special permission from the
142 author and/or copyright holder.
143
144 =back
145
146 =item license_uri
147
148 This should contain a URI where the exact terms of the license may be found.
149
150 (change "unrestricted" to "redistributable"?)
151
152 =item distribution_type
153
154 Example: C<module>
155
156 What kind of stuff is contained in this distribution.  Most things on
157 CPAN are C<module>s (which can also mean a collection of
158 modules), but some things are C<script>s.
159
160 This field is basically meaningless, and tools (like Module::Build or
161 MakeMaker) will likely stop generating it in the future.
162
163 =item private
164
165 WTF is going on here?
166
167 index_ignore: any application that indexes the contents of
168 distributions (PAUSE, search.cpan.org) ought to ignore the items
169 (packages, files, directories, namespace hierarchies).
170
171 =item requires
172
173 Example:
174
175   Data::Dumper: 0
176   File::Find: 1.03
177
178 A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
179 indicating the Perl modules this distribution requires for proper
180 operation.  The keys are the module names, and the values are version
181 specifications as described in the L<Module::Build|documentation for Module::Build's "requires" parameter>.
182
183 I<Note: the exact nature of the fancy specifications like
184 C<< ">= 1.2, != 1.5, < 2.0" >> is subject to
185 change.  Advance notice will be given here.  The simple specifications
186 like C<"1.2"> will not change in format.>
187
188 =item recommends
189
190 Example:
191
192   Data::Dumper: 0
193   File::Find: 1.03
194
195 A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
196 indicating the Perl modules this distribution recommends for enhanced
197 operation.
198
199 =item build_requires
200
201 Example:
202
203   Data::Dumper: 0
204   File::Find: 1.03
205
206 A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
207 indicating the Perl modules required for building and/or testing of
208 this distribution.  These dependencies are not required after the
209 module is installed.
210
211 =item conflicts
212
213 Example:
214
215   Data::Dumper: 0
216   File::Find: 1.03
217
218 A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
219 indicating the Perl modules that cannot be installed while this
220 distribution is installed.  This is a pretty uncommon situation.
221
222 - possibly separate out test-time prereqs, complications include: can
223 tests be meaningfully preserved for later running?  are test-time
224 prereqs in addition to build-time, or exclusive?
225
226 - make official location for installed *distributions*, which can
227 contain tests, etc.
228
229 =item dynamic_config
230
231 Example: C<0>
232
233 A boolean flag indicating whether a F<Build.PL> or
234 F<Makefile.PL> (or similar) must be executed, or whether this
235 module can be built, tested and installed solely from consulting its
236 metadata file.  The main reason to set this to a true value if that
237 your module performs some dynamic configuration (asking questions,
238 sensing the environment, etc.) as part of its build/install process.
239
240 Currently L<Module::Build> doesn't actually do anything with
241 this flag - it's probably going to be up to higher-level tools like
242 L<CPAN|CPAN.pm> to do something useful with it.  It can potentially
243 bring lots of security, packaging, and convenience improvements.
244
245 =item generated_by
246
247 Example: C<Module::Build version 0.16>
248
249 Indicates the tool that was used to create this F<META.yml> file.  It's
250 good form to include both the name of the tool and its version, but
251 this field is essentially opaque, at least for the moment.
252
253 =back
254
255 =head2 Ingy's suggestions
256
257 =over 4
258
259 =item short_description
260
261 add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters
262
263 =item description
264
265 long version of abstract, should add?
266
267 =item maturity
268
269 alpha, beta, gamma, mature, stable
270
271 =item author_id, owner_id
272
273 =item categorization, keyword, chapter_id
274
275 =item URL for further information
276
277 could default to search.cpan.org on PAUSE
278
279 =item namespaces
280
281 can be specified for single elements by prepending
282 dotted-form, i.e. "com.example.my_application.my_property".  Default
283 namespace for META.yml is probably "org.cpan.meta_author" or
284 something.  Precedent for this is Apple's Carbon namespaces, I think.
285
286 =back
287
288 =head1 History
289
290 =over 4
291
292 =item *
293
294 B<March 14, 2003> (Pi day) - created version 1.0 of this document.
295
296 =item *
297
298 B<May 8, 2003> - added the "dynamic_config" field, which was missing from the
299 initial version.
300
301 =back