Contents of /xml/htdocs/proj/en/glep/glep-0056.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (hide annotations) (download) (as text)
Thu Jul 10 18:24:24 2008 UTC (9 years, 11 months ago) by cardoe
Branch: MAIN
Changes since 1.1: +47 -31 lines
File MIME type: text/html
update html for GLEP-0056

1 dev-zero 1.1 <?xml version="1.0" encoding="utf-8" ?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5     <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7     <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8     <title>GLEP 56 -- USE flag descriptions in metadata</title>
9     <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10     </head>
11     <body bgcolor="white">
12     <table class="navigation" cellpadding="0" cellspacing="0"
13     width="100%" border="0">
14     <tr><td class="navicon" width="150" height="35">
15     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17     border="0" width="150" height="35" /></a></td>
18     <td class="textlinks" align="left">
19     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20     [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21     [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0056.txt">GLEP Source</a></b>]
22     </td></tr></table>
23     <table class="rfc2822 docutils field-list" frame="void" rules="none">
24     <col class="field-name" />
25     <col class="field-body" />
26     <tbody valign="top">
27     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">56</td>
28     </tr>
29     <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag descriptions in metadata</td>
30     </tr>
31 cardoe 1.2 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
32 dev-zero 1.1 </tr>
33 cardoe 1.2 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0056.txt?cvsroot=gentoo">2008/07/10 18:15:05</a></td>
34 dev-zero 1.1 </tr>
35     <tr class="field"><th class="field-name">Author:</th><td class="field-body">Doug Goldstein &lt;cardoe&#32;&#97;t&#32;gentoo.org&gt;</td>
36     </tr>
37     <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
38     </tr>
39     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40     </tr>
41     <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td>
42     </tr>
43     <tr class="field"><th class="field-name">Created:</th><td class="field-body">03-Jun-2008</td>
44     </tr>
45 cardoe 1.2 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">13-Jun-2008</td>
46 dev-zero 1.1 </tr>
47     </tbody>
48     </table>
49     <hr />
50     <div class="contents topic">
51     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52     <ul class="simple">
53 cardoe 1.2 <li><a class="reference" href="#abstract" id="id11" name="id11">Abstract</a></li>
54     <li><a class="reference" href="#motivation" id="id12" name="id12">Motivation</a></li>
55     <li><a class="reference" href="#specification" id="id13" name="id13">Specification</a></li>
56     <li><a class="reference" href="#credits" id="id14" name="id14">Credits</a></li>
57     <li><a class="reference" href="#references" id="id15" name="id15">References</a></li>
58     <li><a class="reference" href="#backwards-compatibility" id="id16" name="id16">Backwards Compatibility</a></li>
59 dev-zero 1.1 <li><a class="reference" href="#copyright" id="id17" name="id17">Copyright</a></li>
60     </ul>
61     </div>
62     <div class="section">
63 cardoe 1.2 <h1><a class="toc-backref" href="#id11" id="abstract" name="abstract">Abstract</a></h1>
64 dev-zero 1.1 <p>This GLEP proposes to add per-package USE flag descriptions to each package's
65     metadata.</p>
66     </div>
67     <div class="section">
68 cardoe 1.2 <h1><a class="toc-backref" href="#id12" id="motivation" name="motivation">Motivation</a></h1>
69 dev-zero 1.1 <p>Gives Gentoo users the ability to better identify how USE flags affect their
70     installations of a given package. For example, many global USE flags have very
71     generic descriptions but no specifics on how it affects a certain package.
72     Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
73     flag. Does this flag mean you won't be able to print jpeg files? You can print
74     them directly? It's interface won't use jpeg files.</p>
75     <blockquote>
76     <ul class="simple">
77     <li>Motivator References: <a class="footnote-reference" href="#motivators1" id="id1" name="id1">[6]</a>, <a class="footnote-reference" href="#motivators2" id="id2" name="id2">[7]</a>, <a class="footnote-reference" href="#motivators3" id="id3" name="id3">[8]</a>,
78     and <a class="footnote-reference" href="#motivators4" id="id4" name="id4">[9]</a></li>
79     </ul>
80     </blockquote>
81     </div>
82     <div class="section">
83 cardoe 1.2 <h1><a class="toc-backref" href="#id13" id="specification" name="specification">Specification</a></h1>
84 dev-zero 1.1 <p>This GLEP proposes the addition of <tt class="docutils literal"><span class="pre">&lt;use&gt;</span></tt> XML tag that is only allowed to
85     appear inside of a <tt class="docutils literal"><span class="pre">&lt;pkgmetadata&gt;</span></tt> XML tag.</p>
86     <blockquote>
87     <ul>
88     <li><p class="first">Inside the <tt class="docutils literal"><span class="pre">&lt;use&gt;</span></tt> XML tag, the <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag is allowed to appear
89     once per USE flag as specified by the <tt class="docutils literal"><span class="pre">'name'</span></tt> attribute with the
90     following exception:</p>
91     <ul class="simple">
92     <li>The <tt class="docutils literal"><span class="pre">'restrict'</span></tt> atttribute can limit to specific versions of the
93     package, where the attribute value must be a valid CPV as defined by the
94 cardoe 1.2 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id5" name="id5">[4]</a>. This follows the current
95     behavior of the <tt class="docutils literal"><span class="pre">'restrict'</span></tt> attribute in metadata.xml.<ul>
96 dev-zero 1.1 <li>e.g. A USE flag may have one behavior for version 0.1 of a package,
97     while version 0.2, the USE flag may differ slightly.</li>
98     </ul>
99     </li>
100     </ul>
101     </li>
102     <li><p class="first">Each <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag requires a 'name' attribute which is the full USE
103     flag name as it would appear in the IUSE section of the ebuild.</p>
104     <blockquote>
105     <ul class="simple">
106     <li>e.g. &quot;video_cards_i810&quot; or &quot;alsa&quot;</li>
107     </ul>
108     </blockquote>
109     </li>
110     <li><p class="first">Each <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag allows 0 or more nested <tt class="docutils literal"><span class="pre">&lt;pkg&gt;</span></tt> XML tags whose
111     character data is a valid CP or CPV as defined by the
112 cardoe 1.2 <cite>Gentoo Development Guide - Ebuild File Format</cite> <a class="footnote-reference" href="#devmanual" id="id6" name="id6">[5]</a>.</p>
113 dev-zero 1.1 </li>
114     <li><p class="first">Each <tt class="docutils literal"><span class="pre">&lt;flag&gt;</span></tt> XML tag allows 0 or more nested <tt class="docutils literal"><span class="pre">&lt;cat&gt;</span></tt> XML tags whose
115     character data is a valid category.</p>
116     </li>
117     <li><p class="first">The <tt class="docutils literal"><span class="pre">&lt;use&gt;</span></tt> XML tag may appear multiple times inside of the
118     <tt class="docutils literal"><span class="pre">&lt;pkgmetadata&gt;</span></tt> XML tag if and only if it contains a different <tt class="docutils literal"><span class="pre">'lang'</span></tt>
119     attribute value.</p>
120     <ul class="simple">
121     <li>The <tt class="docutils literal"><span class="pre">lang</span></tt> attribute follows the documented <tt class="docutils literal"><span class="pre">lang</span></tt> attribute in the
122 cardoe 1.2 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id7" name="id7">[4]</a>.</li>
123 dev-zero 1.1 </ul>
124     </li>
125     </ul>
126     </blockquote>
127     <p>Documentation for the Developer Manual and the metadata.dtd can be found in
128 cardoe 1.2 Gentoo's Bugzilla <a class="footnote-reference" href="#use-flag-metadata-bug" id="id8" name="id8">[1]</a> bug #199788.</p>
129     <p>The following are two concrete examples in tree, <a class="footnote-reference" href="#use-flag-metadata-example1" id="id9" name="id9">[2]</a>
130     and <a class="footnote-reference" href="#use-flag-metadata-example2" id="id10" name="id10">[3]</a>.</p>
131 dev-zero 1.1 <p>And the following is an embedded example and not from a real package:</p>
132     <pre class="literal-block">
133     &lt;use&gt;
134     &lt;flag name='acpi'&gt;Enables HAL to attempt to read from
135     /proc/acpi/event, if unavailable, HAL will read events from
136     &lt;pkg&gt;sys-power/acpid&lt;/pkg&gt;. If you need multiple acpi readers,
137     ensure acpid is in your default runlevel
138     (rc-update add acpid default) along with HAL. This will also
139     enable HAL to read Toshiba and IBM acpi events which do not
140     get sent via /proc/acpi/event&lt;/flag&gt;
141     &lt;flag name='spell'&gt;Enables spell checking capability using
142     dictionaries found in &lt;cat&gt;app-dict&lt;/cat&gt;&lt;/flag&gt;
143     &lt;/use&gt;
144     </pre>
145     </div>
146     <div class="section">
147 cardoe 1.2 <h1><a class="toc-backref" href="#id14" id="credits" name="credits">Credits</a></h1>
148 dev-zero 1.1 <p>Thanks to the following persons for their input on or related to this GLEP
149     (even though they might not have known it):
150     Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj),
151     Steve Dibb (beandog), and Tiziano Müller (dev-zero)</p>
152     </div>
153     <div class="section">
154 cardoe 1.2 <h1><a class="toc-backref" href="#id15" id="references" name="references">References</a></h1>
155 dev-zero 1.1 <table class="docutils footnote" frame="void" id="use-flag-metadata-bug" rules="none">
156     <colgroup><col class="label" /><col /></colgroup>
157     <tbody valign="top">
158 cardoe 1.2 <tr><td class="label"><a class="fn-backref" href="#id8" name="use-flag-metadata-bug">[1]</a></td><td><a class="reference" href="http://bugs.gentoo.org/show_bug.cgi?id=199788">http://bugs.gentoo.org/show_bug.cgi?id=199788</a></td></tr>
159 dev-zero 1.1 </tbody>
160     </table>
161     <table class="docutils footnote" frame="void" id="use-flag-metadata-example1" rules="none">
162     <colgroup><col class="label" /><col /></colgroup>
163     <tbody valign="top">
164 cardoe 1.2 <tr><td class="label"><a class="fn-backref" href="#id9" name="use-flag-metadata-example1">[2]</a></td><td><a class="reference" href="http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup">http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup</a></td></tr>
165 dev-zero 1.1 </tbody>
166     </table>
167     <table class="docutils footnote" frame="void" id="use-flag-metadata-example2" rules="none">
168     <colgroup><col class="label" /><col /></colgroup>
169     <tbody valign="top">
170 cardoe 1.2 <tr><td class="label"><a class="fn-backref" href="#id10" name="use-flag-metadata-example2">[3]</a></td><td><a class="reference" href="http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup">http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup</a></td></tr>
171 dev-zero 1.1 </tbody>
172     </table>
173 cardoe 1.2 <table class="docutils footnote" frame="void" id="devhandbook" rules="none">
174 dev-zero 1.1 <colgroup><col class="label" /><col /></colgroup>
175     <tbody valign="top">
176 cardoe 1.2 <tr><td class="label"><a name="devhandbook">[4]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> <a class="reference" href="http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4">http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&amp;chap=4</a></td></tr>
177 dev-zero 1.1 </tbody>
178     </table>
179 cardoe 1.2 <table class="docutils footnote" frame="void" id="devmanual" rules="none">
180 dev-zero 1.1 <colgroup><col class="label" /><col /></colgroup>
181     <tbody valign="top">
182 cardoe 1.2 <tr><td class="label"><a class="fn-backref" href="#id6" name="devmanual">[5]</a></td><td><a class="reference" href="http://devmanual.gentoo.org/ebuild-writing/file-format/index.html">http://devmanual.gentoo.org/ebuild-writing/file-format/index.html</a></td></tr>
183 dev-zero 1.1 </tbody>
184     </table>
185     <table class="docutils footnote" frame="void" id="motivators1" rules="none">
186     <colgroup><col class="label" /><col /></colgroup>
187     <tbody valign="top">
188     <tr><td class="label"><a class="fn-backref" href="#id1" name="motivators1">[6]</a></td><td><a class="reference" href="http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata">http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata</a></td></tr>
189     </tbody>
190     </table>
191     <table class="docutils footnote" frame="void" id="motivators2" rules="none">
192     <colgroup><col class="label" /><col /></colgroup>
193     <tbody valign="top">
194     <tr><td class="label"><a class="fn-backref" href="#id2" name="motivators2">[7]</a></td><td><a class="reference" href="http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/">http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/</a></td></tr>
195     </tbody>
196     </table>
197     <table class="docutils footnote" frame="void" id="motivators3" rules="none">
198     <colgroup><col class="label" /><col /></colgroup>
199     <tbody valign="top">
200     <tr><td class="label"><a class="fn-backref" href="#id3" name="motivators3">[8]</a></td><td><a class="reference" href="http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/">http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/</a></td></tr>
201     </tbody>
202     </table>
203     <table class="docutils footnote" frame="void" id="motivators4" rules="none">
204     <colgroup><col class="label" /><col /></colgroup>
205     <tbody valign="top">
206     <tr><td class="label"><a class="fn-backref" href="#id4" name="motivators4">[9]</a></td><td><a class="reference" href="http://technicalpickles.com/posts/pidgin-idle-time">http://technicalpickles.com/posts/pidgin-idle-time</a></td></tr>
207     </tbody>
208     </table>
209     </div>
210     <div class="section">
211 cardoe 1.2 <h1><a class="toc-backref" href="#id16" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
212     <p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information in
213     the new tags is not mandatory. Tools that currently read <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>
214     files may break if written poorly, while well written tools should just ignore
215     the additional elements. Tools which are capable of handling the new tags
216     should prefer their data over <tt class="docutils literal"><span class="pre">use.desc</span></tt> and <tt class="docutils literal"><span class="pre">use.local.desc</span></tt>.</p>
217     <p>USE flags still must be defined in <tt class="docutils literal"><span class="pre">use.desc</span></tt> or <tt class="docutils literal"><span class="pre">use.local.desc</span></tt>. If the
218     USE flag is not found in either <tt class="docutils literal"><span class="pre">use.desc</span></tt> or <tt class="docutils literal"><span class="pre">use.local.desc</span></tt>, the
219     information contained within the new tags in <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> must be ignored
220     and QA tools should warn as they currently do.</p>
221     <p>Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove
222     the <tt class="docutils literal"><span class="pre">use.local.desc</span></tt> file from CVS and it will be auto-generated for rsync.
223     This will ensure that backwards compatibility is not broken for users of
224     non-CVS trees. At this time, QA tools will need to be updated to verify the
225     contents of <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> containing the necessary tags which would appear
226     in <tt class="docutils literal"><span class="pre">use.local.desc</span></tt>.</p>
227     </div>
228     <div class="section">
229 dev-zero 1.1 <h1><a class="toc-backref" href="#id17" id="copyright" name="copyright">Copyright</a></h1>
230     <p>This document is placed into the public domain.</p>
231     <!-- vim: set ft=glep tw=72 : -->
232     </div>
234     </div>
235     <div class="footer">
236     <hr class="footer" />
237     <a class="reference" href="glep-0056.txt">View document source</a>.
238 cardoe 1.2 Generated on: 2008-07-10 18:23 UTC.
239 dev-zero 1.1 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
241     </div>
242     </body>
243     </html>

  ViewVC Help
Powered by ViewVC 1.1.20