Ok. So, I've gone over the spec and referenced this thread and my archives of past meta discusions on module-authors, and I've come up with a preliminary patch for Ken and anyone else interested. This is a patch against <http://module-build.sourceforge.net/META-spec.html> which:
* Added more YAML rationale articles.
* Fixed existing link to YAML discussion thread to point to new <http://nntp.x.perl.org/group/> site.
* Added and deprecated the "private" field.
* Added "abstract", "configure", "requires_os", "excludes_os", and "no_index" fields.
* Bumped version.
Comments and suggestions?
Randy.
--- META-spec.html.orig 2003-11-13 19:02:25.000000000 -0500 +++ META-spec.html 2003-11-13 22:30:55.000000000 -0500 @@ -2,7 +2,7 @@ <body> <h2 align="center">Specification for the META.yml file</h2> -<p>This document describes version 1.0 of the META.yml specification.</p> +<p>This document describes version 1.1 of the META.yml specification.</p> <p> The META.yml file describes important properties of contributed Perl @@ -12,10 +12,10 @@ </p> <p> -The fields in the META.yml file are meant to be helpful to people +The fields in the META.yml file are meant to be helpful for people maintaining module collections (like CPAN), for people writing installation tools (like <a href="http://search.cpan.org/author/ANDK/CPAN/";>CPAN.pm</a> or <a href="http://search.cpan.org/author/KANE/CPANPLUS/";>CPANPLUS</a>), or -just people who want to know some stuff about a distribution before +just for people who want to know some stuff about a distribution before downloading it and starting to install it. </p> @@ -23,10 +23,19 @@ <p> META.yml files are written in the <a href="http://www.yaml.org/";>YAML</a> format. The reasons we chose -YAML instead of, say, XML or Data::Dumper are discussed in <a href="http://archive.develooper.com/[EMAIL PROTECTED]/msg00405.html">this +YAML instead of, say, XML or Data::Dumper are discussed in <a href="http://nntp.x.perl.org/group/perl.makemaker/406";>this thread</a> on the MakeMaker mailing list. </p> +<p>See Also:</p> + +<ul> +<li><a href="http://nntp.x.perl.org/group/perl.module-authors/1353";>Not keen on YAML</a></li> +<li><a href="http://nntp.x.perl.org/group/perl.module-authors/1385";>META Concerns</a></li> +</ul> + +<h3>Header</h3> + <p> The first line of a META.yml file should be a valid <a href="http://www.yaml.org/spec/#.Document";>YAML document header</a> like <nobr><tt>"--- #YAML:1.0"</tt></nobr>. @@ -56,6 +65,12 @@ The version of the distribution to which the META.yml file refers. </p> +</li><li><b>abstract</b><br> +Example: <b>One line description of the distribution.</b> +<p> +A short description of the purpose of the distribution. +</p> + </li><li><b>license</b><br> Example: <b>perl</b> <p> @@ -129,6 +144,56 @@ distribution is installed. This is a pretty uncommon situation. </p> +</li><li><b>requires_packages</b><br> +Example:<BR> +<b> + libiconv:<br> + version: 1.9<br> + has_library:<br> + - iconv<br> + - charset<br> + has_program:<br> + - iconv<br> +</b> +<p> +This mapping contains a sequence of fields whose names are the names +of non-perl distributions which are required by this distribution. +A number of subfields may be provided to more specifically describe +the requirement. +</p> + +<ul> +<li><b>version</b><br> +Example: <b>1.9</b> +<p> +A version specification indicating the required version(s) of the +required distribution. +</p> + +</li><li><b>has_library</b><br> +Example:<br> +<b> + - iconv<br> + - charset<br> +</b> +<p> +A sequence of names of loadable or linkable libraries +provided by this distribution which must be present for +the distribution to be considered present. +</p> + +</li><li><b>has_program</b><br> +Example:<br> +<b> + - iconv<br> +</b> +<p> +A sequence of names of executable programs +provided by this distribution which must be present for +the distribution to be considered present. +</p> +</li></ul> + </li><li><b>dynamic_config</b><br> Example: <b>0</b> <p> @@ -147,6 +212,111 @@ bring lots of security, packaging, and convenience improvements. </p> +</li><li><b>configure</b><br> +Example: <b>auto</b> +<p> +If the distribution requires configuration, this field indicates whether +the configuration process is <tt>interactive</tt> and requires user +intervention, <tt>scriptable</tt> and requires intervention unless +an answer script is provided, or <tt>auto</tt> and can configure its +self automatically. +</p> + +</li><li><b>requires_os</b><br> +Example: <b>darwin</b> +<p> +This field contains a sequence of operating system names +(ex. <tt>$^O</tt> in perl) that are required for this distribution. +This is an implied white list such that this distribution will not +run on any operating system unless it is listed in this field. For +an alternative way to manage operating system dependencies see +<b>excludes_os</b> below. +</p> + +<p><i>Note: If this field is specified, then <b>excludes_os</b> must +not be specified. +</i> +</p> + +</li><li><b>excludes_os</b><br> +Example: <b>MSWin32</b> +<p> +This field contains a sequence of operating system names +(ex. <tt>$^O</tt> in perl) that are incompatible with this distribution. +This is an implied black list such that this distribution will +run on any operating system except those listed in this field. For +an alternative way to manage operating system dependencies see +<b>requires_os</b> above. +</p> + +<p><i>Note: If this field is specified, then <b>requires_os</b> must +not be specified. +</i> +</p> + +</li><li><b>private</b> +<p> +<b>(Deprecated)</b> This field has been renamed to <b>no_index</b>. +See below. +</p> + +</li><li><b>no_index</b><br> +Example:<br> +<b> + file:<br> + - My/Module.pm<br> + dir:<br> + - My/Private<br> + package:<br> + - My::Module::Stuff<br> + namespace:<br> + - My::Module::Stuff<br> +</b> +<p> +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. +</p> + +<ul> +<li><b>file</b><br> +Example:<br> +<b> + - My/Module.pm<br> +</b> +<p> +Exclude any listed file(s). +</p> + +</li><li><b>dir</b><br> +Example:<br> +<b> + - My/Private<br> +</b> +<p> +Exclude anything below the listed directory(ies). +</p> + +</li><li><b>package</b><br> +Example:<br> +<b> + - My::Module::Stuff<br> +</b> +<p> +Exclude the listed package(s). +</p> + +</li><li><b>namespace</b><br> +Example:<br> +<b> + - My::Module::Stuff<br> +</b> +<p> +Excludes anything below the listed namespace(s), but <i>not</i> +the listed namespace(s) its self. +</p> +</li></ul> + </li><li><b>generated_by</b><br> Example: <b>Module::Build version 0.16</b> <p> @@ -163,6 +333,13 @@ <li><b>March 14, 2003</b> (Pi day) - created version 1.0 of this document.</li> <li><b>May 8, 2003</b> - added the "dynamic_config" field, which was missing from the initial version.</li> +<li><b>November 13, 2003</b><br> +<ul> +<li>Added more YAML rationale articles.</li> +<li>Fixed existing link to YAML discussion thread to point to new <http://nntp.x.perl.org/group/> site.</li> +<li>Added and deprecated the "private" field.</li> +<li>Added "abstract", "configure", "requires_os", "excludes_os", and "no_index" fields.</li> +<li>Bumped version.</li> </ul> -</body></html> \ No newline at end of file +</body></html>
