/[gentoo]/xml/htdocs/proj/en/glep/glep-0056.html
Gentoo

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (show annotations) (download) (as text)
Thu Jul 10 22:14:40 2008 UTC (6 years, 4 months ago) by cardoe
Branch: MAIN
Changes since 1.2: +273 -29 lines
File MIME type: text/html
update html of GLEP 56

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">
4
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 <style type="text/css">
10
11 /*
12 :Author: David Goodger
13 :Contact: goodger@users.sourceforge.net
14 :date: $Date: 2003/06/02 17:03:08 $
15 :version: $Revision: 1.1 $
16 :copyright: This stylesheet has been placed in the public domain.
17
18 Default cascading style sheet for the PEP HTML output of Docutils.
19 */
20
21 .first {
22 margin-top: 0 }
23
24 .last {
25 margin-bottom: 0 }
26
27 .navigation {
28 width: 100% ;
29 background: #cc99ff ;
30 margin-top: 0px ;
31 margin-bottom: 0px }
32
33 .navigation .navicon {
34 width: 150px ;
35 height: 35px }
36
37 .navigation .textlinks {
38 padding-left: 1em ;
39 text-align: left }
40
41 .navigation td, .navigation th {
42 padding-left: 0em ;
43 padding-right: 0em ;
44 vertical-align: middle }
45
46 .rfc2822 {
47 margin-top: 0.5em ;
48 margin-left: 0.5em ;
49 margin-right: 0.5em ;
50 margin-bottom: 0em }
51
52 .rfc2822 td {
53 text-align: left }
54
55 .rfc2822 th.field-name {
56 text-align: right ;
57 font-family: sans-serif ;
58 padding-right: 0.5em ;
59 font-weight: bold ;
60 margin-bottom: 0em }
61
62 a.toc-backref {
63 text-decoration: none ;
64 color: black }
65
66 body {
67 margin: 0px ;
68 margin-bottom: 1em ;
69 padding: 0px }
70
71 dd {
72 margin-bottom: 0.5em }
73
74 div.section {
75 margin-left: 1em ;
76 margin-right: 1em ;
77 margin-bottom: 1.5em }
78
79 div.section div.section {
80 margin-left: 0em ;
81 margin-right: 0em ;
82 margin-top: 1.5em }
83
84 div.abstract {
85 margin: 2em 5em }
86
87 div.abstract p.topic-title {
88 font-weight: bold ;
89 text-align: center }
90
91 div.attention, div.caution, div.danger, div.error, div.hint,
92 div.important, div.note, div.tip, div.warning {
93 margin: 2em ;
94 border: medium outset ;
95 padding: 1em }
96
97 div.attention p.admonition-title, div.caution p.admonition-title,
98 div.danger p.admonition-title, div.error p.admonition-title,
99 div.warning p.admonition-title {
100 color: red ;
101 font-weight: bold ;
102 font-family: sans-serif }
103
104 div.hint p.admonition-title, div.important p.admonition-title,
105 div.note p.admonition-title, div.tip p.admonition-title {
106 font-weight: bold ;
107 font-family: sans-serif }
108
109 div.figure {
110 margin-left: 2em }
111
112 div.footer, div.header {
113 font-size: smaller }
114
115 div.footer {
116 margin-left: 1em ;
117 margin-right: 1em }
118
119 div.system-messages {
120 margin: 5em }
121
122 div.system-messages h1 {
123 color: red }
124
125 div.system-message {
126 border: medium outset ;
127 padding: 1em }
128
129 div.system-message p.system-message-title {
130 color: red ;
131 font-weight: bold }
132
133 div.topic {
134 margin: 2em }
135
136 h1 {
137 font-family: sans-serif ;
138 font-size: large }
139
140 h2 {
141 font-family: sans-serif ;
142 font-size: medium }
143
144 h3 {
145 font-family: sans-serif ;
146 font-size: small }
147
148 h4 {
149 font-family: sans-serif ;
150 font-style: italic ;
151 font-size: small }
152
153 h5 {
154 font-family: sans-serif;
155 font-size: x-small }
156
157 h6 {
158 font-family: sans-serif;
159 font-style: italic ;
160 font-size: x-small }
161
162 .section hr {
163 width: 75% }
164
165 ol.simple, ul.simple {
166 margin-bottom: 1em }
167
168 ol.arabic {
169 list-style: decimal }
170
171 ol.loweralpha {
172 list-style: lower-alpha }
173
174 ol.upperalpha {
175 list-style: upper-alpha }
176
177 ol.lowerroman {
178 list-style: lower-roman }
179
180 ol.upperroman {
181 list-style: upper-roman }
182
183 p.caption {
184 font-style: italic }
185
186 p.credits {
187 font-style: italic ;
188 font-size: smaller }
189
190 p.label {
191 white-space: nowrap }
192
193 p.topic-title {
194 font-family: sans-serif ;
195 font-weight: bold }
196
197 pre.line-block {
198 font-family: serif ;
199 font-size: 100% }
200
201 pre.literal-block, pre.doctest-block {
202 margin-left: 2em ;
203 margin-right: 2em ;
204 background-color: #eeeeee }
205
206 span.classifier {
207 font-family: sans-serif ;
208 font-style: oblique }
209
210 span.classifier-delimiter {
211 font-family: sans-serif ;
212 font-weight: bold }
213
214 span.interpreted {
215 font-family: sans-serif }
216
217 span.option-argument {
218 font-style: italic }
219
220 span.pre {
221 white-space: pre }
222
223 span.problematic {
224 color: red }
225
226 table {
227 margin-top: 0.5em ;
228 margin-bottom: 0.5em }
229
230 td, th {
231 padding-left: 0.5em ;
232 padding-right: 0.5em ;
233 vertical-align: top }
234
235 td.num {
236 text-align: right }
237
238 th.field-name {
239 font-weight: bold ;
240 text-align: left ;
241 white-space: nowrap }
242
243 h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
244 font-size: 100% }
245
246 tt {
247 background-color: #eeeeee }
248
249 ul.auto-toc {
250 list-style-type: none }
251
252 </style>
253 </head>
254 <body bgcolor="white">
255 <table class="navigation" cellpadding="0" cellspacing="0"
256 width="100%" border="0">
257 <tr><td class="navicon" width="150" height="35">
258 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
259 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
260 border="0" width="150" height="35" /></a></td>
261 <td class="textlinks" align="left">
262 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
263 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
264 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0056.txt">GLEP Source</a></b>]
265 </td></tr></table>
266 <table class="rfc2822 docutils field-list" frame="void" rules="none">
267 <col class="field-name" />
268 <col class="field-body" />
269 <tbody valign="top">
270 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">56</td>
271 </tr>
272 <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag descriptions in metadata</td>
273 </tr>
274 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.3</td>
275 </tr>
276 <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 22:13:45</a></td>
277 </tr>
278 <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>
279 </tr>
280 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Accepted</td>
281 </tr>
282 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
283 </tr>
284 <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>
285 </tr>
286 <tr class="field"><th class="field-name">Created:</th><td class="field-body">03-Jun-2008</td>
287 </tr>
288 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">05-June-2008, 13-Jun-2008</td>
289 </tr>
290 </tbody>
291 </table>
292 <hr />
293 <div class="contents topic">
294 <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
295 <ul class="simple">
296 <li><a class="reference" href="#abstract" id="id12" name="id12">Abstract</a></li>
297 <li><a class="reference" href="#motivation" id="id13" name="id13">Motivation</a></li>
298 <li><a class="reference" href="#specification" id="id14" name="id14">Specification</a></li>
299 <li><a class="reference" href="#credits" id="id15" name="id15">Credits</a></li>
300 <li><a class="reference" href="#references" id="id16" name="id16">References</a></li>
301 <li><a class="reference" href="#backwards-compatibility" id="id17" name="id17">Backwards Compatibility</a></li>
302 <li><a class="reference" href="#copyright" id="id18" name="id18">Copyright</a></li>
303 </ul>
304 </div>
305 <div class="section">
306 <h1><a class="toc-backref" href="#id12" id="abstract" name="abstract">Abstract</a></h1>
307 <p>This GLEP proposes to add per-package USE flag descriptions to each package's
308 metadata.</p>
309 </div>
310 <div class="section">
311 <h1><a class="toc-backref" href="#id13" id="motivation" name="motivation">Motivation</a></h1>
312 <p>Gives Gentoo users the ability to better identify how USE flags affect their
313 installations of a given package. For example, many global USE flags have very
314 generic descriptions but no specifics on how it affects a certain package.
315 Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
316 flag. Does this flag mean you won't be able to print jpeg files? You can print
317 them directly? It's interface won't use jpeg files.</p>
318 <blockquote>
319 <ul class="simple">
320 <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>,
321 and <a class="footnote-reference" href="#motivators4" id="id4" name="id4">[9]</a></li>
322 </ul>
323 </blockquote>
324 </div>
325 <div class="section">
326 <h1><a class="toc-backref" href="#id14" id="specification" name="specification">Specification</a></h1>
327 <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
328 appear inside of a <tt class="docutils literal"><span class="pre">&lt;pkgmetadata&gt;</span></tt> XML tag.</p>
329 <blockquote>
330 <ul>
331 <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
332 once per USE flag as specified by the <tt class="docutils literal"><span class="pre">'name'</span></tt> attribute with the
333 following exception:</p>
334 <ul class="simple">
335 <li>The <tt class="docutils literal"><span class="pre">'restrict'</span></tt> atttribute can limit to specific versions of the
336 package, where the attribute value must be a valid CPV as defined by the
337 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id5" name="id5">[4]</a>. This follows the current
338 behavior of the <tt class="docutils literal"><span class="pre">'restrict'</span></tt> attribute in metadata.xml.<ul>
339 <li>e.g. A USE flag may have one behavior for version 0.1 of a package,
340 while version 0.2, the USE flag may differ slightly.</li>
341 </ul>
342 </li>
343 </ul>
344 </li>
345 <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
346 flag name as it would appear in the IUSE section of the ebuild.</p>
347 <blockquote>
348 <ul class="simple">
349 <li>e.g. &quot;video_cards_i810&quot; or &quot;alsa&quot;</li>
350 </ul>
351 </blockquote>
352 </li>
353 <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
354 character data is a valid CP or CPV as defined by the
355 <cite>Gentoo Development Manual - Ebuild File Format</cite> <a class="footnote-reference" href="#devmanual" id="id6" name="id6">[5]</a>.</p>
356 </li>
357 <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
358 character data is a valid category.</p>
359 </li>
360 <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
361 <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>
362 attribute value.</p>
363 <ul class="simple">
364 <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
365 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id7" name="id7">[4]</a>.</li>
366 </ul>
367 </li>
368 </ul>
369 </blockquote>
370 <p>Documentation for the <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id8" name="id8">[4]</a> and the
371 metadata.dtd can be found in Gentoo's Bugzilla <a class="footnote-reference" href="#use-flag-metadata-bug" id="id9" name="id9">[1]</a>
372 bug #199788.</p>
373 <p>The following are two concrete examples in tree, <a class="footnote-reference" href="#use-flag-metadata-example1" id="id10" name="id10">[2]</a>
374 and <a class="footnote-reference" href="#use-flag-metadata-example2" id="id11" name="id11">[3]</a>.</p>
375 <p>And the following is an embedded example and not from a real package:</p>
376 <pre class="literal-block">
377 &lt;use&gt;
378 &lt;flag name='acpi'&gt;Enables HAL to attempt to read from
379 /proc/acpi/event, if unavailable, HAL will read events from
380 &lt;pkg&gt;sys-power/acpid&lt;/pkg&gt;. If you need multiple acpi readers,
381 ensure acpid is in your default runlevel
382 (rc-update add acpid default) along with HAL. This will also
383 enable HAL to read Toshiba and IBM acpi events which do not
384 get sent via /proc/acpi/event&lt;/flag&gt;
385 &lt;flag name='spell'&gt;Enables spell checking capability using
386 dictionaries found in &lt;cat&gt;app-dict&lt;/cat&gt;&lt;/flag&gt;
387 &lt;/use&gt;
388 </pre>
389 </div>
390 <div class="section">
391 <h1><a class="toc-backref" href="#id15" id="credits" name="credits">Credits</a></h1>
392 <p>Thanks to the following persons for their input on or related to this GLEP
393 (even though they might not have known it):
394 Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj),
395 Steve Dibb (beandog), and Tiziano Müller (dev-zero)</p>
396 </div>
397 <div class="section">
398 <h1><a class="toc-backref" href="#id16" id="references" name="references">References</a></h1>
399 <table class="docutils footnote" frame="void" id="use-flag-metadata-bug" rules="none">
400 <colgroup><col class="label" /><col /></colgroup>
401 <tbody valign="top">
402 <tr><td class="label"><a class="fn-backref" href="#id9" 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>
403 </tbody>
404 </table>
405 <table class="docutils footnote" frame="void" id="use-flag-metadata-example1" rules="none">
406 <colgroup><col class="label" /><col /></colgroup>
407 <tbody valign="top">
408 <tr><td class="label"><a class="fn-backref" href="#id10" 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>
409 </tbody>
410 </table>
411 <table class="docutils footnote" frame="void" id="use-flag-metadata-example2" rules="none">
412 <colgroup><col class="label" /><col /></colgroup>
413 <tbody valign="top">
414 <tr><td class="label"><a class="fn-backref" href="#id11" 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>
415 </tbody>
416 </table>
417 <table class="docutils footnote" frame="void" id="devhandbook" rules="none">
418 <colgroup><col class="label" /><col /></colgroup>
419 <tbody valign="top">
420 <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>, <a class="fn-backref" href="#id8">3</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>
421 </tbody>
422 </table>
423 <table class="docutils footnote" frame="void" id="devmanual" rules="none">
424 <colgroup><col class="label" /><col /></colgroup>
425 <tbody valign="top">
426 <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>
427 </tbody>
428 </table>
429 <table class="docutils footnote" frame="void" id="motivators1" rules="none">
430 <colgroup><col class="label" /><col /></colgroup>
431 <tbody valign="top">
432 <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>
433 </tbody>
434 </table>
435 <table class="docutils footnote" frame="void" id="motivators2" rules="none">
436 <colgroup><col class="label" /><col /></colgroup>
437 <tbody valign="top">
438 <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>
439 </tbody>
440 </table>
441 <table class="docutils footnote" frame="void" id="motivators3" rules="none">
442 <colgroup><col class="label" /><col /></colgroup>
443 <tbody valign="top">
444 <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>
445 </tbody>
446 </table>
447 <table class="docutils footnote" frame="void" id="motivators4" rules="none">
448 <colgroup><col class="label" /><col /></colgroup>
449 <tbody valign="top">
450 <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>
451 </tbody>
452 </table>
453 </div>
454 <div class="section">
455 <h1><a class="toc-backref" href="#id17" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
456 <p>No changes are necessary to existing <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> files. Information in
457 the new tags is not mandatory. Tools that currently read <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>
458 files may break if written poorly, while well written tools should just ignore
459 the additional elements. Tools which are capable of handling the new tags
460 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>
461 <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
462 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
463 information contained within the new tags in <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> must be ignored
464 and QA tools should warn as they currently do.</p>
465 <p>Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove
466 the <tt class="docutils literal"><span class="pre">use.local.desc</span></tt> file from CVS and it will be auto-generated for rsync.
467 This will ensure that backwards compatibility is not broken for users of
468 non-CVS trees. At this time, QA tools will need to be updated to verify the
469 contents of <tt class="docutils literal"><span class="pre">metadata.xml</span></tt> containing the necessary tags which would appear
470 in <tt class="docutils literal"><span class="pre">use.local.desc</span></tt>.</p>
471 </div>
472 <div class="section">
473 <h1><a class="toc-backref" href="#id18" id="copyright" name="copyright">Copyright</a></h1>
474 <p>This document is placed into the public domain.</p>
475 <!-- vim: set ft=glep tw=72 : -->
476 </div>
477
478 </div>
479 <div class="footer">
480 <hr class="footer" />
481 <a class="reference" href="glep-0056.txt">View document source</a>.
482 Generated on: 2008-07-10 22:14 UTC.
483 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.
484
485 </div>
486 </body>
487 </html>

  ViewVC Help
Powered by ViewVC 1.1.20