/[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.4 - (hide annotations) (download) (as text)
Wed Apr 7 22:14:20 2010 UTC (4 years, 4 months ago) by robbat2
Branch: MAIN
CVS Tags: HEAD
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 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">
4    
5     <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 robbat2 1.4 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
8 dev-zero 1.1 <title>GLEP 56 -- USE flag descriptions in metadata</title>
9 robbat2 1.4 <link rel="stylesheet" href="tools/glep.css" type="text/css" /></head>
10 dev-zero 1.1 <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 robbat2 1.4 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.4</td>
31 dev-zero 1.1 </tr>
32 robbat2 1.4 <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 dev-zero 1.1 </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 robbat2 1.4 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Final</td>
37 dev-zero 1.1 </tr>
38     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
39     </tr>
40 robbat2 1.4 <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 dev-zero 1.1 </tr>
42     <tr class="field"><th class="field-name">Created:</th><td class="field-body">03-Jun-2008</td>
43     </tr>
44 cardoe 1.3 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">05-June-2008, 13-Jun-2008</td>
45 dev-zero 1.1 </tr>
46     </tbody>
47     </table>
48     <hr />
49 robbat2 1.4 <div class="contents topic" id="contents">
50     <p class="topic-title first">Contents</p>
51 dev-zero 1.1 <ul class="simple">
52 robbat2 1.4 <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 dev-zero 1.1 </ul>
60     </div>
61 robbat2 1.4 <div class="section" id="abstract">
62     <h1><a class="toc-backref" href="#id12">Abstract</a></h1>
63 dev-zero 1.1 <p>This GLEP proposes to add per-package USE flag descriptions to each package's
64     metadata.</p>
65     </div>
66 robbat2 1.4 <div class="section" id="motivation">
67     <h1><a class="toc-backref" href="#id13">Motivation</a></h1>
68 dev-zero 1.1 <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 robbat2 1.4 <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 dev-zero 1.1 </ul>
79     </blockquote>
80     </div>
81 robbat2 1.4 <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 dev-zero 1.1 <blockquote>
86     <ul>
87 robbat2 1.4 <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 dev-zero 1.1 following exception:</p>
90     <ul class="simple">
91 robbat2 1.4 <li>The <tt class="docutils literal">'restrict'</tt> atttribute can limit to specific versions of the
92 dev-zero 1.1 package, where the attribute value must be a valid CPV as defined by the
93 robbat2 1.4 <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 dev-zero 1.1 <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 robbat2 1.4 <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 dev-zero 1.1 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 robbat2 1.4 <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 dev-zero 1.1 character data is a valid CP or CPV as defined by the
111 robbat2 1.4 <cite>Gentoo Development Manual - Ebuild File Format</cite> <a class="footnote-reference" href="#devmanual" id="id6">[5]</a>.</p>
112 dev-zero 1.1 </li>
113 robbat2 1.4 <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 dev-zero 1.1 character data is a valid category.</p>
115     </li>
116 robbat2 1.4 <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 dev-zero 1.1 attribute value.</p>
119     <ul class="simple">
120 robbat2 1.4 <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 dev-zero 1.1 </ul>
123     </li>
124     </ul>
125     </blockquote>
126 robbat2 1.4 <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 cardoe 1.3 bug #199788.</p>
129 robbat2 1.4 <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 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 robbat2 1.4 <div class="section" id="credits">
147     <h1><a class="toc-backref" href="#id15">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 robbat2 1.4 <div class="section" id="references">
154     <h1><a class="toc-backref" href="#id16">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 robbat2 1.4 <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 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 robbat2 1.4 <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 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 robbat2 1.4 <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 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 robbat2 1.4 <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 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 robbat2 1.4 <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 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 robbat2 1.4 <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 dev-zero 1.1 </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 robbat2 1.4 <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 dev-zero 1.1 </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 robbat2 1.4 <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 dev-zero 1.1 </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 robbat2 1.4 <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 dev-zero 1.1 </tbody>
208     </table>
209     </div>
210 robbat2 1.4 <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 cardoe 1.2 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 robbat2 1.4 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 cardoe 1.2 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 robbat2 1.4 the <tt class="docutils literal">use.local.desc</tt> file from CVS and it will be auto-generated for rsync.
223 cardoe 1.2 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 robbat2 1.4 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 cardoe 1.2 </div>
228 robbat2 1.4 <div class="section" id="copyright">
229     <h1><a class="toc-backref" href="#id18">Copyright</a></h1>
230 dev-zero 1.1 <p>This document is placed into the public domain.</p>
231     <!-- vim: set ft=glep tw=72 : -->
232     </div>
233    
234     </div>
235     <div class="footer">
236     <hr class="footer" />
237 robbat2 1.4 <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.
240 dev-zero 1.1
241     </div>
242     </body>
243     </html>

  ViewVC Help
Powered by ViewVC 1.1.20