Commit | Line | Data |
---|---|---|
7ec7fa08 CBW |
1 | # XXX RULES FOR PATCHING THIS FILE XXX |
2 | # Patches that fix typos or formatting are acceptable. Patches | |
3 | # that change semantics are not acceptable without prior approval | |
4 | # by David Golden or Ricardo Signes. | |
5 | ||
c05760c6 DG |
6 | use 5.006; |
7 | use strict; | |
8 | use warnings; | |
9 | package CPAN::Meta::Spec; | |
53bb269a | 10 | our $VERSION = '2.132510'; # VERSION |
730e5b5b | 11 | |
c05760c6 DG |
12 | 1; |
13 | ||
730e5b5b CBW |
14 | # ABSTRACT: specification for CPAN distribution metadata |
15 | ||
7ec7fa08 CBW |
16 | |
17 | # vi:tw=72 | |
18 | ||
c05760c6 | 19 | __END__ |
7f6e6ca2 | 20 | |
c05760c6 DG |
21 | =pod |
22 | ||
7f6e6ca2 CBW |
23 | =encoding utf-8 |
24 | ||
c05760c6 DG |
25 | =head1 NAME |
26 | ||
27 | CPAN::Meta::Spec - specification for CPAN distribution metadata | |
28 | ||
29 | =head1 VERSION | |
30 | ||
53bb269a | 31 | version 2.132510 |
c05760c6 DG |
32 | |
33 | =head1 SYNOPSIS | |
34 | ||
35 | my $distmeta = { | |
36 | name => 'Module-Build', | |
37 | abstract => 'Build and install Perl modules', | |
38 | description => "Module::Build is a system for " | |
39 | . "building, testing, and installing Perl modules. " | |
40 | . "It is meant to ... blah blah blah ...", | |
41 | version => '0.36', | |
5bc9579e | 42 | release_status => 'stable', |
c05760c6 DG |
43 | author => [ |
44 | 'Ken Williams <kwilliams@cpan.org>', | |
45 | 'Module-Build List <module-build@perl.org>', # additional contact | |
46 | ], | |
47 | license => [ 'perl_5' ], | |
48 | prereqs => { | |
49 | runtime => { | |
50 | requires => { | |
51 | 'perl' => '5.006', | |
52 | 'ExtUtils::Install' => '0', | |
53 | 'File::Basename' => '0', | |
54 | 'File::Compare' => '0', | |
55 | 'IO::File' => '0', | |
56 | }, | |
57 | recommends => { | |
58 | 'Archive::Tar' => '1.00', | |
59 | 'ExtUtils::Install' => '0.3', | |
60 | 'ExtUtils::ParseXS' => '2.02', | |
61 | }, | |
62 | }, | |
63 | build => { | |
64 | requires => { | |
65 | 'Test::More' => '0', | |
66 | }, | |
67 | } | |
68 | }, | |
69 | resources => { | |
70 | license => ['http://dev.perl.org/licenses/'], | |
71 | }, | |
72 | optional_features => { | |
73 | domination => { | |
74 | description => 'Take over the world', | |
75 | prereqs => { | |
76 | develop => { requires => { 'Genius::Evil' => '1.234' } }, | |
77 | runtime => { requires => { 'Machine::Weather' => '2.0' } }, | |
78 | }, | |
79 | }, | |
80 | }, | |
81 | dynamic_config => 1, | |
82 | keywords => [ qw/ toolchain cpan dual-life / ], | |
83 | 'meta-spec' => { | |
84 | version => '2', | |
85 | url => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec', | |
86 | }, | |
87 | generated_by => 'Module::Build version 0.36', | |
88 | }; | |
89 | ||
90 | =head1 DESCRIPTION | |
91 | ||
92 | This document describes version 2 of the CPAN distribution metadata | |
93 | specification, also known as the "CPAN Meta Spec". | |
94 | ||
95 | Revisions of this specification for typo corrections and prose | |
96 | clarifications may be issued as CPAN::Meta::Spec 2.I<x>. These | |
97 | revisions will never change semantics or add or remove specified | |
98 | behavior. | |
99 | ||
100 | Distribution metadata describe important properties of Perl | |
101 | distributions. Distribution building tools like Module::Build, | |
102 | Module::Install, ExtUtils::MakeMaker or Dist::Zilla should create a | |
103 | metadata file in accordance with this specification and include it with | |
104 | the distribution for use by automated tools that index, examine, package | |
105 | or install Perl distributions. | |
106 | ||
107 | =head1 TERMINOLOGY | |
108 | ||
109 | =over 4 | |
110 | ||
111 | =item distribution | |
112 | ||
113 | This is the primary object described by the metadata. In the context of | |
114 | this document it usually refers to a collection of modules, scripts, | |
115 | and/or documents that are distributed together for other developers to | |
116 | use. Examples of distributions are C<Class-Container>, C<libwww-perl>, | |
117 | or C<DBI>. | |
118 | ||
119 | =item module | |
120 | ||
121 | This refers to a reusable library of code contained in a single file. | |
122 | Modules usually contain one or more packages and are often referred | |
123 | to by the name of a primary package that can be mapped to the file | |
124 | name. For example, one might refer to C<File::Spec> instead of | |
125 | F<File/Spec.pm> | |
126 | ||
127 | =item package | |
128 | ||
129 | This refers to a namespace declared with the Perl C<package> statement. | |
130 | In Perl, packages often have a version number property given by the | |
131 | C<$VERSION> variable in the namespace. | |
132 | ||
133 | =item consumer | |
134 | ||
135 | This refers to code that reads a metadata file, deserializes it into a | |
136 | data structure in memory, or interprets a data structure of metadata | |
137 | elements. | |
138 | ||
139 | =item producer | |
140 | ||
141 | This refers to code that constructs a metadata data structure, | |
142 | serializes into a bytestream and/or writes it to disk. | |
143 | ||
144 | =item must, should, may, etc. | |
145 | ||
146 | These terms are interpreted as described in IETF RFC 2119. | |
147 | ||
148 | =back | |
149 | ||
150 | =head1 DATA TYPES | |
151 | ||
152 | Fields in the L</STRUCTURE> section describe data elements, each of | |
153 | which has an associated data type as described herein. There are four | |
154 | primitive types: Boolean, String, List and Map. Other types are | |
155 | subtypes of primitives and define compound data structures or define | |
156 | constraints on the values of a data element. | |
157 | ||
158 | =head2 Boolean | |
159 | ||
160 | A I<Boolean> is used to provide a true or false value. It B<must> be | |
161 | represented as a defined value. | |
162 | ||
163 | =head2 String | |
164 | ||
165 | A I<String> is data element containing a non-zero length sequence of | |
166 | Unicode characters, such as an ordinary Perl scalar that is not a | |
167 | reference. | |
168 | ||
169 | =head2 List | |
170 | ||
171 | A I<List> is an ordered collection of zero or more data elements. | |
172 | Elements of a List may be of mixed types. | |
173 | ||
174 | Producers B<must> represent List elements using a data structure which | |
175 | unambiguously indicates that multiple values are possible, such as a | |
176 | reference to a Perl array (an "arrayref"). | |
177 | ||
178 | Consumers expecting a List B<must> consider a String as equivalent to a | |
179 | List of length 1. | |
180 | ||
181 | =head2 Map | |
182 | ||
183 | A I<Map> is an unordered collection of zero or more data elements | |
184 | ("values"), indexed by associated String elements ("keys"). The Map's | |
185 | value elements may be of mixed types. | |
186 | ||
187 | =head2 License String | |
188 | ||
189 | A I<License String> is a subtype of String with a restricted set of | |
190 | values. Valid values are described in detail in the description of | |
191 | the L</license> field. | |
192 | ||
193 | =head2 URL | |
194 | ||
195 | I<URL> is a subtype of String containing a Uniform Resource Locator or | |
196 | Identifier. [ This type is called URL and not URI for historical reasons. ] | |
197 | ||
198 | =head2 Version | |
199 | ||
200 | A I<Version> is a subtype of String containing a value that describes | |
201 | the version number of packages or distributions. Restrictions on format | |
202 | are described in detail in the L</Version Formats> section. | |
203 | ||
204 | =head2 Version Range | |
205 | ||
206 | The I<Version Range> type is a subtype of String. It describes a range | |
207 | of Versions that may be present or installed to fulfill prerequisites. | |
208 | It is specified in detail in the L</Version Ranges> section. | |
209 | ||
210 | =head1 STRUCTURE | |
211 | ||
212 | The metadata structure is a data element of type Map. This section | |
213 | describes valid keys within the Map. | |
214 | ||
215 | Any keys not described in this specification document (whether top-level | |
216 | or within compound data structures described herein) are considered | |
217 | I<custom keys> and B<must> begin with an "x" or "X" and be followed by an | |
218 | underscore; i.e. they must match the pattern: C<< qr{\Ax_}i >>. If a | |
219 | custom key refers to a compound data structure, subkeys within it do not | |
220 | need an "x_" or "X_" prefix. | |
221 | ||
222 | Consumers of metadata may ignore any or all custom keys. All other keys | |
223 | not described herein are invalid and should be ignored by consumers. | |
224 | Producers must not generate or output invalid keys. | |
225 | ||
226 | For each key, an example is provided followed by a description. The | |
227 | description begins with the version of spec in which the key was added | |
228 | or in which the definition was modified, whether the key is I<required> | |
229 | or I<optional> and the data type of the corresponding data element. | |
230 | These items are in parentheses, brackets and braces, respectively. | |
231 | ||
232 | If a data type is a Map or Map subtype, valid subkeys will be described | |
233 | as well. | |
234 | ||
235 | Some fields are marked I<Deprecated>. These are shown for historical | |
236 | context and must not be produced in or consumed from any metadata structure | |
237 | of version 2 or higher. | |
238 | ||
239 | =head2 REQUIRED FIELDS | |
240 | ||
241 | =head3 abstract | |
242 | ||
243 | Example: | |
244 | ||
245 | abstract => 'Build and install Perl modules' | |
246 | ||
247 | (Spec 1.2) [required] {String} | |
248 | ||
249 | This is a short description of the purpose of the distribution. | |
250 | ||
251 | =head3 author | |
252 | ||
253 | Example: | |
254 | ||
255 | author => [ 'Ken Williams <kwilliams@cpan.org>' ] | |
256 | ||
257 | (Spec 1.2) [required] {List of one or more Strings} | |
258 | ||
259 | This List indicates the person(s) to contact concerning the | |
260 | distribution. The preferred form of the contact string is: | |
261 | ||
262 | contact-name <email-address> | |
263 | ||
264 | This field provides a general contact list independent of other | |
265 | structured fields provided within the L</resources> field, such as | |
266 | C<bugtracker>. The addressee(s) can be contacted for any purpose | |
267 | including but not limited to (security) problems with the distribution, | |
268 | questions about the distribution or bugs in the distribution. | |
269 | ||
270 | A distribution's original author is usually the contact listed within | |
271 | this field. Co-maintainers, successor maintainers or mailing lists | |
272 | devoted to the distribution may also be listed in addition to or instead | |
273 | of the original author. | |
274 | ||
275 | =head3 dynamic_config | |
276 | ||
277 | Example: | |
278 | ||
279 | dynamic_config => 1 | |
280 | ||
281 | (Spec 2) [required] {Boolean} | |
282 | ||
283 | A boolean flag indicating whether a F<Build.PL> or F<Makefile.PL> (or | |
284 | similar) must be executed to determine prerequisites. | |
285 | ||
286 | This field should be set to a true value if the distribution performs | |
287 | some dynamic configuration (asking questions, sensing the environment, | |
288 | etc.) as part of its configuration. This field should be set to a false | |
289 | value to indicate that prerequisites included in metadata may be | |
290 | considered final and valid for static analysis. | |
291 | ||
292 | This field explicitly B<does not> indicate whether installation may be | |
293 | safely performed without using a Makefile or Build file, as there may be | |
294 | special files to install or custom installation targets (e.g. for | |
295 | dual-life modules that exist on CPAN as well as in the Perl core). This | |
296 | field only defines whether prerequisites are complete as given in the | |
297 | metadata. | |
298 | ||
299 | =head3 generated_by | |
300 | ||
301 | Example: | |
302 | ||
303 | generated_by => 'Module::Build version 0.36' | |
304 | ||
305 | (Spec 1.0) [required] {String} | |
306 | ||
307 | This field indicates the tool that was used to create this metadata. | |
308 | There are no defined semantics for this field, but it is traditional to | |
309 | use a string in the form "Generating::Package version 1.23" or the | |
310 | author's name, if the file was generated by hand. | |
311 | ||
312 | =head3 license | |
313 | ||
314 | Example: | |
315 | ||
316 | license => [ 'perl_5' ] | |
317 | ||
318 | license => [ 'apache_2', 'mozilla_1_0' ] | |
319 | ||
320 | (Spec 2) [required] {List of one or more License Strings} | |
321 | ||
322 | One or more licenses that apply to some or all of the files in the | |
323 | distribution. If multiple licenses are listed, the distribution | |
324 | documentation should be consulted to clarify the interpretation of | |
325 | multiple licenses. | |
326 | ||
327 | The following list of license strings are valid: | |
328 | ||
329 | string description | |
330 | ------------- ----------------------------------------------- | |
331 | agpl_3 GNU Affero General Public License, Version 3 | |
332 | apache_1_1 Apache Software License, Version 1.1 | |
333 | apache_2_0 Apache License, Version 2.0 | |
334 | artistic_1 Artistic License, (Version 1) | |
335 | artistic_2 Artistic License, Version 2.0 | |
336 | bsd BSD License (three-clause) | |
337 | freebsd FreeBSD License (two-clause) | |
338 | gfdl_1_2 GNU Free Documentation License, Version 1.2 | |
339 | gfdl_1_3 GNU Free Documentation License, Version 1.3 | |
340 | gpl_1 GNU General Public License, Version 1 | |
341 | gpl_2 GNU General Public License, Version 2 | |
342 | gpl_3 GNU General Public License, Version 3 | |
343 | lgpl_2_1 GNU Lesser General Public License, Version 2.1 | |
344 | lgpl_3_0 GNU Lesser General Public License, Version 3.0 | |
345 | mit MIT (aka X11) License | |
346 | mozilla_1_0 Mozilla Public License, Version 1.0 | |
347 | mozilla_1_1 Mozilla Public License, Version 1.1 | |
348 | openssl OpenSSL License | |
349 | perl_5 The Perl 5 License (Artistic 1 & GPL 1 or later) | |
350 | qpl_1_0 Q Public License, Version 1.0 | |
351 | ssleay Original SSLeay License | |
352 | sun Sun Internet Standards Source License (SISSL) | |
353 | zlib zlib License | |
354 | ||
355 | The following license strings are also valid and indicate other | |
356 | licensing not described above: | |
357 | ||
358 | string description | |
359 | ------------- ----------------------------------------------- | |
360 | open_source Other Open Source Initiative (OSI) approved license | |
361 | restricted Requires special permission from copyright holder | |
362 | unrestricted Not an OSI approved license, but not restricted | |
363 | unknown License not provided in metadata | |
364 | ||
365 | All other strings are invalid in the license field. | |
366 | ||
367 | =head3 meta-spec | |
368 | ||
369 | Example: | |
370 | ||
371 | 'meta-spec' => { | |
372 | version => '2', | |
373 | url => 'http://search.cpan.org/perldoc?CPAN::Meta::Spec', | |
374 | } | |
375 | ||
376 | (Spec 1.2) [required] {Map} | |
377 | ||
378 | This field indicates the version of the CPAN Meta Spec that should be | |
379 | used to interpret the metadata. Consumers must check this key as soon | |
380 | as possible and abort further metadata processing if the meta-spec | |
381 | version is not supported by the consumer. | |
382 | ||
383 | The following keys are valid, but only C<version> is required. | |
384 | ||
385 | =over | |
386 | ||
387 | =item version | |
388 | ||
389 | This subkey gives the integer I<Version> of the CPAN Meta Spec against | |
390 | which the document was generated. | |
391 | ||
392 | =item url | |
393 | ||
394 | This is a I<URL> of the metadata specification document corresponding to | |
395 | the given version. This is strictly for human-consumption and should | |
396 | not impact the interpretation of the document. | |
397 | ||
398 | =back | |
399 | ||
400 | =head3 name | |
401 | ||
402 | Example: | |
403 | ||
404 | name => 'Module-Build' | |
405 | ||
406 | (Spec 1.0) [required] {String} | |
407 | ||
408 | This field is the name of the distribution. This is often created by | |
409 | taking the "main package" in the distribution and changing C<::> to | |
410 | C<->, but the name may be completely unrelated to the packages within | |
411 | the distribution. C.f. L<http://search.cpan.org/dist/libwww-perl/>. | |
412 | ||
413 | =head3 release_status | |
414 | ||
415 | Example: | |
416 | ||
417 | release_status => 'stable' | |
418 | ||
419 | (Spec 2) [required] {String} | |
420 | ||
421 | This field provides the release status of this distribution. If the | |
422 | C<version> field contains an underscore character, then | |
423 | C<release_status> B<must not> be "stable." | |
424 | ||
425 | The C<release_status> field B<must> have one of the following values: | |
426 | ||
427 | =over | |
428 | ||
429 | =item stable | |
430 | ||
431 | This indicates an ordinary, "final" release that should be indexed by PAUSE | |
432 | or other indexers. | |
433 | ||
434 | =item testing | |
435 | ||
436 | This indicates a "beta" release that is substantially complete, but has an | |
437 | elevated risk of bugs and requires additional testing. The distribution | |
438 | should not be installed over a stable release without an explicit request | |
439 | or other confirmation from a user. This release status may also be used | |
440 | for "release candidate" versions of a distribution. | |
441 | ||
442 | =item unstable | |
443 | ||
444 | This indicates an "alpha" release that is under active development, but has | |
445 | been released for early feedback or testing and may be missing features or | |
446 | may have serious bugs. The distribution should not be installed over a | |
447 | stable release without an explicit request or other confirmation from a | |
448 | user. | |
449 | ||
450 | =back | |
451 | ||
452 | Consumers B<may> use this field to determine how to index the | |
453 | distribution for CPAN or other repositories in addition to or in | |
454 | replacement of heuristics based on version number or file name. | |
455 | ||
456 | =head3 version | |
457 | ||
458 | Example: | |
459 | ||
460 | version => '0.36' | |
461 | ||
462 | (Spec 1.0) [required] {Version} | |
463 | ||
464 | This field gives the version of the distribution to which the metadata | |
465 | structure refers. | |
466 | ||
467 | =head2 OPTIONAL FIELDS | |
468 | ||
469 | =head3 description | |
470 | ||
471 | Example: | |
472 | ||
473 | description => "Module::Build is a system for " | |
474 | . "building, testing, and installing Perl modules. " | |
475 | . "It is meant to ... blah blah blah ...", | |
476 | ||
477 | (Spec 2) [optional] {String} | |
478 | ||
479 | A longer, more complete description of the purpose or intended use of | |
480 | the distribution than the one provided by the C<abstract> key. | |
481 | ||
482 | =head3 keywords | |
483 | ||
484 | Example: | |
485 | ||
486 | keywords => [ qw/ toolchain cpan dual-life / ] | |
487 | ||
488 | (Spec 1.1) [optional] {List of zero or more Strings} | |
489 | ||
490 | A List of keywords that describe this distribution. Keywords | |
491 | B<must not> include whitespace. | |
492 | ||
493 | =head3 no_index | |
494 | ||
495 | Example: | |
496 | ||
497 | no_index => { | |
498 | file => [ 'My/Module.pm' ], | |
499 | directory => [ 'My/Private' ], | |
500 | package => [ 'My::Module::Secret' ], | |
501 | namespace => [ 'My::Module::Sample' ], | |
502 | } | |
503 | ||
504 | (Spec 1.2) [optional] {Map} | |
505 | ||
506 | This Map describes any files, directories, packages, and namespaces that | |
507 | are private to the packaging or implementation of the distribution and | |
508 | should be ignored by indexing or search tools. | |
509 | ||
510 | Valid subkeys are as follows: | |
511 | ||
512 | =over | |
513 | ||
514 | =item file | |
515 | ||
516 | A I<List> of relative paths to files. Paths B<must be> specified with | |
2d1dec40 | 517 | unix conventions. |
c05760c6 DG |
518 | |
519 | =item directory | |
520 | ||
521 | A I<List> of relative paths to directories. Paths B<must be> specified | |
2d1dec40 | 522 | with unix conventions. |
c05760c6 DG |
523 | |
524 | [ Note: previous editions of the spec had C<dir> instead of C<directory> ] | |
525 | ||
526 | =item package | |
527 | ||
528 | A I<List> of package names. | |
529 | ||
530 | =item namespace | |
531 | ||
532 | A I<List> of package namespaces, where anything below the namespace | |
533 | must be ignored, but I<not> the namespace itself. | |
534 | ||
535 | In the example above for C<no_index>, C<My::Module::Sample::Foo> would | |
536 | be ignored, but C<My::Module::Sample> would not. | |
537 | ||
538 | =back | |
539 | ||
540 | =head3 optional_features | |
541 | ||
542 | Example: | |
543 | ||
544 | optional_features => { | |
545 | sqlite => { | |
546 | description => 'Provides SQLite support', | |
547 | prereqs => { | |
548 | runtime => { | |
549 | requires => { | |
550 | 'DBD::SQLite' => '1.25' | |
551 | } | |
552 | } | |
553 | } | |
554 | } | |
555 | } | |
556 | ||
557 | (Spec 2) [optional] {Map} | |
558 | ||
559 | This Map describes optional features with incremental prerequisites. | |
560 | Each key of the C<optional_features> Map is a String used to identify | |
561 | the feature and each value is a Map with additional information about | |
562 | the feature. Valid subkeys include: | |
563 | ||
564 | =over | |
565 | ||
566 | =item description | |
567 | ||
568 | This is a String describing the feature. Every optional feature | |
569 | should provide a description | |
570 | ||
571 | =item prereqs | |
572 | ||
573 | This entry is required and has the same structure as that of the | |
574 | C<L</prereqs>> key. It provides a list of package requirements | |
575 | that must be satisfied for the feature to be supported or enabled. | |
576 | ||
2d1dec40 | 577 | There is one crucial restriction: the prereqs of an optional feature |
c05760c6 DG |
578 | B<must not> include C<configure> phase prereqs. |
579 | ||
580 | =back | |
581 | ||
582 | Consumers B<must not> include optional features as prerequisites without | |
85091ccc | 583 | explicit instruction from users (whether via interactive prompting, |
c05760c6 DG |
584 | a function parameter or a configuration value, etc. ). |
585 | ||
586 | If an optional feature is used by a consumer to add additional | |
587 | prerequisites, the consumer should merge the optional feature | |
588 | prerequisites into those given by the C<prereqs> key using the same | |
589 | semantics. See L</Merging and Resolving Prerequisites> for details on | |
590 | merging prerequisites. | |
591 | ||
592 | I<Suggestion for disuse:> Because there is currently no way for a | |
593 | distribution to specify a dependency on an optional feature of another | |
594 | dependency, the use of C<optional_feature> is discouraged. Instead, | |
595 | create a separate, installable distribution that ensures the desired | |
7ec7fa08 | 596 | feature is available. For example, if C<Foo::Bar> has a C<Baz> feature, |
c05760c6 DG |
597 | release a separate C<Foo-Bar-Baz> distribution that satisfies |
598 | requirements for the feature. | |
599 | ||
600 | =head3 prereqs | |
601 | ||
602 | Example: | |
603 | ||
604 | prereqs => { | |
605 | runtime => { | |
606 | requires => { | |
607 | 'perl' => '5.006', | |
608 | 'File::Spec' => '0.86', | |
609 | 'JSON' => '2.16', | |
610 | }, | |
611 | recommends => { | |
612 | 'JSON::XS' => '2.26', | |
613 | }, | |
614 | suggests => { | |
615 | 'Archive::Tar' => '0', | |
616 | }, | |
617 | }, | |
618 | build => { | |
619 | requires => { | |
620 | 'Alien::SDL' => '1.00', | |
621 | }, | |
622 | }, | |
623 | test => { | |
624 | recommends => { | |
625 | 'Test::Deep' => '0.10', | |
626 | }, | |
627 | } | |
628 | } | |
629 | ||
630 | (Spec 2) [optional] {Map} | |
631 | ||
632 | This is a Map that describes all the prerequisites of the distribution. | |
633 | The keys are phases of activity, such as C<configure>, C<build>, C<test> | |
634 | or C<runtime>. Values are Maps in which the keys name the type of | |
635 | prerequisite relationship such as C<requires>, C<recommends>, or | |
636 | C<suggests> and the value provides a set of prerequisite relations. The | |
637 | set of relations B<must> be specified as a Map of package names to | |
638 | version ranges. | |
639 | ||
640 | The full definition for this field is given in the L</Prereq Spec> | |
641 | section. | |
642 | ||
643 | =head3 provides | |
644 | ||
645 | Example: | |
646 | ||
647 | provides => { | |
648 | 'Foo::Bar' => { | |
649 | file => 'lib/Foo/Bar.pm', | |
7ec7fa08 | 650 | version => '0.27_02', |
c05760c6 DG |
651 | }, |
652 | 'Foo::Bar::Blah' => { | |
653 | file => 'lib/Foo/Bar/Blah.pm', | |
654 | }, | |
655 | 'Foo::Bar::Baz' => { | |
656 | file => 'lib/Foo/Bar/Baz.pm', | |
7ec7fa08 | 657 | version => '0.3', |
c05760c6 DG |
658 | }, |
659 | } | |
660 | ||
661 | (Spec 1.2) [optional] {Map} | |
662 | ||
663 | This describes all packages provided by this distribution. This | |
664 | information is used by distribution and automation mechanisms like | |
665 | PAUSE, CPAN, and search.cpan.org to build indexes saying in which | |
666 | distribution various packages can be found. | |
667 | ||
668 | The keys of C<provides> are package names that can be found within | |
a0831c78 CBW |
669 | the distribution. If a package name key is provided, it must |
670 | have a Map with the following valid subkeys: | |
c05760c6 DG |
671 | |
672 | =over | |
673 | ||
674 | =item file | |
675 | ||
a0831c78 CBW |
676 | This field is required. It must contain a Unix-style relative file path |
677 | from the root of the distribution directory to a file that contains or | |
678 | generates the package. | |
c05760c6 DG |
679 | |
680 | =item version | |
681 | ||
a0831c78 CBW |
682 | If it exists, this field must contains a I<Version> String for the |
683 | package. If the package does not have a C<$VERSION>, this field must | |
684 | be omitted. | |
c05760c6 DG |
685 | |
686 | =back | |
687 | ||
688 | =head3 resources | |
689 | ||
690 | Example: | |
691 | ||
692 | resources => { | |
693 | license => [ 'http://dev.perl.org/licenses/' ], | |
694 | homepage => 'http://sourceforge.net/projects/module-build', | |
695 | bugtracker => { | |
730e5b5b | 696 | web => 'http://rt.cpan.org/Public/Dist/Display.html?Name=CPAN-Meta', |
c05760c6 DG |
697 | mailto => 'meta-bugs@example.com', |
698 | }, | |
699 | repository => { | |
730e5b5b CBW |
700 | url => 'git://github.com/dagolden/cpan-meta.git', |
701 | web => 'http://github.com/dagolden/cpan-meta', | |
c05760c6 DG |
702 | type => 'git', |
703 | }, | |
704 | x_twitter => 'http://twitter.com/cpan_linked/', | |
705 | } | |
706 | ||
707 | (Spec 2) [optional] {Map} | |
708 | ||
709 | This field describes resources related to this distribution. | |
710 | ||
711 | Valid subkeys include: | |
712 | ||
713 | =over | |
714 | ||
715 | =item homepage | |
716 | ||
717 | The official home of this project on the web. | |
718 | ||
719 | =item license | |
720 | ||
721 | A List of I<URL>'s that relate to this distribution's license. As with the | |
722 | top-level C<license> field, distribution documentation should be consulted | |
723 | to clarify the interpretation of multiple licenses provided here. | |
724 | ||
725 | =item bugtracker | |
726 | ||
727 | This entry describes the bug tracking system for this distribution. It | |
728 | is a Map with the following valid keys: | |
729 | ||
730 | web - a URL pointing to a web front-end for the bug tracker | |
731 | mailto - an email address to which bugs can be sent | |
732 | ||
733 | =item repository | |
734 | ||
735 | This entry describes the source control repository for this distribution. It | |
736 | is a Map with the following valid keys: | |
737 | ||
738 | url - a URL pointing to the repository itself | |
739 | web - a URL pointing to a web front-end for the repository | |
740 | type - a lowercase string indicating the VCS used | |
741 | ||
742 | Because a url like C<http://myrepo.example.com/> is ambiguous as to | |
743 | type, producers should provide a C<type> whenever a C<url> key is given. | |
744 | The C<type> field should be the name of the most common program used | |
7ec7fa08 CBW |
745 | to work with the repository, e.g. C<git>, C<svn>, C<cvs>, C<darcs>, |
746 | C<bzr> or C<hg>. | |
c05760c6 DG |
747 | |
748 | =back | |
749 | ||
750 | =head2 DEPRECATED FIELDS | |
751 | ||
752 | =head3 build_requires | |
753 | ||
754 | I<(Deprecated in Spec 2)> [optional] {String} | |
755 | ||
756 | Replaced by C<prereqs> | |
757 | ||
758 | =head3 configure_requires | |
759 | ||
760 | I<(Deprecated in Spec 2)> [optional] {String} | |
761 | ||
762 | Replaced by C<prereqs> | |
763 | ||
764 | =head3 conflicts | |
765 | ||
766 | I<(Deprecated in Spec 2)> [optional] {String} | |
767 | ||
768 | Replaced by C<prereqs> | |
769 | ||
770 | =head3 distribution_type | |
771 | ||
772 | I<(Deprecated in Spec 2)> [optional] {String} | |
773 | ||
774 | This field indicated 'module' or 'script' but was considered | |
775 | meaningless, since many distributions are hybrids of several kinds of | |
776 | things. | |
777 | ||
778 | =head3 license_uri | |
779 | ||
780 | I<(Deprecated in Spec 1.2)> [optional] {URL} | |
781 | ||
782 | Replaced by C<license> in C<resources> | |
783 | ||
784 | =head3 private | |
785 | ||
786 | I<(Deprecated in Spec 1.2)> [optional] {Map} | |
787 | ||
788 | This field has been renamed to L</"no_index">. | |
789 | ||
790 | =head3 recommends | |
791 | ||
792 | I<(Deprecated in Spec 2)> [optional] {String} | |
793 | ||
794 | Replaced by C<prereqs> | |
795 | ||
796 | =head3 requires | |
797 | ||
798 | I<(Deprecated in Spec 2)> [optional] {String} | |
799 | ||
800 | Replaced by C<prereqs> | |
801 | ||
802 | =head1 VERSION NUMBERS | |
803 | ||
804 | =head2 Version Formats | |
805 | ||
806 | This section defines the Version type, used by several fields in the | |
807 | CPAN Meta Spec. | |
808 | ||
809 | Version numbers must be treated as strings, not numbers. For | |
810 | example, C<1.200> B<must not> be serialized as C<1.2>. Version | |
811 | comparison should be delegated to the Perl L<version> module, version | |
812 | 0.80 or newer. | |
813 | ||
814 | Unless otherwise specified, version numbers B<must> appear in one of two | |
815 | formats: | |
816 | ||
817 | =over | |
818 | ||
819 | =item Decimal versions | |
820 | ||
821 | Decimal versions are regular "decimal numbers", with some limitations. | |
822 | They B<must> be non-negative and B<must> begin and end with a digit. A | |
823 | single underscore B<may> be included, but B<must> be between two digits. | |
824 | They B<must not> use exponential notation ("1.23e-2"). | |
825 | ||
826 | version => '1.234' # OK | |
827 | version => '1.23_04' # OK | |
828 | ||
829 | version => '1.23_04_05' # Illegal | |
830 | version => '1.' # Illegal | |
831 | version => '.1' # Illegal | |
832 | ||
833 | =item Dotted-integer versions | |
834 | ||
835 | Dotted-integer (also known as dotted-decimal) versions consist of | |
836 | positive integers separated by full stop characters (i.e. "dots", | |
837 | "periods" or "decimal points"). This are equivalent in format to Perl | |
838 | "v-strings", with some additional restrictions on form. They must be | |
839 | given in "normal" form, which has a leading "v" character and at least | |
840 | three integer components. To retain a one-to-one mapping with decimal | |
841 | versions, all components after the first B<should> be restricted to the | |
842 | range 0 to 999. The final component B<may> be separated by an | |
843 | underscore character instead of a period. | |
844 | ||
845 | version => 'v1.2.3' # OK | |
846 | version => 'v1.2_3' # OK | |
847 | version => 'v1.2.3.4' # OK | |
848 | version => 'v1.2.3_4' # OK | |
849 | version => 'v2009.10.31' # OK | |
850 | ||
851 | version => 'v1.2' # Illegal | |
852 | version => '1.2.3' # Illegal | |
853 | version => 'v1.2_3_4' # Illegal | |
854 | version => 'v1.2009.10.31' # Not recommended | |
855 | ||
856 | =back | |
857 | ||
858 | =head2 Version Ranges | |
859 | ||
860 | Some fields (prereq, optional_features) indicate the particular | |
861 | version(s) of some other module that may be required as a prerequisite. | |
862 | This section details the Version Range type used to provide this | |
863 | information. | |
864 | ||
865 | The simplest format for a Version Range is just the version | |
866 | number itself, e.g. C<2.4>. This means that B<at least> version 2.4 | |
867 | must be present. To indicate that B<any> version of a prerequisite is | |
868 | okay, even if the prerequisite doesn't define a version at all, use | |
869 | the version C<0>. | |
870 | ||
871 | Alternatively, a version range B<may> use the operators E<lt> (less than), | |
872 | E<lt>= (less than or equal), E<gt> (greater than), E<gt>= (greater than | |
873 | or equal), == (equal), and != (not equal). For example, the | |
874 | specification C<E<lt> 2.0> means that any version of the prerequisite | |
875 | less than 2.0 is suitable. | |
876 | ||
877 | For more complicated situations, version specifications B<may> be AND-ed | |
878 | together using commas. The specification C<E<gt>= 1.2, != 1.5, E<lt> | |
879 | 2.0> indicates a version that must be B<at least> 1.2, B<less than> 2.0, | |
880 | and B<not equal to> 1.5. | |
881 | ||
882 | =head1 PREREQUISITES | |
883 | ||
884 | =head2 Prereq Spec | |
885 | ||
886 | The C<prereqs> key in the top-level metadata and within | |
887 | C<optional_features> define the relationship between a distribution and | |
888 | other packages. The prereq spec structure is a hierarchical data | |
889 | structure which divides prerequisites into I<Phases> of activity in the | |
890 | installation process and I<Relationships> that indicate how | |
891 | prerequisites should be resolved. | |
892 | ||
893 | For example, to specify that C<Data::Dumper> is C<required> during the | |
894 | C<test> phase, this entry would appear in the distribution metadata: | |
895 | ||
896 | prereqs => { | |
897 | test => { | |
898 | requires => { | |
899 | 'Data::Dumper' => '2.00' | |
900 | } | |
901 | } | |
902 | } | |
903 | ||
904 | =head3 Phases | |
905 | ||
906 | Requirements for regular use must be listed in the C<runtime> phase. | |
907 | Other requirements should be listed in the earliest stage in which they | |
908 | are required and consumers must accumulate and satisfy requirements | |
909 | across phases before executing the activity. For example, C<build> | |
910 | requirements must also be available during the C<test> phase. | |
911 | ||
912 | before action requirements that must be met | |
913 | ---------------- -------------------------------- | |
914 | perl Build.PL configure | |
915 | perl Makefile.PL | |
916 | ||
917 | make configure, runtime, build | |
918 | Build | |
919 | ||
920 | make test configure, runtime, build, test | |
921 | Build test | |
922 | ||
923 | Consumers that install the distribution must ensure that | |
924 | I<runtime> requirements are also installed and may install | |
925 | dependencies from other phases. | |
926 | ||
927 | after action requirements that must be met | |
928 | ---------------- -------------------------------- | |
929 | make install runtime | |
930 | Build install | |
931 | ||
932 | =over | |
933 | ||
934 | =item configure | |
935 | ||
936 | The configure phase occurs before any dynamic configuration has been | |
937 | attempted. Libraries required by the configure phase B<must> be | |
938 | available for use before the distribution building tool has been | |
939 | executed. | |
940 | ||
941 | =item build | |
942 | ||
943 | The build phase is when the distribution's source code is compiled (if | |
944 | necessary) and otherwise made ready for installation. | |
945 | ||
946 | =item test | |
947 | ||
948 | The test phase is when the distribution's automated test suite is run. | |
949 | Any library that is needed only for testing and not for subsequent use | |
950 | should be listed here. | |
951 | ||
952 | =item runtime | |
953 | ||
954 | The runtime phase refers not only to when the distribution's contents | |
955 | are installed, but also to its continued use. Any library that is a | |
956 | prerequisite for regular use of this distribution should be indicated | |
957 | here. | |
958 | ||
959 | =item develop | |
960 | ||
961 | The develop phase's prereqs are libraries needed to work on the | |
962 | distribution's source code as its author does. These tools might be | |
963 | needed to build a release tarball, to run author-only tests, or to | |
964 | perform other tasks related to developing new versions of the | |
965 | distribution. | |
966 | ||
967 | =back | |
968 | ||
969 | =head3 Relationships | |
970 | ||
971 | =over | |
972 | ||
973 | =item requires | |
974 | ||
975 | These dependencies B<must> be installed for proper completion of the | |
976 | phase. | |
977 | ||
978 | =item recommends | |
979 | ||
980 | Recommended dependencies are I<strongly> encouraged and should be | |
981 | satisfied except in resource constrained environments. | |
982 | ||
983 | =item suggests | |
984 | ||
985 | These dependencies are optional, but are suggested for enhanced operation | |
986 | of the described distribution. | |
987 | ||
988 | =item conflicts | |
989 | ||
990 | These libraries cannot be installed when the phase is in operation. | |
991 | This is a very rare situation, and the C<conflicts> relationship should | |
992 | be used with great caution, or not at all. | |
993 | ||
994 | =back | |
995 | ||
996 | =head2 Merging and Resolving Prerequisites | |
997 | ||
998 | Whenever metadata consumers merge prerequisites, either from different | |
999 | phases or from C<optional_features>, they should merged in a way which | |
1000 | preserves the intended semantics of the prerequisite structure. Generally, | |
1001 | this means concatenating the version specifications using commas, as | |
1002 | described in the L<Version Ranges> section. | |
1003 | ||
1004 | Another subtle error that can occur in resolving prerequisites comes from | |
1005 | the way that modules in prerequisites are indexed to distribution files on | |
1006 | CPAN. When a module is deleted from a distribution, prerequisites calling | |
7ec7fa08 | 1007 | for that module could indicate an older distribution should be installed, |
c05760c6 DG |
1008 | potentially overwriting files from a newer distribution. |
1009 | ||
1010 | For example, as of Oct 31, 2009, the CPAN index file contained these | |
1011 | module-distribution mappings: | |
1012 | ||
1013 | Class::MOP 0.94 D/DR/DROLSKY/Class-MOP-0.94.tar.gz | |
1014 | Class::MOP::Class 0.94 D/DR/DROLSKY/Class-MOP-0.94.tar.gz | |
1015 | Class::MOP::Class::Immutable 0.04 S/ST/STEVAN/Class-MOP-0.36.tar.gz | |
1016 | ||
1017 | Consider the case where "Class::MOP" 0.94 is installed. If a | |
1018 | distribution specified "Class::MOP::Class::Immutable" as a prerequisite, | |
1019 | it could result in Class-MOP-0.36.tar.gz being installed, overwriting | |
1020 | any files from Class-MOP-0.94.tar.gz. | |
1021 | ||
1022 | Consumers of metadata B<should> test whether prerequisites would result | |
1023 | in installed module files being "downgraded" to an older version and | |
1024 | B<may> warn users or ignore the prerequisite that would cause such a | |
1025 | result. | |
1026 | ||
1027 | =head1 SERIALIZATION | |
1028 | ||
1029 | Distribution metadata should be serialized (as a hashref) as | |
1030 | JSON-encoded data and packaged with distributions as the file | |
1031 | F<META.json>. | |
1032 | ||
1033 | In the past, the distribution metadata structure had been packed with | |
1034 | distributions as F<META.yml>, a file in the YAML Tiny format (for which, | |
1035 | see L<YAML::Tiny>). Tools that consume distribution metadata from disk | |
1036 | should be capable of loading F<META.yml>, but should prefer F<META.json> | |
1037 | if both are found. | |
1038 | ||
1039 | =head1 NOTES FOR IMPLEMENTORS | |
1040 | ||
1041 | =head2 Extracting Version Numbers from Perl Modules | |
1042 | ||
1043 | To get the version number from a Perl module, consumers should use the | |
730e5b5b CBW |
1044 | C<< MM->parse_version($file) >> method provided by |
1045 | L<ExtUtils::MakeMaker> or L<Module::Metadata>. For example, for the | |
1046 | module given by C<$mod>, the version may be retrieved in one of the | |
1047 | following ways: | |
c05760c6 DG |
1048 | |
1049 | # via ExtUtils::MakeMaker | |
1050 | my $file = MM->_installed_file_for_module($mod); | |
1051 | my $version = MM->parse_version($file) | |
1052 | ||
1053 | The private C<_installed_file_for_module> method may be replaced with | |
1054 | other methods for locating a module in C<@INC>. | |
1055 | ||
730e5b5b CBW |
1056 | # via Module::Metadata |
1057 | my $info = Module::Metadata->new_from_module($mod); | |
c05760c6 DG |
1058 | my $version = $info->version; |
1059 | ||
1060 | If only a filename is available, the following approach may be used: | |
1061 | ||
1062 | # via Module::Build | |
730e5b5b | 1063 | my $info = Module::Metadata->new_from_file($file); |
c05760c6 DG |
1064 | my $version = $info->version; |
1065 | ||
1066 | =head2 Comparing Version Numbers | |
1067 | ||
1068 | The L<version> module provides the most reliable way to compare version | |
1069 | numbers in all the various ways they might be provided or might exist | |
1070 | within modules. Given two strings containing version numbers, C<$v1> and | |
1071 | C<$v2>, they should be converted to C<version> objects before using | |
1072 | ordinary comparison operators. For example: | |
1073 | ||
1074 | use version; | |
1075 | if ( version->new($v1) <=> version->new($v2) ) { | |
1076 | print "Versions are not equal\n"; | |
1077 | } | |
1078 | ||
1079 | If the only comparison needed is whether an installed module is of a | |
1080 | sufficiently high version, a direct test may be done using the string | |
1081 | form of C<eval> and the C<use> function. For example, for module C<$mod> | |
1082 | and version prerequisite C<$prereq>: | |
1083 | ||
1084 | if ( eval "use $mod $prereq (); 1" ) { | |
1085 | print "Module $mod version is OK.\n"; | |
1086 | } | |
1087 | ||
1088 | If the values of C<$mod> and C<$prereq> have not been scrubbed, however, | |
1089 | this presents security implications. | |
1090 | ||
1091 | =head1 SEE ALSO | |
1092 | ||
1093 | CPAN, L<http://www.cpan.org/> | |
1094 | ||
1095 | CPAN.pm, L<http://search.cpan.org/dist/CPAN/> | |
1096 | ||
1097 | CPANPLUS, L<http://search.cpan.org/dist/CPANPLUS/> | |
1098 | ||
1099 | ExtUtils::MakeMaker, L<http://search.cpan.org/dist/ExtUtils-MakeMaker/> | |
1100 | ||
1101 | Module::Build, L<http://search.cpan.org/dist/Module-Build/> | |
1102 | ||
1103 | Module::Install, L<http://search.cpan.org/dist/Module-Install/> | |
1104 | ||
1105 | JSON, L<http://json.org/> | |
1106 | ||
1107 | YAML, L<http://www.yaml.org/> | |
1108 | ||
53bb269a | 1109 | =head1 HISTORY |
c05760c6 DG |
1110 | |
1111 | Ken Williams wrote the original CPAN Meta Spec (also known as the | |
1112 | "META.yml spec") in 2003 and maintained it through several revisions | |
1113 | with input from various members of the community. In 2005, Randy | |
1114 | Sims redrafted it from HTML to POD for the version 1.2 release. Ken | |
1115 | continued to maintain the spec through version 1.4. | |
1116 | ||
1117 | In late 2009, David Golden organized the version 2 proposal review | |
1118 | process. David and Ricardo Signes drafted the final version 2 spec | |
1119 | in April 2010 based on the version 1.4 spec and patches contributed | |
1120 | during the proposal process. | |
1121 | ||
c05760c6 DG |
1122 | =head1 AUTHORS |
1123 | ||
1124 | =over 4 | |
1125 | ||
1126 | =item * | |
1127 | ||
1128 | David Golden <dagolden@cpan.org> | |
1129 | ||
1130 | =item * | |
1131 | ||
1132 | Ricardo Signes <rjbs@cpan.org> | |
1133 | ||
1134 | =back | |
1135 | ||
1136 | =head1 COPYRIGHT AND LICENSE | |
1137 | ||
1138 | This software is copyright (c) 2010 by David Golden and Ricardo Signes. | |
1139 | ||
1140 | This is free software; you can redistribute it and/or modify it under | |
1141 | the same terms as the Perl 5 programming language system itself. | |
1142 | ||
1143 | =cut |