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

NAME

6       CPAN::Meta::History::Meta_1_4 - Version 1.4 metadata specification for
7       META.yml
8

PREFACE

10       This is a historical copy of the version 1.4 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.2807 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        resources:
55          license: http://dev.perl.org/licenses/
56        meta-spec:
57          version: 1.4
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.4 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.4
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 or the Artistic license.
215
216       restrictive
217           The distribution may not be redistributed without special
218           permission from the author and/or copyright holder.
219
220       unrestricted
221           The distribution is licensed under a license that is not approved
222           by www.opensource.org <http://www.opensource.org/> but that allows
223           distribution without restrictions.
224
225   distribution_type
226       Example:
227
228         distribution_type: module
229
230       (Spec 1.0) [optional] {string} What kind of stuff is contained in this
231       distribution.  Most things on CPAN are "module"s (which can also mean a
232       collection of modules), but some things are "script"s.
233
234       Unfortunately this field is basically meaningless, since many
235       distributions are hybrids of several kinds of things, or some new
236       thing, or subjectively different in focus depending on who's using
237       them.  Tools like Module::Build and MakeMaker will likely stop
238       generating this field.
239
240   requires
241       Example:
242
243         requires:
244           Data::Dumper: 0
245           File::Find: 1.03
246
247       (Spec 1.0) [optional] {map} A YAML mapping indicating the Perl
248       prerequisites this distribution requires for proper operation.  The
249       keys are the names of the prerequisites (module names or 'perl'), and
250       the values are version specifications as described in VERSION
251       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
261       prerequisites this distribution recommends for enhanced operation.  The
262       keys are the names of the prerequisites (module names or 'perl'), and
263       the values are version specifications as described in VERSION
264       SPECIFICATIONS.
265
266       ALTERNATIVE: It may be desirable to present to the user which features
267       depend on which modules so they can make an informed decision about
268       which recommended modules to install.
269
270       Example:
271
272         optional_features:
273           foo:
274             description: Provides the ability to blah.
275             requires:
276               Data::Dumper: 0
277               File::Find: 1.03
278
279       (Spec 1.1) [optional] {map} A YAML mapping of names for optional
280       features which are made available when its requirements are met. For
281       each feature a description is provided along with any of "requires",
282       "build_requires", and "conflicts", which have the same meaning in this
283       subcontext as described elsewhere in this document.
284
285   build_requires
286       Example:
287
288         build_requires:
289           Data::Dumper: 0
290           File::Find: 1.03
291
292       (Spec 1.0) [optional] {map} A YAML mapping indicating the Perl
293       prerequisites required for building and/or testing of this
294       distribution.  The keys are the names of the prerequisites (module
295       names or 'perl'), and the values are version specifications as
296       described in "VERSION SPECIFICATIONS".  These dependencies are not
297       required after the distribution is installed.
298
299   configure_requires
300       Example:
301
302         configure_requires:
303           Module::Build: 0.2809
304           Data::Dumper: 0
305           File::Find: 1.03
306
307       (Spec 1.4) [optional] {map} A YAML mapping indicating the Perl
308       prerequisites required before configuring this distribution.  The keys
309       are the names of the prerequisites (module names or 'perl'), and the
310       values are version specifications as described in "VERSION
311       SPECIFICATIONS".  These dependencies are not required after the
312       distribution is installed.
313
314   conflicts
315       Example:
316
317         conflicts:
318           Data::Dumper: 0
319           File::Find: 1.03
320
321       (Spec 1.0) [optional] {map} A YAML mapping indicating any items that
322       cannot be installed while this distribution is installed.  This is a
323       pretty uncommon situation.  The keys for "conflicts" are the item names
324       (module names or 'perl'), and the values are version specifications as
325       described in "VERSION SPECIFICATIONS".
326
327   dynamic_config
328       Example:
329
330         dynamic_config: 0
331
332       (Spec 1.0) [optional] {boolean} A boolean flag indicating whether a
333       Build.PL or Makefile.PL (or similar) must be executed when building
334       this distribution, or whether it can be built, tested and installed
335       solely from consulting its metadata file.  The main reason to set this
336       to a true value is that your module performs some dynamic configuration
337       (asking questions, sensing the environment, etc.) as part of its
338       build/install process.
339
340       Currently Module::Build doesn't actually do anything with this flag -
341       it's probably going to be up to higher-level tools like CPAN to do
342       something useful with it.  It can potentially bring lots of security,
343       packaging, and convenience improvements.
344
345       If this field is omitted, it defaults to 1 (true).
346
347   private
348       (Deprecated) (Spec 1.0) [optional] {map} This field has been renamed to
349       "no_index".  See below.
350
351   provides
352       Example:
353
354         provides:
355           Foo::Bar:
356             file: lib/Foo/Bar.pm
357             version: 0.27_02
358           Foo::Bar::Blah:
359             file: lib/Foo/Bar/Blah.pm
360           Foo::Bar::Baz:
361             file: lib/Foo/Bar/Baz.pm
362             version: 0.3
363
364       (Spec 1.1) [optional] {map} A YAML mapping that describes all packages
365       provided by this distribution.  This information can be (and, in some
366       cases, is) used by distribution and automation mechanisms like PAUSE,
367       CPAN, and search.cpan.org to build indexes saying in which distribution
368       various packages can be found.
369
370       When using tools like Module::Build that can generate the "provides"
371       mapping for your distribution automatically, make sure you examine what
372       it generates to make sure it makes sense - indexers will usually trust
373       the "provides" field if it's present, rather than scanning through the
374       distribution files themselves to figure out packages and versions.
375       This is a good thing, because it means you can use the "provides" field
376       to tell the indexers precisely what you want indexed about your
377       distribution, rather than relying on them to essentially guess what you
378       want indexed.
379
380   no_index
381       Example:
382
383         no_index:
384           file:
385           - My/Module.pm
386           directory:
387           - My/Private
388           package:
389           - My::Module::Stuff
390           namespace:
391           - My::Module::Stuff
392
393       (Spec 1.1) [optional] {map} A YAML mapping that describes any files,
394       directories, packages, and namespaces that are private (i.e.
395       implementation artifacts) that are not of interest to searching and
396       indexing tools.  This is useful when no "provides" field is present.
397
398       For example, <http://search.cpan.org/> excludes items listed in
399       "no_index" when searching for POD, meaning files in these directories
400       will not converted to HTML and made public - which is useful if you
401       have example or test PODs that you don't want the search engine to go
402       through.
403
404       file
405
406       (Spec 1.1) [optional] Exclude any listed file(s).
407
408       directory
409
410       (Spec 1.1) [optional] Exclude anything below the listed directory(ies).
411
412       [Note: previous editions of the spec had "dir" instead of "directory",
413       but I think MakeMaker and various users started using "directory", so
414       in deference we switched to that.]
415
416       package
417
418       (Spec 1.1) [optional] Exclude the listed package(s).
419
420       namespace
421
422       (Spec 1.1) [optional] Excludes anything below the listed namespace(s),
423       but not the listed namespace(s) its self.
424
425   keywords
426       Example:
427
428         keywords:
429           - make
430           - build
431           - install
432
433       (Spec 1.1) [optional] {list} A sequence of keywords/phrases that
434       describe this distribution.
435
436   resources
437       Example:
438
439         resources:
440           license: http://dev.perl.org/licenses/
441           homepage: http://sourceforge.net/projects/module-build
442           bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Build
443           repository: http://sourceforge.net/cvs/?group_id=45731
444           MailingList: http://lists.sourceforge.net/lists/listinfo/module-build-general
445
446       (Spec 1.1) [optional] {map} A mapping of any URL resources related to
447       this distribution.  All-lower-case keys, such as "homepage", "license",
448       and "bugtracker", are reserved by this specification, as they have
449       "official" meanings defined here in this specification.  If you'd like
450       to add your own "special" entries (like the "MailingList" entry above),
451       use at least one upper-case letter.
452
453       The current set of official keys is:
454
455       homepage
456         The official home of this project on the web.
457
458       license
459         An URL for an official statement of this distribution's license.
460
461       bugtracker
462         An URL for a bug tracker (e.g. Bugzilla or RT queue) for this
463         project.
464
465   generated_by
466       Example:
467
468         generated_by: Module::Build version 0.20
469
470       (Spec 1.0) [required] {string} Indicates the tool that was used to
471       create this META.yml file.  It's good form to include both the name of
472       the tool and its version, but this field is essentially opaque, at
473       least for the moment. If META.yml was generated by hand, it is
474       suggested that the author be specified here.
475
476       [Note: My meta_stats.pl script which I use to gather statistics
477       regarding META.yml usage prefers the form listed above, i.e. it splits
478       on /\s+version\s+/ taking the first field as the name of the tool that
479       generated the file and the second field as version of that tool. RWS]
480

VERSION SPECIFICATIONS

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

SEE ALSO

504       CPAN <http://www.cpan.org/>
505
506       CPAN.pm
507
508       CPANPLUS
509
510       Data::Dumper
511
512       ExtUtils::MakeMaker
513
514       Module::Build
515
516       Module::Install
517
518       XML <http://www.w3.org/XML/>
519
520       YAML <http://www.yaml.org/>
521

HISTORY

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