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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (show annotations) (download) (as text)
Wed Apr 7 22:14:20 2010 UTC (8 years, 3 months ago) by robbat2
Branch: MAIN
Changes since 1.3: +71 -316 lines
File MIME type: text/html
Sync to 1.4 of glep-0056.txt (no embedded styles now, final state already).

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.6: 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" /></head>
10 <body bgcolor="white">
11 <table class="navigation" cellpadding="0" cellspacing="0"
12 width="100%" border="0">
13 <tr><td class="navicon" width="150" height="35">
14 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
15 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
16 border="0" width="150" height="35" /></a></td>
17 <td class="textlinks" align="left">
18 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
19 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
20 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0056.txt">GLEP Source</a></b>]
21 </td></tr></table>
22 <table class="rfc2822 docutils field-list" frame="void" rules="none">
23 <col class="field-name" />
24 <col class="field-body" />
25 <tbody valign="top">
26 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">56</td>
27 </tr>
28 <tr class="field"><th class="field-name">Title:</th><td class="field-body">USE flag descriptions in metadata</td>
29 </tr>
30 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.4</td>
31 </tr>
32 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0056.txt?cvsroot=gentoo">2008/09/02 20:37:40</a></td>
33 </tr>
34 <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>
35 </tr>
36 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
37 </tr>
38 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
39 </tr>
40 <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="glep-0002.html">text/x-rst</a></td>
41 </tr>
42 <tr class="field"><th class="field-name">Created:</th><td class="field-body">03-Jun-2008</td>
43 </tr>
44 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">05-June-2008, 13-Jun-2008</td>
45 </tr>
46 </tbody>
47 </table>
48 <hr />
49 <div class="contents topic" id="contents">
50 <p class="topic-title first">Contents</p>
51 <ul class="simple">
52 <li><a class="reference internal" href="#abstract" id="id12">Abstract</a></li>
53 <li><a class="reference internal" href="#motivation" id="id13">Motivation</a></li>
54 <li><a class="reference internal" href="#specification" id="id14">Specification</a></li>
55 <li><a class="reference internal" href="#credits" id="id15">Credits</a></li>
56 <li><a class="reference internal" href="#references" id="id16">References</a></li>
57 <li><a class="reference internal" href="#backwards-compatibility" id="id17">Backwards Compatibility</a></li>
58 <li><a class="reference internal" href="#copyright" id="id18">Copyright</a></li>
59 </ul>
60 </div>
61 <div class="section" id="abstract">
62 <h1><a class="toc-backref" href="#id12">Abstract</a></h1>
63 <p>This GLEP proposes to add per-package USE flag descriptions to each package's
64 metadata.</p>
65 </div>
66 <div class="section" id="motivation">
67 <h1><a class="toc-backref" href="#id13">Motivation</a></h1>
68 <p>Gives Gentoo users the ability to better identify how USE flags affect their
69 installations of a given package. For example, many global USE flags have very
70 generic descriptions but no specifics on how it affects a certain package.
71 Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
72 flag. Does this flag mean you won't be able to print jpeg files? You can print
73 them directly? It's interface won't use jpeg files.</p>
74 <blockquote>
75 <ul class="simple">
76 <li>Motivator References: <a class="footnote-reference" href="#motivators1" id="id1">[6]</a>, <a class="footnote-reference" href="#motivators2" id="id2">[7]</a>, <a class="footnote-reference" href="#motivators3" id="id3">[8]</a>,
77 and <a class="footnote-reference" href="#motivators4" id="id4">[9]</a></li>
78 </ul>
79 </blockquote>
80 </div>
81 <div class="section" id="specification">
82 <h1><a class="toc-backref" href="#id14">Specification</a></h1>
83 <p>This GLEP proposes the addition of <tt class="docutils literal">&lt;use&gt;</tt> XML tag that is only allowed to
84 appear inside of a <tt class="docutils literal">&lt;pkgmetadata&gt;</tt> XML tag.</p>
85 <blockquote>
86 <ul>
87 <li><p class="first">Inside the <tt class="docutils literal">&lt;use&gt;</tt> XML tag, the <tt class="docutils literal">&lt;flag&gt;</tt> XML tag is allowed to appear
88 once per USE flag as specified by the <tt class="docutils literal">'name'</tt> attribute with the
89 following exception:</p>
90 <ul class="simple">
91 <li>The <tt class="docutils literal">'restrict'</tt> atttribute can limit to specific versions of the
92 package, where the attribute value must be a valid CPV as defined by the
93 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id5">[4]</a>. This follows the current
94 behavior of the <tt class="docutils literal">'restrict'</tt> attribute in metadata.xml.<ul>
95 <li>e.g. A USE flag may have one behavior for version 0.1 of a package,
96 while version 0.2, the USE flag may differ slightly.</li>
97 </ul>
98 </li>
99 </ul>
100 </li>
101 <li><p class="first">Each <tt class="docutils literal">&lt;flag&gt;</tt> XML tag requires a 'name' attribute which is the full USE
102 flag name as it would appear in the IUSE section of the ebuild.</p>
103 <blockquote>
104 <ul class="simple">
105 <li>e.g. &quot;video_cards_i810&quot; or &quot;alsa&quot;</li>
106 </ul>
107 </blockquote>
108 </li>
109 <li><p class="first">Each <tt class="docutils literal">&lt;flag&gt;</tt> XML tag allows 0 or more nested <tt class="docutils literal">&lt;pkg&gt;</tt> XML tags whose
110 character data is a valid CP or CPV as defined by the
111 <cite>Gentoo Development Manual - Ebuild File Format</cite> <a class="footnote-reference" href="#devmanual" id="id6">[5]</a>.</p>
112 </li>
113 <li><p class="first">Each <tt class="docutils literal">&lt;flag&gt;</tt> XML tag allows 0 or more nested <tt class="docutils literal">&lt;cat&gt;</tt> XML tags whose
114 character data is a valid category.</p>
115 </li>
116 <li><p class="first">The <tt class="docutils literal">&lt;use&gt;</tt> XML tag may appear multiple times inside of the
117 <tt class="docutils literal">&lt;pkgmetadata&gt;</tt> XML tag if and only if it contains a different <tt class="docutils literal">'lang'</tt>
118 attribute value.</p>
119 <ul class="simple">
120 <li>The <tt class="docutils literal">lang</tt> attribute follows the documented <tt class="docutils literal">lang</tt> attribute in the
121 <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id7">[4]</a>.</li>
122 </ul>
123 </li>
124 </ul>
125 </blockquote>
126 <p>Documentation for the <cite>Gentoo Developer Handbook</cite> <a class="footnote-reference" href="#devhandbook" id="id8">[4]</a> and the
127 metadata.dtd can be found in Gentoo's Bugzilla <a class="footnote-reference" href="#use-flag-metadata-bug" id="id9">[1]</a>
128 bug #199788.</p>
129 <p>The following are two concrete examples in tree, <a class="footnote-reference" href="#use-flag-metadata-example1" id="id10">[2]</a>
130 and <a class="footnote-reference" href="#use-flag-metadata-example2" id="id11">[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" id="credits">
147 <h1><a class="toc-backref" href="#id15">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" id="references">
154 <h1><a class="toc-backref" href="#id16">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="#id9">[1]</a></td><td><a class="reference external" 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="#id10">[2]</a></td><td><a class="reference external" 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="#id11">[3]</a></td><td><a class="reference external" 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">[4]</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 external" 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">[5]</a></td><td><a class="reference external" 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">[6]</a></td><td><a class="reference external" 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">[7]</a></td><td><a class="reference external" 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">[8]</a></td><td><a class="reference external" 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">[9]</a></td><td><a class="reference external" 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" id="backwards-compatibility">
211 <h1><a class="toc-backref" href="#id17">Backwards Compatibility</a></h1>
212 <p>No changes are necessary to existing <tt class="docutils literal">metadata.xml</tt> files. Information in
213 the new tags is not mandatory. Tools that currently read <tt class="docutils literal">metadata.xml</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">use.desc</tt> and <tt class="docutils literal">use.local.desc</tt>.</p>
217 <p>USE flags still must be defined in <tt class="docutils literal">use.desc</tt> or <tt class="docutils literal">use.local.desc</tt>. If the
218 USE flag is not found in either <tt class="docutils literal">use.desc</tt> or <tt class="docutils literal">use.local.desc</tt>, the
219 information contained within the new tags in <tt class="docutils literal">metadata.xml</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">use.local.desc</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">metadata.xml</tt> containing the necessary tags which would appear
226 in <tt class="docutils literal">use.local.desc</tt>.</p>
227 </div>
228 <div class="section" id="copyright">
229 <h1><a class="toc-backref" href="#id18">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 external" href="glep-0056.txt">View document source</a>.
238 Generated on: 2010-04-07 22:13 UTC.
239 Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
241 </div>
242 </body>
243 </html>

  ViewVC Help
Powered by ViewVC 1.1.20