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