1CPAN::Meta::History::MeUtsae_r1_C1o(n3t)ributed Perl DocCuPmAeNn:t:aMteitoan::History::Meta_1_1(3)
2
3
4

NAME

6       CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for
7       META.yml
8

PREFACE

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
14       Modifications from the original:
15
16       •   Conversion from the original HTML to POD format
17
18       •   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
22       •   Fixed some dead links to point to active resources.
23

DESCRIPTION

25       This document describes version 1.1 of the META.yml specification.
26
27       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
32       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

Format

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
45       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

Fields

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
54       name
55           Example: "Module-Build"
56
57           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
63       version
64           Example: 0.16
65
66           The version of the distribution to which the META.yml file refers.
67           This is a mandatory field.
68
69           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
74           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
80       license
81           Example: "perl"
82
83           a descriptive term for the licenses ... not authoritative, but must
84           be consistent with licensure statements in the READMEs,
85           documentation, etc.
86
87           The license under which this distribution may be used and
88           redistributed.
89
90           Must be one of the following licenses:
91
92           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
99           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
103           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
108           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
114           bsd The distribution is licensed under the BSD 3-Clause License
115               (<http://opensource.org/licenses/BSD-3-Clause>).
116
117           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
122           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
127           restrictive
128               The distribution may not be redistributed without special
129               permission from the author and/or copyright holder.
130
131       license_uri
132           This should contain a URI where the exact terms of the license may
133           be found.
134
135           (change "unrestricted" to "redistributable"?)
136
137       distribution_type
138           Example: "module"
139
140           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
144           This field is basically meaningless, and tools (like Module::Build
145           or MakeMaker) will likely stop generating it in the future.
146
147       private
148           WTF is going on here?
149
150           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
154       requires
155           Example:
156
157             Data::Dumper: 0
158             File::Find: 1.03
159
160           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
167           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
172       recommends
173           Example:
174
175             Data::Dumper: 0
176             File::Find: 1.03
177
178           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
183       build_requires
184           Example:
185
186             Data::Dumper: 0
187             File::Find: 1.03
188
189           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
195       conflicts
196           Example:
197
198             Data::Dumper: 0
199             File::Find: 1.03
200
201           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
206           - 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
210           - make official location for installed *distributions*, which can
211           contain tests, etc.
212
213       dynamic_config
214           Example: 0
215
216           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
223           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
228       generated_by
229           Example: "Module::Build version 0.16"
230
231           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
236   Ingy's suggestions
237       short_description
238           add as field, containing abstract, maximum 80 characters, suggested
239           minimum 40 characters
240
241       description
242           long version of abstract, should add?
243
244       maturity
245           alpha, beta, gamma, mature, stable
246
247       author_id, owner_id
248       categorization, keyword, chapter_id
249       URL for further information
250           could default to search.cpan.org on PAUSE
251
252       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

History

259March 14, 2003 (Pi day) - created version 1.0 of this document.
260
261May 8, 2003 - added the "dynamic_config" field, which was missing
262           from the initial version.
263
264
265
266perl v5.38.0                      2023-07-20  CPAN::Meta::History::Meta_1_1(3)
Impressum