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

NAME

6       CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for
7       META.yml
8

PREFACE

10       This is a historical copy of the version 1.3 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.2805 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.3
58          url: http://module-build.sourceforge.net/META-spec-v1.3.html
59        generated_by: Module::Build version 0.20
60

DESCRIPTION

62       This document describes version 1.3 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 together
101           for other developers to use.  Examples of distributions are
102           "Class-Container", "libwww-perl", or "DBI".
103
104       module
105           This refers to a reusable library of code typically contained in a
106           single file. Currently, we primarily talk of perl modules, but this
107           specification should be open enough to apply to other languages as
108           well (ex. python, ruby).  Examples of modules are
109           "Class::Container", "LWP::Simple", or "DBD::File".
110
112       The first line of a META.yml file should be a valid YAML document
113       header like "--- #YAML:1.0".
114

FIELDS

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

VERSION SPECIFICATIONS

469       Some fields require a version specification (ex. "requires",
470       "recommends", "build_requires", etc.) to indicate the particular
471       version(s) of some other module that may be required as a prerequisite.
472       This section details the version specification formats that are
473       currently supported.
474
475       The simplest format for a version specification is just the version
476       number itself, e.g. 2.4.  This means that at least version 2.4 must be
477       present.  To indicate that any version of a prerequisite is okay, even
478       if the prerequisite doesn't define a version at all, use the version 0.
479
480       You may also use the operators < (less than), <= (less than or equal),
481       > (greater than), >= (greater than or equal), == (equal), and != (not
482       equal).  For example, the specification < 2.0 means that any version of
483       the prerequisite less than 2.0 is suitable.
484
485       For more complicated situations, version specifications may be AND-ed
486       together using commas.  The specification >= 1.2, != 1.5, < 2.0
487       indicates a version that must be at least 1.2, less than 2.0, and not
488       equal to 1.5.
489

SEE ALSO

491       CPAN <http://www.cpan.org/>
492
493       CPAN.pm
494
495       CPANPLUS
496
497       Data::Dumper
498
499       ExtUtils::MakeMaker
500
501       Module::Build
502
503       Module::Install
504
505       XML <http://www.w3.org/XML/>
506
507       YAML <http://www.yaml.org/>
508

HISTORY

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