1CPAN::Meta::History::MeUtsae_r1_C4o(n3t)ributed Perl DocCuPmAeNn:t:aMteitoan::History::Meta_1_4(3)
2
3
4
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
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
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
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
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
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
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
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
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
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.34.0 2021-07-22 CPAN::Meta::History::Meta_1_4(3)