CPAN::Meta::History::Meta_1_0(3pm)

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

NAME

6       CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for
7       META.yml
8

PREFACE

10       This is a historical copy of the version 1.0 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.17 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.0 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
68       license
69           Example: "perl"
70
71           The license under which this distribution may be used and
72           redistributed.
73
74           Must be one of the following licenses:
75
76           perl
77               The distribution may be copied and redistributed under the same
78               terms as perl itself (this is by far the most common licensing
79               option for modules on CPAN).  This is a dual license, in which
80               the user may choose between either the GPL version 1 or the
81               Artistic version 1 license.
82
83           gpl The distribution is distributed under the terms of the GNU
84               General Public License version 2
85               (<http://opensource.org/licenses/GPL-2.0>).
86
87           lgpl
88               The distribution is distributed under the terms of the GNU
89               Lesser General Public License version 2
90               (<http://opensource.org/licenses/LGPL-2.1>).
91
92           artistic
93               The distribution is licensed under the Artistic License version
94               1, as specified by the Artistic file in the standard perl
95               distribution
96               (<http://opensource.org/licenses/Artistic-Perl-1.0>).
97
98           bsd The distribution is licensed under the BSD 3-Clause License
99               (<http://opensource.org/licenses/BSD-3-Clause>).
100
101           open_source
102               The distribution is licensed under some other Open Source
103               Initiative-approved license listed at
104               <http://www.opensource.org/licenses/>.
105
106           unrestricted
107               The distribution is licensed under a license that is not
108               approved by www.opensource.org <http://www.opensource.org/> but
109               that allows distribution without restrictions.
110
111           restrictive
112               The distribution may not be redistributed without special
113               permission from the author and/or copyright holder.
114
115       distribution_type
116           Example: "module"
117
118           What kind of stuff is contained in this distribution.  Most things
119           on CPAN are "module"s (which can also mean a collection of
120           modules), but some things are "script"s.
121
122       requires
123           Example:
124
125             Data::Dumper: 0
126             File::Find: 1.03
127
128           A YAML mapping
129           <http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
130           indicating the Perl modules this distribution requires for proper
131           operation.  The keys are the module names, and the values are
132           version specifications as described in the documentation for
133           Module::Build's "requires" parameter.
134
135           Note: the exact nature of the fancy specifications like ">= 1.2, !=
136           1.5, < 2.0" is subject to change.  Advance notice will be given
137           here.  The simple specifications like "1.2" will not change in
138           format.
139
140       recommends
141           Example:
142
143             Data::Dumper: 0
144             File::Find: 1.03
145
146           A YAML mapping
147           <http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
148           indicating the Perl modules this distribution recommends for
149           enhanced operation.
150
151       build_requires
152           Example:
153
154             Data::Dumper: 0
155             File::Find: 1.03
156
157           A YAML mapping
158           <http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
159           indicating the Perl modules required for building and/or testing of
160           this distribution.  These dependencies are not required after the
161           module is installed.
162
163       conflicts
164           Example:
165
166             Data::Dumper: 0
167             File::Find: 1.03
168
169           A YAML mapping
170           <http://yaml.org/spec/history/2002-10-31.html#syntax-mapping>
171           indicating the Perl modules that cannot be installed while this
172           distribution is installed.  This is a pretty uncommon situation.
173
174       dynamic_config
175           Example: 0
176
177           A boolean flag indicating whether a Build.PL or Makefile.PL (or
178           similar) must be executed, or whether this module can be built,
179           tested and installed solely from consulting its metadata file.  The
180           main reason to set this to a true value if that your module
181           performs some dynamic configuration (asking questions, sensing the
182           environment, etc.) as part of its build/install process.
183
184           Currently Module::Build doesn't actually do anything with this flag
185           - it's probably going to be up to higher-level tools like CPAN.pm
186           to do something useful with it.  It can potentially bring lots of
187           security, packaging, and convenience improvements.
188
189       generated_by
190           Example: "Module::Build version 0.16"
191
192           Indicates the tool that was used to create this META.yml file.
193           It's good form to include both the name of the tool and its
194           version, but this field is essentially opaque, at least for the
195           moment.
196

Related Projects

198       DOAP
199           An RDF vocabulary to describe software projects.
200           <http://usefulinc.com/doap>.
201

History

203       •   March 14, 2003 (Pi day) - created version 1.0 of this document.
204
205       •   May 8, 2003 - added the "dynamic_config" field, which was missing
206           from the initial version.
207
208
209
210perl v5.36.0                      2023-01-20  CPAN::Meta::History::Meta_1_0(3)