=for :stopwords DOAP RDF
=head1 NAME
CPAN::Meta::History::Meta_1_0 - Version 1.0 metadata specification for META.yml
=head1 PREFACE
This is a historical copy of the version 1.0 specification for F<META.yml>
files, copyright by Ken Williams.
Modifications from the original:
=over
=item *
Conversion from the original HTML to POD format
=back
=head1 DESCRIPTION
This document describes version 1.0 of the F<META.yml> specification.
The META.yml file describes important properties of contributed Perl
distributions such as the ones found on L<CPAN|http://www.cpan.org>. It is
typically created by tools like L<Module::Build> and L<ExtUtils::MakeMaker>.
The fields in the F<META.yml> file are meant to be helpful to people
maintaining module collections (like CPAN), for people writing
installation tools (like L<CPAN> or L<CPANPLUS>), or just people who want to
know some stuff about a distribution before downloading it and starting to
install it.
=head1 Format
F<META.yml> files are written in the L<YAML|http://www.yaml.org/> format. The
reasons we chose YAML instead of, say, XML or Data::Dumper are discussed in
L<this thread|http://archive.develooper.com/makemaker@perl.org/msg00405.html>
on the MakeMaker mailing list.
The first line of a F<META.yml> file should be a valid L<YAML document header|http://www.yaml.org/spec/#.Document>
like C<"--- #YAML:1.0">
=head1 Fields
The rest of the META.yml file is one big YAML
L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->,
whose keys are described here.
=over 4
=item name
Example: C<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
L<libwww-perl|http://search.cpan.org/author/GAAS/libwww-perl/> distribution.
=item version
Example: C<0.16>
The version of the distribution to which the META.yml file refers.
=item license
Example: C<perl>
The license under which this distribution may be used and
redistributed. See L<Module::Build> for the list of valid options.
=item distribution_type
Example: C<module>
What kind of stuff is contained in this distribution. Most things on
CPAN are C<module>s (which can also mean a collection of
modules), but some things are C<script>s.
=item requires
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-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 L<Module::Build|documentation for Module::Build's "requires" parameter>.
I<Note: the exact nature of the fancy specifications like
C<< ">= 1.2, != 1.5, < 2.0" >> is subject to
change. Advance notice will be given here. The simple specifications
like C<"1.2"> will not change in format.>
=item recommends
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
indicating the Perl modules this distribution recommends for enhanced
operation.
=item build_requires
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
indicating the Perl modules required for building and/or testing of
this distribution. These dependencies are not required after the
module is installed.
=item conflicts
Example:
Data::Dumper: 0
File::Find: 1.03
A YAML L<mapping|http://www.yaml.org/spec/#.-syntax-mapping-Mapping->
indicating the Perl modules that cannot be installed while this
distribution is installed. This is a pretty uncommon situation.
=item dynamic_config
Example: C<0>
A boolean flag indicating whether a F<Build.PL> or
F<Makefile.PL> (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 L<Module::Build> doesn't actually do anything with
this flag - it's probably going to be up to higher-level tools like
L<CPAN|CPAN.pm> to do something useful with it. It can potentially
bring lots of security, packaging, and convenience improvements.
=item generated_by
Example: C<Module::Build version 0.16>
Indicates the tool that was used to create this F<META.yml> 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.
=back
=head1 Related Projects
=over 4
=item DOAP
An RDF vocabulary to describe software projects. L<http://usefulinc.com/doap>.
=back
=head1 History
=over 4
=item *
B<March 14, 2003> (Pi day) - created version 1.0 of this document.
=item *
B<May 8, 2003> - added the "dynamic_config" field, which was missing from the
initial version.
=back