CPAN::Meta::History::Meta_1_1(3p) Perl Programmers Reference Guide #
CPAN::Meta::History::Meta_1_1(3p) Perl Programmers Reference Guide
NNAAMMEE #
CPAN::Meta::History::Meta_1_1 - Version 1.1 metadata specification for
META.yml
PPRREEFFAACCEE #
This is a historical copy of the version 1.1 specification for _M_E_T_A_._y_m_l
files, copyright by Ken Williams and licensed under the same terms as
Perl itself.
Modifications from the original:
• Conversion from the original HTML to POD format
• Include list of valid licenses from Module::Build 0.18 rather than
linking to the module, with minor updates to text and links to
reflect versions at the time of publication.
• Fixed some dead links to point to active resources.
DDEESSCCRRIIPPTTIIOONN #
This document describes version 1.1 of the _M_E_T_A_._y_m_l specification.
The _M_E_T_A_._y_m_l file describes important properties of contributed Perl
distributions such as the ones found on CPAN <http://www.cpan.org>. It
is typically created by tools like Module::Build and ExtUtils::MakeMaker.
The fields in the _M_E_T_A_._y_m_l file are meant to be helpful to people
maintaining module collections (like CPAN), for people writing
installation tools (like CPAN or CPANPLUS), or just people who want to
know some stuff about a distribution before downloading it and starting
to install it.
FFoorrmmaatt _M_E_T_A_._y_m_l files are written in the YAML http://www.yaml.org/ format. The reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in this thread http://www.nntp.perl.org/group/perl.makemaker/2002/04/msg406.html on the MakeMaker mailing list.
The first line of a _M_E_T_A_._y_m_l file should be a valid YAML document header
<http://yaml.org/spec/history/2002-10-31.html#syntax-document> like "---
#YAML:1.0" #
FFiieellddss The rest of the META.yml file is one big YAML mapping http://yaml.org/spec/history/2002-10-31.html#syntax-mapping, whose keys are described here.
name
Example: "Module-Build"
The name of the distribution. 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
<http://search.cpan.org/author/GAAS/libwww-perl/> distribution.
version
Example: 0.16
The version of the distribution to which the META.yml file refers.
This is a mandatory field.
The version is essentially an arbitrary string, but _m_u_s_t be only
ASCII characters, and _s_t_r_o_n_g_l_y _s_h_o_u_l_d be of the format integer-dot-
digit-digit, i.e. 25.57, optionally followed by underscore-digit-
digit, i.e. "25.57_04".
The standard tools that deal with module distribution (PAUSE, CPAN,
etc.) form an identifier for each distribution by joining the 'name'
and 'version' attributes with a dash ("-") character. Tools who are
prepared to deal with distributions that have no version numbers
generally omit the dash as well.
license
Example: "perl"
a descriptive term for the licenses ... not authoritative, but must
be consistent with licensure statements in the READMEs,
documentation, etc.
The license under which this distribution may be used and
redistributed.
Must be one of the following licenses:
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.
gpl The distribution is distributed under the terms of the GNU
General Public License version 2
(<http://opensource.org/licenses/GPL-2.0>).
lgpl
The distribution is distributed under the terms of the GNU Lesser
General Public License version 2
(<http://opensource.org/licenses/LGPL-2.1>).
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>).
bsd The distribution is licensed under the BSD 3-Clause License
(<http://opensource.org/licenses/BSD-3-Clause>).
open_source
The distribution is licensed under some other Open Source
Initiative-approved license listed at
<http://www.opensource.org/licenses/>.
unrestricted
The distribution is licensed under a license that is nnoott approved
by www.opensource.org <http://www.opensource.org/> but that
allows distribution without restrictions.
restrictive
The distribution may not be redistributed without special
permission from the author and/or copyright holder.
license_uri
This should contain a URI where the exact terms of the license may be
found.
(change "unrestricted" to "redistributable"?)
distribution_type
Example: "module"
What kind of stuff is contained in this distribution. Most things on
CPAN are "module"s (which can also mean a collection of modules), but
some things are "script"s.
This field is basically meaningless, and tools (like Module::Build or
MakeMaker) will likely stop generating it in the future.
private
WTF is going on here?
index_ignore: any application that indexes the contents of
distributions (PAUSE, search.cpan.org) ought to ignore the items
(packages, files, directories, namespace hierarchies).
requires
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML mapping <http://yaml.org/spec/history/2002-10-31.html#syntax-
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 the documentation for
Module::Build's "requires" parameter.
_N_o_t_e_: _t_h_e _e_x_a_c_t _n_a_t_u_r_e _o_f _t_h_e _f_a_n_c_y _s_p_e_c_i_f_i_c_a_t_i_o_n_s _l_i_k_e _"_>_= _1_._2_, _!_=
_1_._5_, _< _2_._0_" _i_s _s_u_b_j_e_c_t _t_o _c_h_a_n_g_e_. _A_d_v_a_n_c_e _n_o_t_i_c_e _w_i_l_l _b_e _g_i_v_e_n _h_e_r_e_.
_T_h_e _s_i_m_p_l_e _s_p_e_c_i_f_i_c_a_t_i_o_n_s _l_i_k_e _"_1_._2_" _w_i_l_l _n_o_t _c_h_a_n_g_e _i_n _f_o_r_m_a_t_.
recommends
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML mapping <http://yaml.org/spec/history/2002-10-31.html#syntax-
mapping> indicating the Perl modules this distribution recommends for
enhanced operation.
build_requires
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML mapping <http://yaml.org/spec/history/2002-10-31.html#syntax-
mapping> indicating the Perl modules required for building and/or
testing of this distribution. These dependencies are not required
after the module is installed.
conflicts
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML mapping <http://yaml.org/spec/history/2002-10-31.html#syntax-
mapping> indicating the Perl modules that cannot be installed while
this distribution is installed. This is a pretty uncommon situation.
- possibly separate out test-time prereqs, complications include: can
tests be meaningfully preserved for later running? are test-time
prereqs in addition to build-time, or exclusive?
- make official location for installed *distributions*, which can
contain tests, etc.
dynamic_config
Example: 0
A boolean flag indicating whether a _B_u_i_l_d_._P_L or _M_a_k_e_f_i_l_e_._P_L (or
similar) must be executed, or whether this module 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.
Currently Module::Build doesn't actually do anything with this flag -
it's probably going to be up to higher-level tools like CPAN.pm to do
something useful with it. It can potentially bring lots of security,
packaging, and convenience improvements.
generated_by
Example: "Module::Build version 0.16"
Indicates the tool that was used to create this _M_E_T_A_._y_m_l 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.
IInnggyy’’ss ssuuggggeessttiioonnss short_description add as field, containing abstract, maximum 80 characters, suggested minimum 40 characters
description
long version of abstract, should add?
maturity
alpha, beta, gamma, mature, stable
author_id, owner_id
categorization, keyword, chapter_id
URL for further information
could default to search.cpan.org on PAUSE
namespaces
can be specified for single elements by prepending dotted-form, i.e.
"com.example.my_application.my_property". Default namespace for
META.yml is probably "org.cpan.meta_author" or something. Precedent
for this is Apple's Carbon namespaces, I think.
HHiissttoorryy • MMaarrcchh 1144,, 22000033 (Pi day) - created version 1.0 of this document.
• MMaayy 88,, 22000033 - added the "dynamic_config" field, which was missing
from the initial version.
perl v5.36.3 2019-02-13 CPAN::Meta::History::Meta_1_1(3p)