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

NAME

6       CPAN::Meta::History::Meta_1_2 - Version 1.2 metadata specification for
7       META.yml
8

PREFACE

10       This is a historical copy of the version 1.2 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       •   Various spelling corrections
17
18       •   Include list of valid licenses from Module::Build 0.2611 rather
19           than 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

SYNOPSIS

25        --- #YAML:1.0
26        name: Module-Build
27        abstract: Build and install Perl modules
28        version: 0.20
29        author:
30          - Ken Williams <kwilliams@cpan.org>
31        license: perl
32        distribution_type: module
33        requires:
34          Config: 0
35          Cwd: 0
36          Data::Dumper: 0
37          ExtUtils::Install: 0
38          File::Basename: 0
39          File::Compare: 0
40          File::Copy: 0
41          File::Find: 0
42          File::Path: 0
43          File::Spec: 0
44          IO::File: 0
45          perl: 5.005_03
46        recommends:
47          Archive::Tar: 1.00
48          ExtUtils::Install: 0.3
49          ExtUtils::ParseXS: 2.02
50          Pod::Text: 0
51          YAML: 0.35
52        build_requires:
53          Test: 0
54        urls:
55          license: http://dev.perl.org/licenses/
56        meta-spec:
57          version: 1.2
58          url: http://module-build.sourceforge.net/META-spec-v1.2.html
59        generated_by: Module::Build version 0.20
60

DESCRIPTION

