1CPAN::Meta::History::MeUtsae_r1_C4o(n3t)ributed Perl DocCuPmAeNn:t:aMteitoan::History::Meta_1_4(3)
2
6 CPAN::Meta::History::Meta_1_4 - Version 1.4 metadata specification for
7 META.yml
8
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 Modifications from the original:
15 · Various spelling corrections
17 · 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 · 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 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
62 This document describes version 1.4 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.4
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 or the Artistic license.
215 restrictive
217 The distribution may not be redistributed without special
218 permission from the author and/or copyright holder.
219 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 distribution_type
226 Example:
227 distribution_type: module
229 (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 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 requires
241 Example:
242 requires:
244 Data::Dumper: 0
245 File::Find: 1.03
246 (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 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
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 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 Example:
271 optional_features:
273 foo:
274 description: Provides the ability to blah.
275 requires:
276 Data::Dumper: 0
277 File::Find: 1.03
278 (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 build_requires
286 Example:
287 build_requires:
289 Data::Dumper: 0
290 File::Find: 1.03
291 (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 configure_requires
300 Example:
301 configure_requires:
303 Module::Build: 0.2809
304 Data::Dumper: 0
305 File::Find: 1.03
306 (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 conflicts
315 Example:
316 conflicts:
318 Data::Dumper: 0
319 File::Find: 1.03
320 (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 dynamic_config
328 Example:
329 dynamic_config: 0
331 (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 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 If this field is omitted, it defaults to 1 (true).
346 private
348 (Deprecated) (Spec 1.0) [optional] {map} This field has been renamed to
349 "no_index". See below.
350 provides
352 Example:
353 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 (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 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 no_index
381 Example:
382 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 (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 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 file
405 (Spec 1.1) [optional] Exclude any listed file(s).
407 directory
409 (Spec 1.1) [optional] Exclude anything below the listed directory(ies).
411 [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 package
417 (Spec 1.1) [optional] Exclude the listed package(s).
419 namespace
421 (Spec 1.1) [optional] Excludes anything below the listed namespace(s),
423 but not the listed namespace(s) its self.
424 keywords
426 Example:
427 keywords:
429 - make
430 - build
431 - install
432 (Spec 1.1) [optional] {list} A sequence of keywords/phrases that
434 describe this distribution.
435 resources
437 Example:
438 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 (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 The current set of official keys is:
454 homepage
456 The official home of this project on the web.
457 license
459 An URL for an official statement of this distribution's license.
460 bugtracker
462 An URL for a bug tracker (e.g. Bugzilla or RT queue) for this
463 project.
464 generated_by
466 Example:
467 generated_by: Module::Build version 0.20
469 (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 [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
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 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 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 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
504 CPAN <http://www.cpan.org/>
505 CPAN.pm
507 CPANPLUS
509 Data::Dumper
511 ExtUtils::MakeMaker
513 Module::Build
515 Module::Install
517 XML <http://www.w3.org/XML/>
519 YAML <http://www.yaml.org/>
521
523 March 14, 2003 (Pi day)
524 · Created version 1.0 of this document.
525 May 8, 2003
527 · Added the "dynamic_config" field, which was missing from the
528 initial version.
529 November 13, 2003
531 · Added more YAML rationale articles.
532 · Fixed existing link to YAML discussion thread to point to new
534 <http://nntp.x.perl.org/group/> site.
535 · Added and deprecated the "private" field.
537 · Added "abstract", "configure", "requires_packages",
539 "requires_os", "excludes_os", and "no_index" fields.
540 · Bumped version.
542 November 16, 2003
544 · Added "generation", "authored_by" fields.
545 · Add alternative proposal to the "recommends" field.
547 · Add proposal for a "requires_build_tools" field.
549 December 9, 2003
551 · Added link to latest version of this specification on CPAN.
552 · Added section "VERSION SPECIFICATIONS".
554 · Chang name from Module::Build::META-spec to
556 CPAN::META::Specification.
557 · Add proposal for "auto_regenerate" field.
559 December 15, 2003
561 · Add "index" field as a compliment to "no_index"
562 · Add "keywords" field as a means to aid searching distributions.
564 · Add "TERMINOLOGY" section to explain certain terms that may be
566 ambiguous.
567 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 · Changed "authored_by" to "author", since that's always been what
575 it's actually called in actual META.yml files.
576 · Added the "==" operator to the list of supported version-checking
578 operators.
579 · Noted that the "distribution_type" field is basically
581 meaningless, and shouldn't really be used.
582 · Clarified "dynamic_config" a bit.
584 August 23, 2005
586 · Removed the name "CPAN::META::Specification", since that implies
587 a module that doesn't actually exist.
588 June 12, 2007
590 · Added "configure_requires".
591perl v5.32.0 2020-07-28 CPAN::Meta::History::Meta_1_4(3)