1CPAN::Meta::History::MeUtsae_r1_C3o(n3t)ributed Perl DocCuPmAeNn:t:aMteitoan::History::Meta_1_3(3)
2
6 CPAN::Meta::History::Meta_1_3 - Version 1.3 metadata specification for
7 META.yml
8
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 Modifications from the original:
15 · Various spelling corrections
17 · 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 · Fixed some dead links to point to active resources.
23
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
62 This document describes version 1.3 of the META.yml specification.
63 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 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 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
81 META.yml files are written in the YAML format (see
82 <http://www.yaml.org/>).
83 See the following links to learn why we chose YAML instead of, say, XML
85 or Data::Dumper:
86 · Module::Build design plans
88 <http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html>
89 · Not keen on YAML <http://www.nntp.perl.org/group/perl.module-
91 authors/2003/11/msg1353.html>
92 · META Concerns <http://www.nntp.perl.org/group/perl.module-
94 authors/2003/11/msg1385.html>
95
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 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
116 The rest of the META.yml file is one big YAML mapping whose keys are
117 described here.
118 meta-spec
120 Example:
121 meta-spec:
123 version: 1.3
124 url: http://module-build.sourceforge.net/META-spec-v1.3.html
125 (Spec 1.1) [required] {URL} This field indicates the location of the
127 version of the META.yml specification used.
128 name
130 Example:
131 name: Module-Build
133 (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 version
141 Example:
142 version: 0.20
144 (Spec 1.0) [required] {version} The version of the distribution to
146 which the META.yml file refers.
147 abstract
149 Example:
150 abstract: Build and install Perl modules.
152 (Spec 1.1) [required] {string} A short description of the purpose of
154 the distribution.
155 author
157 Example:
158 author:
160 - Ken Williams <kwilliams@cpan.org>
161 (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 license
167 Example:
168 license: perl
170 (Spec 1.0) [required] {string} The license under which this
172 distribution may be used and redistributed.
173 Must be one of the following licenses:
175 apache
177 The distribution is licensed under the Apache Software License
178 version 1.1 (<http://opensource.org/licenses/Apache-1.1>).
179 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 bsd The distribution is licensed under the BSD 3-Clause License
186 (<http://opensource.org/licenses/BSD-3-Clause>).
187 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 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 mit The distribution is licensed under the MIT License
198 (<http://opensource.org/licenses/MIT>).
199 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 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 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 restrictive
218 The distribution may not be redistributed without special
219 permission from the author and/or copyright holder.
220 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 distribution_type
227 Example:
228 distribution_type: module
230 (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 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 requires
242 Example:
243 requires:
245 Data::Dumper: 0
246 File::Find: 1.03
247 (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 recommends
254 Example:
255 recommends:
257 Data::Dumper: 0
258 File::Find: 1.03
259 (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 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 Example:
270 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 (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 build_requires
289 Example:
290 build_requires:
292 Data::Dumper: 0
293 File::Find: 1.03
294 (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 conflicts
302 Example:
303 conflicts:
305 Data::Dumper: 0
306 File::Find: 1.03
307 (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 dynamic_config
315 Example:
316 dynamic_config: 0
318 (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 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 If this field is omitted, it defaults to 1 (true).
333 private
335 (Deprecated) (Spec 1.0) [optional] {map} This field has been renamed to
336 "no_index". See below.
337 provides
339 Example:
340 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 (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 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 no_index
368 Example:
369 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 (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 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 file
392 (Spec 1.1) [optional] Exclude any listed file(s).
394 directory
396 (Spec 1.1) [optional] Exclude anything below the listed directory(ies).
398 [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 package
404 (Spec 1.1) [optional] Exclude the listed package(s).
406 namespace
408 (Spec 1.1) [optional] Excludes anything below the listed namespace(s),
410 but not the listed namespace(s) its self.
411 keywords
413 Example:
414 keywords:
416 - make
417 - build
418 - install
419 (Spec 1.1) [optional] {list} A sequence of keywords/phrases that
421 describe this distribution.
422 resources
424 Example:
425 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 (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 The current set of official keys is:
441 homepage
443 The official home of this project on the web.
444 license
446 An URL for an official statement of this distribution's license.
447 bugtracker
449 An URL for a bug tracker (e.g. Bugzilla or RT queue) for this
450 project.
451 generated_by
453 Example:
454 generated_by: Module::Build version 0.20
456 (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 [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
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 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 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
483 of the prerequisite less than 2.0 is suitable.
484 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
491 CPAN <http://www.cpan.org/>
492 CPAN.pm
494 CPANPLUS
496 Data::Dumper
498 ExtUtils::MakeMaker
500 Module::Build
502 Module::Install
504 XML <http://www.w3.org/XML/>
506 YAML <http://www.yaml.org/>
508
510 March 14, 2003 (Pi day)
511 · Created version 1.0 of this document.
512 May 8, 2003
514 · Added the "dynamic_config" field, which was missing from the
515 initial version.
516 November 13, 2003
518 · Added more YAML rationale articles.
519 · Fixed existing link to YAML discussion thread to point to new
521 <http://nntp.x.perl.org/group/> site.
522 · Added and deprecated the "private" field.
524 · Added "abstract", "configure", "requires_packages",
526 "requires_os", "excludes_os", and "no_index" fields.
527 · Bumped version.
529 November 16, 2003
531 · Added "generation", "authored_by" fields.
532 · Add alternative proposal to the "recommends" field.
534 · Add proposal for a "requires_build_tools" field.
536 December 9, 2003
538 · Added link to latest version of this specification on CPAN.
539 · Added section "VERSION SPECIFICATIONS".
541 · Chang name from Module::Build::META-spec to
543 CPAN::META::Specification.
544 · Add proposal for "auto_regenerate" field.
546 December 15, 2003
548 · Add "index" field as a compliment to "no_index"
549 · Add "keywords" field as a means to aid searching distributions.
551 · Add "TERMINOLOGY" section to explain certain terms that may be
553 ambiguous.
554 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 · Changed "authored_by" to "author", since that's always been what
562 it's actually called in actual META.yml files.
563 · Added the "==" operator to the list of supported version-checking
565 operators.
566 · Noted that the "distribution_type" field is basically
568 meaningless, and shouldn't really be used.
569 · Clarified "dynamic_config" a bit.
571 August 23, 2005
573 · Removed the name "CPAN::META::Specification", since that implies
574 a module that doesn't actually exist.
575perl v5.28.0 2016-08-18 CPAN::Meta::History::Meta_1_3(3)