62       This document describes version 1.2 of the META.yml specification.
63
64       The META.yml file describes important properties of contributed Perl
65       distributions such as the ones found on CPAN.  It is typically created
66       by tools like Module::Build, Module::Install, and ExtUtils::MakeMaker.
67
68       The fields in the META.yml file are meant to be helpful for people
69       maintaining module collections (like CPAN), for people writing
70       installation tools (like CPAN.pm or CPANPLUS), or just for people who
71       want to know some stuff about a distribution before downloading it and
72       starting to install it.
73
74       Note: The latest stable version of this specification can always be
75       found at <http://module-build.sourceforge.net/META-spec-current.html>,
76       and the latest development version (which may include things that won't
77       make it into the stable version can always be found at
78       <http://module-build.sourceforge.net/META-spec-blead.html>.
79

FORMAT

81       META.yml files are written in the YAML format (see
82       <http://www.yaml.org/>).
83
84       See the following links to learn why we chose YAML instead of, say, XML
85       or Data::Dumper:
86
87       •   Module::Build design plans
88           <http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html>
89
90       •   Not keen on YAML <http://www.nntp.perl.org/group/perl.module-
91           authors/2003/11/msg1353.html>
92
93       •   META Concerns <http://www.nntp.perl.org/group/perl.module-
94           authors/2003/11/msg1385.html>
95

TERMINOLOGY

97       distribution
98           This is the primary object described by the META.yml specification.
99           In the context of this document it usually refers to a collection
100           of modules, scripts, and/or documents that are distributed for
101           other developers to use.
102
103       module
104           This refers to a reusable library of code typically contained in a
105           single file. Currently, we primarily talk of perl modules, but this
106           specification should be open enough to apply to other languages as
107           well (ex. python, ruby).
108

VERSION SPECIFICATIONS

110       Some fields require a version specification (ex. "requires",
111       "recommends", "build_requires", etc.).  This section details the
112       version specifications that are currently supported.
113
114       If a single version is listed, then that version is considered to be
115       the minimum version supported.
116
117       If 0 is given as the version number, then any version is supported.
118
119       Additionally, for more complicated requirements, the specification
120       supports a list of versions, each of which may be optionally preceded
121       by a relational operator.
122
123       Supported operators include < (less than), <= (less than or equal), >
124       (greater than), >= (greater than or equal), == (equal), and != (not
125       equal).
126
127       If a list is given then it is evaluated from left to right so that any
128       specifications in the list that conflict with a previous specification
129       are overridden by the later.
130
131       Examples:
132
133        >= 1.2, != 1.5, < 2.0
134
135       Any version from version 1.2 onward, except version 1.5, that also
136       precedes version 2.0.
137
139       The first line of a META.yml file should be a valid YAML document
140       header like "--- #YAML:1.0".
141

FIELDS

143       The rest of the META.yml file is one big YAML mapping whose keys are
144       described here.
145
146   meta-spec
147       Example:
148
149        meta-spec:
150          version: 1.2
151          url: http://module-build.sourceforge.net/META-spec-v1.2.html
152
153       (Spec 1.1) [required] {URL} This field indicates the location of the
154       version of the META.yml specification used.
155
156   name
157       Example:
158
159         name: Module-Build
160
161       (Spec 1.0) [required] {string} The name of the distribution which is
162       often created by taking the "main module" in the distribution and
163       changing "::" to "-".  Sometimes it's completely different, however, as
164       in the case of the libwww-perl distribution (see
165       <http://search.cpan.org/author/GAAS/libwww-perl/>).
166
167   version
168       Example:
169
170         version: 0.20
171
172       (Spec 1.0) [required] {version} The version of the distribution to
173       which the META.yml file refers.
174
175   abstract
176       Example:
177
178         abstract: Build and install Perl modules.
179
180       (Spec 1.1) [required] {string} A short description of the purpose of
181       the distribution.
182
183   author
184       Example:
185
186         author:
187           - Ken Williams <kwilliams@cpan.org>
188
189       (Spec 1.1) [required] {list of strings} A YAML sequence indicating the
190       author(s) of the distribution. The preferred form is author-name
191       <email-address>.
192
193   license
194       Example:
195
196         license: perl
197
198       (Spec 1.0) [required] {string} The license under which this
199       distribution may be used and redistributed.
200
201       Must be one of the following licenses:
202
203       perl
204           The distribution may be copied and redistributed under the same
205           terms as perl itself (this is by far the most common licensing
206           option for modules on CPAN).  This is a dual license, in which the
207           user may choose between either the GPL version 1 or the Artistic
208           version 1 license.
209
210       gpl The distribution is distributed under the terms of the GNU General
211           Public License version 2
212           (<http://opensource.org/licenses/GPL-2.0>).
213
214       lgpl
215           The distribution is distributed under the terms of the GNU Lesser
216           General Public License version 2
217           (<http://opensource.org/licenses/LGPL-2.1>).
218
219       artistic
220           The distribution is licensed under the Artistic License version 1,
221           as specified by the Artistic file in the standard perl distribution
222           (<http://opensource.org/licenses/Artistic-Perl-1.0>).
223
224       bsd The distribution is licensed under the BSD 3-Clause License
225           (<http://opensource.org/licenses/BSD-3-Clause>).
226
227       open_source
228           The distribution is licensed under some other Open Source
229           Initiative-approved license listed at
230           <http://www.opensource.org/licenses/>.
231
232       unrestricted
233           The distribution is licensed under a license that is not approved
234           by www.opensource.org <http://www.opensource.org/> but that allows
235           distribution without restrictions.
236
237       restrictive
238           The distribution may not be redistributed without special
239           permission from the author and/or copyright holder.
240
241   distribution_type
242       Example:
243
244         distribution_type: module
245
246       (Spec 1.0) [optional] {string} What kind of stuff is contained in this
247       distribution.  Most things on CPAN are "module"s (which can also mean a
248       collection of modules), but some things are "script"s.
249
250       Unfortunately this field is basically meaningless, since many
251       distributions are hybrids of several kinds of things, or some new
252       thing, or subjectively different in focus depending on who's using
253       them.  Tools like Module::Build and MakeMaker will likely stop
254       generating this field.
255
256   requires
257       Example:
258
259         requires:
260           Data::Dumper: 0
261           File::Find: 1.03
262
263       (Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
264       this distribution requires for proper operation.  The keys are the
265       module names, and the values are version specifications as described in
266       Module::Build for the "requires" parameter.
267
268   recommends
269       Example:
270
271         recommends:
272           Data::Dumper: 0
273           File::Find: 1.03
274
275       (Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
276       this distribution recommends for enhanced operation.
277
278       ALTERNATIVE: It may be desirable to present to the user which features
279       depend on which modules so they can make an informed decision about
280       which recommended modules to install.
281
282       Example:
283
284         optional_features:
285         - foo:
286             description: Provides the ability to blah.
287             requires:
288               Data::Dumper: 0
289               File::Find: 1.03
290         - bar:
291             description: This feature is not available on this platform.
292             excludes_os: MSWin32
293
294       (Spec 1.1) [optional] {map} A YAML sequence of names for optional
295       features which are made available when its requirements are met. For
296       each feature a description is provided along with any of "requires",
297       "build_requires", "conflicts", "requires_packages", "requires_os", and
298       "excludes_os" which have the same meaning in this subcontext as
299       described elsewhere in this document.
300
301   build_requires
302       Example:
303
304         build_requires:
305           Data::Dumper: 0
306           File::Find: 1.03
307
308       (Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
309       required for building and/or testing of this distribution.  These
310       dependencies are not required after the module is installed.
311
312   conflicts
313       Example:
314
315         conflicts:
316           Data::Dumper: 0
317           File::Find: 1.03
318
319       (Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules
320       that cannot be installed while this distribution is installed.  This is
321       a pretty uncommon situation.
322
323   dynamic_config
324       Example:
325
326         dynamic_config: 0
327
328       (Spec 1.0) [optional] {boolean} A boolean flag indicating whether a
329       Build.PL or Makefile.PL (or similar) must be executed when building
330       this distribution, or whether it can be built, tested and installed
331       solely from consulting its metadata file.  The main reason to set this
332       to a true value if that your module performs some dynamic configuration
333       (asking questions, sensing the environment, etc.) as part of its
334       build/install process.
335
336       Currently Module::Build doesn't actually do anything with this flag -
337       it's probably going to be up to higher-level tools like CPAN to do
338       something useful with it.  It can potentially bring lots of security,
339       packaging, and convenience improvements.
340
341       If this field is omitted, it defaults to 1 (true).
342
343   private
344       (Deprecated) (Spec 1.0) [optional] {map} This field has been renamed to
345       "no_index".  See below.
346
347   provides
348       Example:
349
350         provides:
351           Foo::Bar:
352             file: lib/Foo/Bar.pm
353             version: 0.27_02
354           Foo::Bar::Blah:
355             file: lib/Foo/Bar/Blah.pm
356           Foo::Bar::Baz:
357             file: lib/Foo/Bar/Baz.pm
358             version: 0.3
359
360       (Spec 1.1) [optional] {map} A YAML mapping that describes all packages
361       provided by this distribution.  This information can be (and, in some
362       cases, is) used by distribution and automation mechanisms like PAUSE,
363       CPAN, and search.cpan.org to build indexes saying in which distribution
364       various packages can be found.
365
366       When using tools like Module::Build that can generate the "provides"
367       mapping for your distribution automatically, make sure you examine what
368       it generates to make sure it makes sense - indexers will usually trust
369       the "provides" field if it's present, rather than scanning through the
370       distribution files themselves to figure out packages and versions.
371       This is a good thing, because it means you can use the "provides" field
372       to tell the indexers precisely what you want indexed about your
373       distribution, rather than relying on them to essentially guess what you
374       want indexed.
375
376   no_index
377       Example:
378
379         no_index:
380           file:
381           - My/Module.pm
382           dir:
383           - My/Private
384           package:
385           - My::Module::Stuff
386           namespace:
387           - My::Module::Stuff
388
389       (Spec 1.1) [optional] {map} A YAML mapping that describes any files,
390       directories, packages, and namespaces that are private (i.e.
391       implementation artifacts) that are not of interest to searching and
392       indexing tools.  This is useful when no "provides" field is present.
393
394       (Note: I'm not actually sure who looks at this field, or exactly what
395       they do with it.  This spec could be off in some way from actual
396       usage.)
397
398       file
399
400       (Spec 1.1) [optional] Exclude any listed file(s).
401
402       dir
403
404       (Spec 1.1) [optional] Exclude anything below the listed directory(ies).
405
406       package
407
408       (Spec 1.1) [optional] Exclude the listed package(s).
409
410       namespace
411
412       (Spec 1.1) [optional] Excludes anything below the listed namespace(s),
413       but not the listed namespace(s) its self.
414
415   keywords
416       Example:
417
418         keywords:
419           - make
420           - build
421           - install
422
423       (Spec 1.1) [optional] {list} A sequence of keywords/phrases that
424       describe this distribution.
425
426   resources
427       Example:
428
429         resources:
430           license: http://dev.perl.org/licenses/
431           homepage: http://sourceforge.net/projects/module-build
432           bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build
433           MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general
434
435       (Spec 1.1) [optional] {map} A mapping of any URL resources related to
436       this distribution.  All-lower-case keys, such as "homepage", "license",
437       and "bugtracker", are reserved by this specification, as they have
438       "official" meanings defined here in this specification.  If you'd like
439       to add your own "special" entries (like the "MailingList" entry above),
440       use at least one upper-case letter.
441
442       The current set of official keys is:
443
444       homepage
445         The official home of this project on the web.
446
447       license
448         An URL for an official statement of this distribution's license.
449
450       bugtracker
451         An URL for a bug tracker (e.g. Bugzilla or RT queue) for this
452         project.
453
454   generated_by
455       Example:
456
457         generated_by: Module::Build version 0.20
458
459       (Spec 1.0) [required] {string} Indicates the tool that was used to
460       create this META.yml file.  It's good form to include both the name of
461       the tool and its version, but this field is essentially opaque, at
462       least for the moment. If META.yml was generated by hand, it is
463       suggested that the author be specified here.
464
465       [Note: My meta_stats.pl script which I use to gather statistics
466       regarding META.yml usage prefers the form listed above, i.e. it splits
467       on /\s+version\s+/ taking the first field as the name of the tool that
468       generated the file and the second field as version of that tool. RWS]
469

SEE ALSO

471       CPAN <http://www.cpan.org/>
472
473       CPAN.pm
474
475       CPANPLUS
476
477       Data::Dumper
478
479       ExtUtils::MakeMaker
480
481       Module::Build
482
483       Module::Install
484
485       XML <http://www.w3.org/XML/>
486
487       YAML <http://www.yaml.org/>
488

HISTORY

490       March 14, 2003 (Pi day)
491           • Created version 1.0 of this document.
492
493       May 8, 2003
494           • Added the "dynamic_config" field, which was missing from the
495             initial version.
496
497       November 13, 2003
498           • Added more YAML rationale articles.
499
500           • Fixed existing link to YAML discussion thread to point to new
501             <http://nntp.x.perl.org/group/> site.
502
503           • Added and deprecated the "private" field.
504
505           • Added "abstract", "configure", "requires_packages",
506             "requires_os", "excludes_os", and "no_index" fields.
507
508           • Bumped version.
509
510       November 16, 2003
511           • Added "generation", "authored_by" fields.
512
513           • Add alternative proposal to the "recommends" field.
514
515           • Add proposal for a "requires_build_tools" field.
516
517       December 9, 2003
518           • Added link to latest version of this specification on CPAN.
519
520           • Added section "VERSION SPECIFICATIONS".
521
522           • Chang name from Module::Build::META-spec to
523             CPAN::META::Specification.
524
525           • Add proposal for "auto_regenerate" field.
526
527       December 15, 2003
528           • Add "index" field as a compliment to "no_index"
529
530           • Add "keywords" field as a means to aid searching distributions.
531
532           • Add "TERMINOLOGY" section to explain certain terms that may be
533             ambiguous.
534
535       July 26, 2005
536           • Removed a bunch of items (generation, requires_build_tools,
537             requires_packages, configure, requires_os, excludes_os,
538             auto_regenerate) that have never actually been supported, but
539             were more like records of brainstorming.
540
541           • Changed "authored_by" to "author", since that's always been what
542             it's actually called in actual META.yml files.
543
544           • Added the "==" operator to the list of supported version-checking
545             operators.
546
547           • Noted that the "distribution_type" field is basically
548             meaningless, and shouldn't really be used.
549
550           • Clarified "dynamic_config" a bit.
551
552       August 23, 2005
553           • Removed the name "CPAN::META::Specification", since that implies
554             a module that doesn't actually exist.
555
556
557
558perl v5.32.1                      2021-01-26  CPAN::Meta::History::Meta_1_2(3)
Impressum