diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/CPAN::Meta::History::Meta_1_2.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/CPAN::Meta::History::Meta_1_2.3pm | 709 |
1 files changed, 709 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/CPAN::Meta::History::Meta_1_2.3pm b/upstream/mageia-cauldron/man3pm/CPAN::Meta::History::Meta_1_2.3pm new file mode 100644 index 00000000..7362de78 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/CPAN::Meta::History::Meta_1_2.3pm @@ -0,0 +1,709 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "CPAN::Meta::History::Meta_1_2 3pm" +.TH CPAN::Meta::History::Meta_1_2 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CPAN::Meta::History::Meta_1_2 \- Version 1.2 metadata specification for META.yml +.SH PREFACE +.IX Header "PREFACE" +This is a historical copy of the version 1.2 specification for \fIMETA.yml\fR +files, copyright by Ken Williams and licensed under the same terms as Perl +itself. +.PP +Modifications from the original: +.IP \(bu 4 +Various spelling corrections +.IP \(bu 4 +Include list of valid licenses from Module::Build 0.2611 rather than +linking to the module, with minor updates to text and links to reflect +versions at the time of publication. +.IP \(bu 4 +Fixed some dead links to point to active resources. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 10 +\& \-\-\- #YAML:1.0 +\& name: Module\-Build +\& abstract: Build and install Perl modules +\& version: 0.20 +\& author: +\& \- Ken Williams <kwilliams@cpan.org> +\& license: perl +\& distribution_type: module +\& requires: +\& Config: 0 +\& Cwd: 0 +\& Data::Dumper: 0 +\& ExtUtils::Install: 0 +\& File::Basename: 0 +\& File::Compare: 0 +\& File::Copy: 0 +\& File::Find: 0 +\& File::Path: 0 +\& File::Spec: 0 +\& IO::File: 0 +\& perl: 5.005_03 +\& recommends: +\& Archive::Tar: 1.00 +\& ExtUtils::Install: 0.3 +\& ExtUtils::ParseXS: 2.02 +\& Pod::Text: 0 +\& YAML: 0.35 +\& build_requires: +\& Test: 0 +\& urls: +\& license: http://dev.perl.org/licenses/ +\& meta\-spec: +\& version: 1.2 +\& url: http://module\-build.sourceforge.net/META\-spec\-v1.2.html +\& generated_by: Module::Build version 0.20 +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This document describes version 1.2 of the \fIMETA.yml\fR specification. +.PP +The \fIMETA.yml\fR file describes important properties of contributed +Perl distributions such as the ones found on CPAN. It is typically +created by tools like Module::Build, Module::Install, and +ExtUtils::MakeMaker. +.PP +The fields in the \fIMETA.yml\fR file are meant to be helpful for people +maintaining module collections (like CPAN), for people writing +installation tools (like CPAN.pm or CPANPLUS), or just for people who +want to know some stuff about a distribution before downloading it and +starting to install it. +.PP +\&\fINote: The latest stable version of this specification can always be +found at <http://module\-build.sourceforge.net/META\-spec\-current.html>, +and the latest development version (which may include things that +won't make it into the stable version can always be found at +<http://module\-build.sourceforge.net/META\-spec\-blead.html>.\fR +.SH FORMAT +.IX Header "FORMAT" +\&\fIMETA.yml\fR files are written in the YAML format (see +<http://www.yaml.org/>). +.PP +See the following links to learn why we chose YAML instead of, say, +XML or Data::Dumper: +.IP \(bu 4 +Module::Build design plans <http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg407.html> +.IP \(bu 4 +Not keen on YAML <http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1353.html> +.IP \(bu 4 +META Concerns <http://www.nntp.perl.org/group/perl.module-authors/2003/11/msg1385.html> +.SH TERMINOLOGY +.IX Header "TERMINOLOGY" +.IP distribution 4 +.IX Item "distribution" +This is the primary object described by the \fIMETA.yml\fR +specification. In the context of this document it usually refers to a +collection of modules, scripts, and/or documents that are distributed +for other developers to use. +.IP module 4 +.IX Item "module" +This refers to a reusable library of code typically contained in a +single file. Currently, we primarily talk of perl modules, but this +specification should be open enough to apply to other languages as +well (ex. python, ruby). +.SH "VERSION SPECIFICATIONS" +.IX Header "VERSION SPECIFICATIONS" +Some fields require a version specification (ex. "requires", +"recommends", "build_requires", etc.). This section details the +version specifications that are currently supported. +.PP +If a single version is listed, then that version is considered to be +the minimum version supported. +.PP +If 0 is given as the version number, then any version is supported. +.PP +Additionally, for more complicated requirements, the specification +supports a list of versions, each of which may be optionally preceded +by a relational operator. +.PP +Supported operators include < (less than), <= (less than or +equal), > (greater than), >= (greater than or equal), == (equal), and != +(not equal). +.PP +If a list is given then it is evaluated from left to right so that any +specifications in the list that conflict with a previous specification +are overridden by the later. +.PP +Examples: +.PP +.Vb 1 +\& >= 1.2, != 1.5, < 2.0 +.Ve +.PP +Any version from version 1.2 onward, except version 1.5, that also +precedes version 2.0. +.SH HEADER +.IX Header "HEADER" +The first line of a \fIMETA.yml\fR file should be a valid YAML document +header like \f(CW"\-\-\- #YAML:1.0"\fR. +.SH FIELDS +.IX Header "FIELDS" +The rest of the \fIMETA.yml\fR file is one big YAML mapping whose keys +are described here. +.SS meta-spec +.IX Subsection "meta-spec" +Example: +.PP +.Vb 3 +\& meta\-spec: +\& version: 1.2 +\& url: http://module\-build.sourceforge.net/META\-spec\-v1.2.html +.Ve +.PP +(Spec 1.1) [required] {URL} This field indicates the location of the +version of the META.yml specification used. +.SS name +.IX Subsection "name" +Example: +.PP +.Vb 1 +\& name: Module\-Build +.Ve +.PP +(Spec 1.0) [required] {string} The name of the distribution which is often +created by taking the "main module" in the distribution and changing +"::" to "\-". Sometimes it's completely different, however, as in the +case of the libwww-perl distribution (see +<http://search.cpan.org/author/GAAS/libwww\-perl/>). +.SS version +.IX Subsection "version" +Example: +.PP +.Vb 1 +\& version: 0.20 +.Ve +.PP +(Spec 1.0) [required] {version} The version of the distribution to which the +\&\fIMETA.yml\fR file refers. +.SS abstract +.IX Subsection "abstract" +Example: +.PP +.Vb 1 +\& abstract: Build and install Perl modules. +.Ve +.PP +(Spec 1.1) [required] {string} A short description of the purpose of the +distribution. +.SS author +.IX Subsection "author" +Example: +.PP +.Vb 2 +\& author: +\& \- Ken Williams <kwilliams@cpan.org> +.Ve +.PP +(Spec 1.1) [required] {list of strings} A YAML sequence indicating the author(s) of the +distribution. The preferred form is author-name <email\-address>. +.SS license +.IX Subsection "license" +Example: +.PP +.Vb 1 +\& license: perl +.Ve +.PP +(Spec 1.0) [required] {string} The license under which this distribution may be +used and redistributed. +.PP +Must be one of the following licenses: +.IP perl 4 +.IX Item "perl" +The distribution may be copied and redistributed under the same terms as perl +itself (this is by far the most common licensing option for modules on CPAN). +This is a dual license, in which the user may choose between either the GPL +version 1 or the Artistic version 1 license. +.IP gpl 4 +.IX Item "gpl" +The distribution is distributed under the terms of the GNU General Public +License version 2 (<http://opensource.org/licenses/GPL\-2.0>). +.IP lgpl 4 +.IX Item "lgpl" +The distribution is distributed under the terms of the GNU Lesser General +Public License version 2 (<http://opensource.org/licenses/LGPL\-2.1>). +.IP artistic 4 +.IX Item "artistic" +The distribution is licensed under the Artistic License version 1, as specified +by the Artistic file in the standard perl distribution +(<http://opensource.org/licenses/Artistic\-Perl\-1.0>). +.IP bsd 4 +.IX Item "bsd" +The distribution is licensed under the BSD 3\-Clause License +(<http://opensource.org/licenses/BSD\-3\-Clause>). +.IP open_source 4 +.IX Item "open_source" +The distribution is licensed under some other Open Source Initiative-approved +license listed at <http://www.opensource.org/licenses/>. +.IP unrestricted 4 +.IX Item "unrestricted" +The distribution is licensed under a license that is \fBnot\fR approved by +www.opensource.org <http://www.opensource.org/> but that allows distribution +without restrictions. +.IP restrictive 4 +.IX Item "restrictive" +The distribution may not be redistributed without special permission from the +author and/or copyright holder. +.SS distribution_type +.IX Subsection "distribution_type" +Example: +.PP +.Vb 1 +\& distribution_type: module +.Ve +.PP +(Spec 1.0) [optional] {string} What kind of stuff is contained in this +distribution. Most things on CPAN are \f(CW\*(C`module\*(C'\fRs (which can also mean +a collection of modules), but some things are \f(CW\*(C`script\*(C'\fRs. +.PP +Unfortunately this field is basically meaningless, since many +distributions are hybrids of several kinds of things, or some new +thing, or subjectively different in focus depending on who's using +them. Tools like Module::Build and MakeMaker will likely stop +generating this field. +.SS requires +.IX Subsection "requires" +Example: +.PP +.Vb 3 +\& requires: +\& Data::Dumper: 0 +\& File::Find: 1.03 +.Ve +.PP +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution requires for proper operation. The keys are the module +names, and the values are version specifications as described in +Module::Build for the "requires" parameter. +.SS recommends +.IX Subsection "recommends" +Example: +.PP +.Vb 3 +\& recommends: +\& Data::Dumper: 0 +\& File::Find: 1.03 +.Ve +.PP +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules this +distribution recommends for enhanced operation. +.PP +\&\fIALTERNATIVE: It may be desirable to present to the user which +features depend on which modules so they can make an informed +decision about which recommended modules to install.\fR +.PP +Example: +.PP +.Vb 9 +\& optional_features: +\& \- foo: +\& description: Provides the ability to blah. +\& requires: +\& Data::Dumper: 0 +\& File::Find: 1.03 +\& \- bar: +\& description: This feature is not available on this platform. +\& excludes_os: MSWin32 +.Ve +.PP +\&\fI(Spec 1.1) [optional] {map} A YAML sequence of names for optional features +which are made available when its requirements are met. For each +feature a description is provided along with any of "requires", +"build_requires", "conflicts", \fR\f(CI\*(C`requires_packages\*(C'\fR\fI, +\&\fR\f(CI\*(C`requires_os\*(C'\fR\fI, and \fR\f(CI\*(C`excludes_os\*(C'\fR\fI which have the same meaning in +this subcontext as described elsewhere in this document.\fR +.SS build_requires +.IX Subsection "build_requires" +Example: +.PP +.Vb 3 +\& build_requires: +\& Data::Dumper: 0 +\& File::Find: 1.03 +.Ve +.PP +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules +required for building and/or testing of this distribution. These +dependencies are not required after the module is installed. +.SS conflicts +.IX Subsection "conflicts" +Example: +.PP +.Vb 3 +\& conflicts: +\& Data::Dumper: 0 +\& File::Find: 1.03 +.Ve +.PP +(Spec 1.0) [optional] {map} A YAML mapping indicating the Perl modules that +cannot be installed while this distribution is installed. This is a +pretty uncommon situation. +.SS dynamic_config +.IX Subsection "dynamic_config" +Example: +.PP +.Vb 1 +\& dynamic_config: 0 +.Ve +.PP +(Spec 1.0) [optional] {boolean} A boolean flag indicating whether a \fIBuild.PL\fR +or \fIMakefile.PL\fR (or similar) must be executed when building this +distribution, or whether it can be built, tested and installed solely +from consulting its +metadata file. The main reason to set this to a true value if that +your module performs some dynamic configuration (asking questions, +sensing the environment, etc.) as part of its build/install process. +.PP +Currently Module::Build doesn't actually do anything with this flag +\&\- it's probably going to be up to higher-level tools like CPAN +to do something useful with it. It can potentially bring lots of +security, packaging, and convenience improvements. +.PP +If this field is omitted, it defaults to 1 (true). +.SS private +.IX Subsection "private" +\&\fI(Deprecated)\fR (Spec 1.0) [optional] {map} This field has been renamed to +"no_index". See below. +.SS provides +.IX Subsection "provides" +Example: +.PP +.Vb 9 +\& provides: +\& Foo::Bar: +\& file: lib/Foo/Bar.pm +\& version: 0.27_02 +\& Foo::Bar::Blah: +\& file: lib/Foo/Bar/Blah.pm +\& Foo::Bar::Baz: +\& file: lib/Foo/Bar/Baz.pm +\& version: 0.3 +.Ve +.PP +(Spec 1.1) [optional] {map} A YAML mapping that describes all packages +provided by this distribution. This information can be (and, in some +cases, is) used by distribution and automation mechanisms like PAUSE, +CPAN, and search.cpan.org to build indexes saying in which +distribution various packages can be found. +.PP +When using tools like Module::Build that can generate the +\&\f(CW\*(C`provides\*(C'\fR mapping for your distribution automatically, make sure you +examine what it generates to make sure it makes sense \- indexers will +usually trust the \f(CW\*(C`provides\*(C'\fR field if it's present, rather than +scanning through the distribution files themselves to figure out +packages and versions. This is a good thing, because it means you can +use the \f(CW\*(C`provides\*(C'\fR field to tell the indexers precisely what you want +indexed about your distribution, rather than relying on them to +essentially guess what you want indexed. +.SS no_index +.IX Subsection "no_index" +Example: +.PP +.Vb 9 +\& no_index: +\& file: +\& \- My/Module.pm +\& dir: +\& \- My/Private +\& package: +\& \- My::Module::Stuff +\& namespace: +\& \- My::Module::Stuff +.Ve +.PP +(Spec 1.1) [optional] {map} A YAML mapping that describes any files, +directories, packages, and namespaces that are private +(i.e. implementation artifacts) that are not of interest to searching +and indexing tools. This is useful when no \f(CW\*(C`provides\*(C'\fR field is +present. +.PP +\&\fI(Note: I'm not actually sure who looks at this field, or exactly +what they do with it. This spec could be off in some way from actual +usage.)\fR +.PP +\fIfile\fR +.IX Subsection "file" +.PP +(Spec 1.1) [optional] Exclude any listed file(s). +.PP +\fIdir\fR +.IX Subsection "dir" +.PP +(Spec 1.1) [optional] Exclude anything below the listed +directory(ies). +.PP +\fIpackage\fR +.IX Subsection "package" +.PP +(Spec 1.1) [optional] Exclude the listed package(s). +.PP +\fInamespace\fR +.IX Subsection "namespace" +.PP +(Spec 1.1) [optional] Excludes anything below the listed namespace(s), +but \fInot\fR the listed namespace(s) its self. +.SS keywords +.IX Subsection "keywords" +Example: +.PP +.Vb 4 +\& keywords: +\& \- make +\& \- build +\& \- install +.Ve +.PP +(Spec 1.1) [optional] {list} A sequence of keywords/phrases that describe +this distribution. +.SS resources +.IX Subsection "resources" +Example: +.PP +.Vb 5 +\& resources: +\& license: http://dev.perl.org/licenses/ +\& homepage: http://sourceforge.net/projects/module\-build +\& bugtracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module\-Build +\& MailingList: http://lists.sourceforge.net/lists/listinfo/module\-build\-general +.Ve +.PP +(Spec 1.1) [optional] {map} A mapping of any URL resources related to +this distribution. All-lower-case keys, such as \f(CW\*(C`homepage\*(C'\fR, +\&\f(CW\*(C`license\*(C'\fR, and \f(CW\*(C`bugtracker\*(C'\fR, are reserved by this specification, as +they have "official" meanings defined here in this specification. If +you'd like to add your own "special" entries (like the "MailingList" +entry above), use at least one upper-case letter. +.PP +The current set of official keys is: +.IP homepage 2 +.IX Item "homepage" +The official home of this project on the web. +.IP license 2 +.IX Item "license" +An URL for an official statement of this distribution's license. +.IP bugtracker 2 +.IX Item "bugtracker" +An URL for a bug tracker (e.g. Bugzilla or RT queue) for this project. +.SS generated_by +.IX Subsection "generated_by" +Example: +.PP +.Vb 1 +\& generated_by: Module::Build version 0.20 +.Ve +.PP +(Spec 1.0) [required] {string} Indicates the tool that was used to create this +\&\fIMETA.yml\fR file. It's good form to include both the name of the tool +and its version, but this field is essentially opaque, at least for +the moment. If \fIMETA.yml\fR was generated by hand, it is suggested that +the author be specified here. +.PP +[Note: My \fImeta_stats.pl\fR script which I use to gather statistics +regarding \fIMETA.yml\fR usage prefers the form listed above, i.e. it +splits on /\es+version\es+/ taking the first field as the name of the +tool that generated the file and the second field as version of that +tool. RWS] +.SH "SEE ALSO" +.IX Header "SEE ALSO" +CPAN <http://www.cpan.org/> +.PP +CPAN.pm +.PP +CPANPLUS +.PP +Data::Dumper +.PP +ExtUtils::MakeMaker +.PP +Module::Build +.PP +Module::Install +.PP +XML <http://www.w3.org/XML/> +.PP +YAML <http://www.yaml.org/> +.SH HISTORY +.IX Header "HISTORY" +.IP "March 14, 2003 (Pi day)" 4 +.IX Item "March 14, 2003 (Pi day)" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Created version 1.0 of this document. +.RE +.RS 4 +.RE +.IP "May 8, 2003" 4 +.IX Item "May 8, 2003" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Added the "dynamic_config" field, which was missing from the initial +version. +.RE +.RS 4 +.RE +.IP "November 13, 2003" 4 +.IX Item "November 13, 2003" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Added more YAML rationale articles. +.IP \(bu 2 +Fixed existing link to YAML discussion thread to point to new +<http://nntp.x.perl.org/group/> site. +.IP \(bu 2 +Added and deprecated the "private" field. +.IP \(bu 2 +Added "abstract", \f(CW\*(C`configure\*(C'\fR, \f(CW\*(C`requires_packages\*(C'\fR, +\&\f(CW\*(C`requires_os\*(C'\fR, \f(CW\*(C`excludes_os\*(C'\fR, and "no_index" fields. +.IP \(bu 2 +Bumped version. +.RE +.RS 4 +.RE +.IP "November 16, 2003" 4 +.IX Item "November 16, 2003" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Added \f(CW\*(C`generation\*(C'\fR, \f(CW\*(C`authored_by\*(C'\fR fields. +.IP \(bu 2 +Add alternative proposal to the "recommends" field. +.IP \(bu 2 +Add proposal for a \f(CW\*(C`requires_build_tools\*(C'\fR field. +.RE +.RS 4 +.RE +.IP "December 9, 2003" 4 +.IX Item "December 9, 2003" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Added link to latest version of this specification on CPAN. +.IP \(bu 2 +Added section "VERSION SPECIFICATIONS". +.IP \(bu 2 +Chang name from Module::Build::META\-spec to CPAN::META::Specification. +.IP \(bu 2 +Add proposal for \f(CW\*(C`auto_regenerate\*(C'\fR field. +.RE +.RS 4 +.RE +.IP "December 15, 2003" 4 +.IX Item "December 15, 2003" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Add \f(CW\*(C`index\*(C'\fR field as a compliment to "no_index" +.IP \(bu 2 +Add "keywords" field as a means to aid searching distributions. +.IP \(bu 2 +Add "TERMINOLOGY" section to explain certain terms that may be +ambiguous. +.RE +.RS 4 +.RE +.IP "July 26, 2005" 4 +.IX Item "July 26, 2005" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Removed a bunch of items (generation, requires_build_tools, +requires_packages, configure, requires_os, excludes_os, +auto_regenerate) that have never actually been supported, but were +more like records of brainstorming. +.IP \(bu 2 +Changed \f(CW\*(C`authored_by\*(C'\fR to "author", since that's always been what +it's actually called in actual \fIMETA.yml\fR files. +.IP \(bu 2 +Added the "==" operator to the list of supported version-checking +operators. +.IP \(bu 2 +Noted that the "distribution_type" field is basically meaningless, +and shouldn't really be used. +.IP \(bu 2 +Clarified "dynamic_config" a bit. +.RE +.RS 4 +.RE +.IP "August 23, 2005" 4 +.IX Item "August 23, 2005" +.RS 4 +.PD 0 +.IP \(bu 2 +.PD +Removed the name \f(CW\*(C`CPAN::META::Specification\*(C'\fR, since that implies a +module that doesn't actually exist. +.RE +.RS 4 +.RE |