=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
