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

Parent Directory Parent Directory | Revision Log Revision Log

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

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 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.2</td>
32 </tr>
33 <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 </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 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">13-Jun-2008</td>
46 </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 <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 <li><a class="reference" href="#copyright" id="id17" name="id17">Copyright</a></li>
60 </ul>
61 </div>
62 <div class="section">
63 <h1><a class="toc-backref" href="#id11" id="abstract" name="abstract">Abstract</a></h1>
64 <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 <h1><a class="toc-backref" href="#id12" id="motivation" name="motivation">Motivation</a></h1>
69 <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 <h1><a class="toc-backref" href="#id13" id="specification" name="specification">Specification</a></h1>
84 <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 <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 <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 <cite>Gentoo Development Guide - Ebuild File Format</cite> <a class="footnote-reference" href="#devmanual" id="id6" name="id6">[5]</a>.</p>
113 </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 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id7" name="id7">[4]</a>.</li>
123 </ul>
124 </li>
125 </ul>
126 </blockquote>
127 <p>Documentation for the Developer Manual and the metadata.dtd can be found in
128 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 <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 <h1><a class="toc-backref" href="#id14" id="credits" name="credits">Credits</a></h1>
148 <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 <h1><a class="toc-backref" href="#id15" id="references" name="references">References</a></h1>
155 <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 <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 </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 <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 </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 <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 </tbody>
172 </table>
173 <table class="docutils footnote" frame="void" id="devhandbook" rules="none">
174 <colgroup><col class="label" /><col /></colgroup>
175 <tbody valign="top">
176 <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 </tbody>
178 </table>
179 <table class="docutils footnote" frame="void" id="devmanual" rules="none">
180 <colgroup><col class="label" /><col /></colgroup>
181 <tbody valign="top">
182 <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 </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 <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 <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 Generated on: 2008-07-10 18:23 UTC.
239 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