[Module-build-checkins] Module-Build/website META-spec.html,1.4,1.5 META-spec.pod,1.1,1.2
Status: Beta
Brought to you by:
kwilliams
Menu
▾
▴
[Module-build-checkins] Module-Build/website META-spec.html,1.4,1.5 META-spec.pod,1.1,1.2
|
From: Ken W. <kwi...@us...> - 2005-07-26 22:20:45
|
Update of /cvsroot/module-build/Module-Build/website In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv30032 Modified Files: META-spec.html META-spec.pod Log Message: Bring into accordance with currently supported metainformation Index: META-spec.html =================================================================== RCS file: /cvsroot/module-build/Module-Build/website/META-spec.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -d -r1.4 -r1.5 --- META-spec.html 26 Jul 2005 03:19:46 -0000 1.4 +++ META-spec.html 26 Jul 2005 22:20:35 -0000 1.5 @@ -2,7 +2,7 @@ <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>CPAN::META::Specification - Specification for F<META.yml></title> -<link rev="made" href="mailto:" /> +<link rev="made" href="mailto:ro...@ha..." /> </head> <body style="background-color: white"> @@ -25,28 +25,15 @@ <li><a href="#metaspec">meta-spec</a></li> <li><a href="#name">name</a></li> <li><a href="#version">version</a></li> - <li><a href="#generation">generation</a></li> <li><a href="#abstract">abstract</a></li> - <li><a href="#authored_by">authored_by</a></li> + <li><a href="#author">author</a></li> <li><a href="#license">license</a></li> <li><a href="#distribution_type">distribution_type</a></li> <li><a href="#requires">requires</a></li> <li><a href="#recommends">recommends</a></li> <li><a href="#build_requires">build_requires</a></li> <li><a href="#conflicts">conflicts</a></li> - <li><a href="#requires_build_tools">requires_build_tools</a></li> - <li><a href="#requires_packages">requires_packages</a></li> - <ul> - - <li><a href="#version">version</a></li> - <li><a href="#has_library">has_library</a></li> - <li><a href="#has_program">has_program</a></li> - </ul> - <li><a href="#dynamic_config">dynamic_config</a></li> - <li><a href="#configure">configure</a></li> - <li><a href="#requires_os">requires_os</a></li> - <li><a href="#excludes_os">excludes_os</a></li> <li><a href="#private">private</a></li> <li><a href="#index">index</a></li> <ul> @@ -68,7 +55,6 @@ <li><a href="#keywords">keywords</a></li> <li><a href="#generated_by">generated_by</a></li> - <li><a href="#auto_regenerate">auto_regenerate</a></li> </ul> <li><a href="#see_also">SEE ALSO</a></li> @@ -90,8 +76,8 @@ name: Module-Build abstract: Build and install Perl modules version: 0.20 - authored_by: - - Ken Williams <ke...@ma...> + author: + - Ken Williams <kwi...@cp...> license: perl distribution_type: module requires: @@ -193,7 +179,7 @@ supports a list of versions, each of which may be optionally preceeded by a relational operator.</p> <p>Supported operators include < (less than), <= (less than or -equal), > (greater than), >= (greater than or equal), and != +equal), > (greater than), >= (greater than or equal), == (equal), and != (not equal).</p> <p>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 @@ -247,20 +233,6 @@ <em>META.yml</em> file refers.</p> <p> </p> -<h2><a name="generation">generation</a></h2> -<p>Example:</p> -<pre> - generation: 2</pre> -<p>(Spec 1.1) [optional] Indicates which generation this version belongs -to. A generation is a way of indicating that a collection of versions -are all compatible with each other, whereas a version from a different -generation may include incompatibilities or other major -differences. This allows tools like CPAN and CPANPLUS to present to -its users the greatest version in each generation to choose from when -the user queries a package instead of only presenting a single highest -version.</p> -<p> -</p> <h2><a name="abstract">abstract</a></h2> <p>Example:</p> <pre> @@ -269,11 +241,11 @@ distribution.</p> <p> </p> -<h2><a name="authored_by">authored_by</a></h2> +<h2><a name="author">author</a></h2> <p>Example:</p> <pre> - authored_by: - - Ken Williams <ke...@ma...></pre> + author: + - Ken Williams <kwi...@cp...></pre> <p>(Spec 1.1) [required] A YAML sequence indicating the <code>author(s)</code> of the distribution. The prefered form is author-name <email-address>.</p> <p> @@ -294,6 +266,11 @@ <p>(Spec 1.0) [optional] What kind of stuff is contained in this distribution. Most things on CPAN are <a href="#item_module"><code>module</code></a>s (which can also mean a collection of modules), but some things are <code>script</code>s.</p> +<p>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.</p> <p> </p> <h2><a name="requires">requires</a></h2> @@ -317,7 +294,7 @@ <p>(Spec 1.0) [optional] A YAML mapping indicating the Perl modules this distribution recommends for enhanced operation.</p> <p><em>ALTERNATIVE: It may be desirable to present to the user which -features are dependant on which modules so they can make an informed +features depend on which modules so they can make an informed decision about which recommended modules to install.</em></p> <p>Example:</p> <pre> @@ -360,59 +337,14 @@ pretty uncommon situation.</p> <p> </p> -<h2><a name="requires_build_tools">requires_build_tools</a></h2> -<p>Example:</p> -<pre> - requires_build_tools: 1</pre> -<p>(Spec 1.1) [optional] A boolean that indicates external build tools -(i.e. compiler, linker, etc.) are required to build this package. If -not present it is assumed to be false.</p> -<p> -</p> -<h2><a name="requires_packages">requires_packages</a></h2> -<p>Example:</p> -<pre> - requires_packages: - - libiconv: - version: 1.9 - has_library: - - iconv - - charset - has_program: - - iconv - - zlib - has_library: - - z</pre> -<p>(Spec 1.1) [optional] A YAML sequence of fields whose names are the -names of non-perl distributions which are required by this -distribution. Each field is a YAML mapping that more specifically -describes the requirement.</p> -<p> -</p> -<h3><a name="version">version</a></h3> -<p>(Spec 1.1) [optional] A version specification indicating the required -<code>version(s)</code> of the required distribution.</p> -<p> -</p> -<h3><a name="has_library">has_library</a></h3> -<p>(Spec 1.1) [optional] 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> -<p> -</p> -<h3><a name="has_program">has_program</a></h3> -<p>(Spec 1.1) [optional] A sequence of names of executable programs -provided by this distribution which must be present for the -distribution to be considered present.</p> -<p> -</p> <h2><a name="dynamic_config">dynamic_config</a></h2> <p>Example:</p> <pre> dynamic_config: 0</pre> <p>(Spec 1.0) [optional] A boolean flag indicating whether a <em>Build.PL</em> -or <em>Makefile.PL</em> (or similar) must be executed, or whether this -module can be built, tested and installed solely from consulting its +or <em>Makefile.PL</em> (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.</p> @@ -420,45 +352,7 @@ - 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.</p> -<p> -</p> -<h2><a name="configure">configure</a></h2> -<p>Example:</p> -<pre> - configure: auto</pre> -<p>(Spec 1.1) [optional] If the distribution requires configuration, this -field indicates whether the configuration process is <code>interactive</code> -and requires user intervention, <code>scriptable</code> and requires -intervention or an answer script, or <code>auto</code> and can configure its -self automatically.</p> -<p> -</p> -<h2><a name="requires_os">requires_os</a></h2> -<p>Example:</p> -<pre> - requires_os: darwin</pre> -<p>(Spec 1.1) [optional] This field contains a sequence of operating -system names (ex. <code>$^O</code> 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 <a href="#excludes_os">excludes_os</a> below.</p> -<p><em>Note: If this field is specified, then <a href="#excludes_os">excludes_os</a> must not -be specified.</em></p> -<p> -</p> -<h2><a name="excludes_os">excludes_os</a></h2> -<p>Example:</p> -<pre> - excludes_os: MSWin32</pre> -<p>(Spec 1.1) [optional] This field contains a sequence of operating -system names (ex. <code>$^O</code> 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 <a href="#requires_os">requires_os</a> above.</p> -<p><em>Note: If this field is specified, then <a href="#requires_os">requires_os</a> must not -be specified.</em></p> +<p>If this field is omitted, it defaults to 1 (true).</p> <p> </p> <h2><a name="private">private</a></h2> @@ -565,17 +459,6 @@ tool. RWS]</p> <p> </p> -<h2><a name="auto_regenerate">auto_regenerate</a></h2> -<p>Example:</p> -<pre> - auto_regenerate: false</pre> -<p>(Spec 1.1) [optional] Some tools (Module::Build, ExtUtils::MakeMaker) -automaticaly generate a <em>META.yml</em> file. If you customize this file, -you should use this field to indicate to tools that follow the -specification that they should not overwrite your customizations. The -value of this field is assumed to be 'true' if not present.</p> -<p> -</p> <hr /> <h1><a name="see_also">SEE ALSO</a></h1> <p>CPAN, <a href="http://www.cpan.org/">http://www.cpan.org/</a></p> @@ -665,6 +548,30 @@ Add <a href="#terminology">TERMINOLOGY</a> section to explain certain terms that may be ambiguous. <p></p></ul> +<dt><strong><a name="item_july_26_2c_2005">July 26, 2005</a></strong><br /> +</dt> +<ul> +<li></li> +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. +<p></p> +<li></li> +Changed <code>authored_by</code> to <code>author</code>, since that's always been what +it's actually called in actual <em>META.yml</em> files. +<p></p> +<li></li> +Added the ``=='' operator to the list of supported version-checking +operators. +<p></p> +<li></li> +Noted that the <code>distribution_type</code> field is basically meaningless, +and shouldn't really be used. +<p></p> +<li></li> +Clarified <code>dynamic_config</code> a bit. +<p></p></ul> </dl> </body> Index: META-spec.pod =================================================================== RCS file: /cvsroot/module-build/Module-Build/website/META-spec.pod,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- META-spec.pod 26 Jul 2005 03:18:58 -0000 1.1 +++ META-spec.pod 26 Jul 2005 22:20:36 -0000 1.2 @@ -8,8 +8,8 @@ name: Module-Build abstract: Build and install Perl modules version: 0.20 - authored_by: - - Ken Williams <ke...@ma...> + author: + - Ken Williams <kwi...@cp...> license: perl distribution_type: module requires: @@ -122,7 +122,7 @@ by a relational operator. Supported operators include E<lt> (less than), E<lt>= (less than or -equal), E<gt> (greater than), E<gt>= (greater than or equal), and != +equal), E<gt> (greater than), E<gt>= (greater than or equal), == (equal), and != (not equal). If a list is given then it is evaluated from left to right so that any @@ -179,21 +179,6 @@ (Spec 1.0) [required] The version of the distribution to which the F<META.yml> file refers. -=head2 generation - -Example: - - generation: 2 - -(Spec 1.1) [optional] Indicates which generation this version belongs -to. A generation is a way of indicating that a collection of versions -are all compatible with each other, whereas a version from a different -generation may include incompatibilities or other major -differences. This allows tools like CPAN and CPANPLUS to present to -its users the greatest version in each generation to choose from when -the user queries a package instead of only presenting a single highest -version. - =head2 abstract Example: @@ -203,12 +188,12 @@ (Spec 1.1) [required] A short description of the purpose of the distribution. -=head2 authored_by +=head2 author Example: - authored_by: - - Ken Williams <ke...@ma...> + author: + - Ken Williams <kwi...@cp...> (Spec 1.1) [required] A YAML sequence indicating the author(s) of the distribution. The prefered form is author-name <email-address>. @@ -233,6 +218,12 @@ distribution. Most things on CPAN are C<module>s (which can also mean a collection of modules), but some things are C<script>s. +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. + =head2 requires Example: @@ -258,7 +249,7 @@ distribution recommends for enhanced operation. I<ALTERNATIVE: It may be desirable to present to the user which -features are dependant on which modules so they can make an informed +features depend on which modules so they can make an informed decision about which recommended modules to install.> Example: @@ -304,54 +295,6 @@ cannot be installed while this distribution is installed. This is a pretty uncommon situation. -=head2 requires_build_tools - -Example: - - requires_build_tools: 1 - -(Spec 1.1) [optional] A boolean that indicates external build tools -(i.e. compiler, linker, etc.) are required to build this package. If -not present it is assumed to be false. - -=head2 requires_packages - -Example: - - requires_packages: - - libiconv: - version: 1.9 - has_library: - - iconv - - charset - has_program: - - iconv - - zlib - has_library: - - z - -(Spec 1.1) [optional] A YAML sequence of fields whose names are the -names of non-perl distributions which are required by this -distribution. Each field is a YAML mapping that more specifically -describes the requirement. - -=head3 version - -(Spec 1.1) [optional] A version specification indicating the required -version(s) of the required distribution. - -=head3 has_library - -(Spec 1.1) [optional] A sequence of names of loadable or linkable -libraries provided by this distribution which must be present for the -distribution to be considered present. - -=head3 has_program - -(Spec 1.1) [optional] A sequence of names of executable programs -provided by this distribution which must be present for the -distribution to be considered present. - =head2 dynamic_config Example: @@ -359,8 +302,9 @@ dynamic_config: 0 (Spec 1.0) [optional] 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 +or F<Makefile.PL> (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. @@ -370,49 +314,7 @@ to do something useful with it. It can potentially bring lots of security, packaging, and convenience improvements. -=head2 configure - -Example: - - configure: auto - -(Spec 1.1) [optional] If the distribution requires configuration, this -field indicates whether the configuration process is C<interactive> -and requires user intervention, C<scriptable> and requires -intervention or an answer script, or C<auto> and can configure its -self automatically. - -=head2 requires_os - -Example: - - requires_os: darwin - -(Spec 1.1) [optional] This field contains a sequence of operating -system names (ex. C<$^O> 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 L</"excludes_os"> below. - -I<Note: If this field is specified, then L</"excludes_os"> must not -be specified.> - -=head2 excludes_os - -Example: - - excludes_os: MSWin32 - -(Spec 1.1) [optional] This field contains a sequence of operating -system names (ex. C<$^O> 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 L</"requires_os"> above. - -I<Note: If this field is specified, then L</"requires_os"> must not -be specified.> +If this field is omitted, it defaults to 1 (true). =head2 private @@ -523,18 +425,6 @@ tool that generated the file and the second field as version of that tool. RWS] -=head2 auto_regenerate - -Example: - - auto_regenerate: false - -(Spec 1.1) [optional] Some tools (Module::Build, ExtUtils::MakeMaker) -automaticaly generate a F<META.yml> file. If you customize this file, -you should use this field to indicate to tools that follow the -specification that they should not overwrite your customizations. The -value of this field is assumed to be 'true' if not present. - =head1 SEE ALSO CPAN, L<http://www.cpan.org/> @@ -667,4 +557,36 @@ =back +=item July 26, 2005 + +=over 2 + +=item * + +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. + +=item * + +Changed C<authored_by> to C<author>, since that's always been what +it's actually called in actual F<META.yml> files. + +=item * + +Added the "==" operator to the list of supported version-checking +operators. + +=item * + +Noted that the C<distribution_type> field is basically meaningless, +and shouldn't really be used. + +=item * + +Clarified C<dynamic_config> a bit. + +=back + =back |
