1 |
GLEP: 56 |
2 |
Title: USE flag descriptions in metadata |
3 |
Version: $Revision: 1.3 $ |
4 |
Last-Modified: $Date: 2008/07/10 22:13:45 $ |
5 |
Author: Doug Goldstein <cardoe@gentoo.org> |
6 |
Status: Final |
7 |
Type: Standards Track |
8 |
Content-Type: text/x-rst |
9 |
Created: 03-Jun-2008 |
10 |
Post-History: 05-June-2008, 13-Jun-2008 |
11 |
|
12 |
Abstract |
13 |
======== |
14 |
|
15 |
This GLEP proposes to add per-package USE flag descriptions to each package's |
16 |
metadata. |
17 |
|
18 |
|
19 |
Motivation |
20 |
========== |
21 |
|
22 |
Gives Gentoo users the ability to better identify how USE flags affect their |
23 |
installations of a given package. For example, many global USE flags have very |
24 |
generic descriptions but no specifics on how it affects a certain package. |
25 |
Specifically speaking, an example would be net-print/cups and the 'jpeg' USE |
26 |
flag. Does this flag mean you won't be able to print jpeg files? You can print |
27 |
them directly? It's interface won't use jpeg files. |
28 |
|
29 |
- Motivator References: [#motivators1]_, [#motivators2]_, [#motivators3]_, |
30 |
and [#motivators4]_ |
31 |
|
32 |
|
33 |
Specification |
34 |
============= |
35 |
|
36 |
This GLEP proposes the addition of ``<use>`` XML tag that is only allowed to |
37 |
appear inside of a ``<pkgmetadata>`` XML tag. |
38 |
|
39 |
- Inside the ``<use>`` XML tag, the ``<flag>`` XML tag is allowed to appear |
40 |
once per USE flag as specified by the ``'name'`` attribute with the |
41 |
following exception: |
42 |
|
43 |
* The ``'restrict'`` atttribute can limit to specific versions of the |
44 |
package, where the attribute value must be a valid CPV as defined by the |
45 |
`Gentoo Developer Handbook` [#devhandbook]_. This follows the current |
46 |
behavior of the ``'restrict'`` attribute in metadata.xml. |
47 |
|
48 |
- e.g. A USE flag may have one behavior for version 0.1 of a package, |
49 |
while version 0.2, the USE flag may differ slightly. |
50 |
|
51 |
- Each ``<flag>`` XML tag requires a 'name' attribute which is the full USE |
52 |
flag name as it would appear in the IUSE section of the ebuild. |
53 |
|
54 |
* e.g. "video_cards_i810" or "alsa" |
55 |
|
56 |
- Each ``<flag>`` XML tag allows 0 or more nested ``<pkg>`` XML tags whose |
57 |
character data is a valid CP or CPV as defined by the |
58 |
`Gentoo Development Manual - Ebuild File Format` [#devmanual]_. |
59 |
|
60 |
- Each ``<flag>`` XML tag allows 0 or more nested ``<cat>`` XML tags whose |
61 |
character data is a valid category. |
62 |
|
63 |
- The ``<use>`` XML tag may appear multiple times inside of the |
64 |
``<pkgmetadata>`` XML tag if and only if it contains a different ``'lang'`` |
65 |
attribute value. |
66 |
|
67 |
* The ``lang`` attribute follows the documented ``lang`` attribute in the |
68 |
`Gentoo Developer Handbook` [#devhandbook]_. |
69 |
|
70 |
Documentation for the `Gentoo Developer Handbook` [#devhandbook]_ and the |
71 |
metadata.dtd can be found in Gentoo's Bugzilla [#use-flag-metadata-bug]_ |
72 |
bug #199788. |
73 |
|
74 |
The following are two concrete examples in tree, [#use-flag-metadata-example1]_ |
75 |
and [#use-flag-metadata-example2]_. |
76 |
|
77 |
And the following is an embedded example and not from a real package:: |
78 |
|
79 |
<use> |
80 |
<flag name='acpi'>Enables HAL to attempt to read from |
81 |
/proc/acpi/event, if unavailable, HAL will read events from |
82 |
<pkg>sys-power/acpid</pkg>. If you need multiple acpi readers, |
83 |
ensure acpid is in your default runlevel |
84 |
(rc-update add acpid default) along with HAL. This will also |
85 |
enable HAL to read Toshiba and IBM acpi events which do not |
86 |
get sent via /proc/acpi/event</flag> |
87 |
<flag name='spell'>Enables spell checking capability using |
88 |
dictionaries found in <cat>app-dict</cat></flag> |
89 |
</use> |
90 |
|
91 |
|
92 |
|
93 |
Credits |
94 |
======= |
95 |
|
96 |
Thanks to the following persons for their input on or related to this GLEP |
97 |
(even though they might not have known it): |
98 |
Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj), |
99 |
Steve Dibb (beandog), and Tiziano Müller (dev-zero) |
100 |
|
101 |
|
102 |
References |
103 |
========== |
104 |
|
105 |
.. [#use-flag-metadata-bug] http://bugs.gentoo.org/show_bug.cgi?id=199788 |
106 |
|
107 |
.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup |
108 |
|
109 |
.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup |
110 |
|
111 |
.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4 |
112 |
|
113 |
.. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html |
114 |
|
115 |
.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata |
116 |
|
117 |
.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/ |
118 |
|
119 |
.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/ |
120 |
|
121 |
.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time |
122 |
|
123 |
|
124 |
Backwards Compatibility |
125 |
======================= |
126 |
|
127 |
No changes are necessary to existing ``metadata.xml`` files. Information in |
128 |
the new tags is not mandatory. Tools that currently read ``metadata.xml`` |
129 |
files may break if written poorly, while well written tools should just ignore |
130 |
the additional elements. Tools which are capable of handling the new tags |
131 |
should prefer their data over ``use.desc`` and ``use.local.desc``. |
132 |
|
133 |
USE flags still must be defined in ``use.desc`` or ``use.local.desc``. If the |
134 |
USE flag is not found in either ``use.desc`` or ``use.local.desc``, the |
135 |
information contained within the new tags in ``metadata.xml`` must be ignored |
136 |
and QA tools should warn as they currently do. |
137 |
|
138 |
Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove |
139 |
the ``use.local.desc`` file from CVS and it will be auto-generated for rsync. |
140 |
This will ensure that backwards compatibility is not broken for users of |
141 |
non-CVS trees. At this time, QA tools will need to be updated to verify the |
142 |
contents of ``metadata.xml`` containing the necessary tags which would appear |
143 |
in ``use.local.desc``. |
144 |
|
145 |
|
146 |
Copyright |
147 |
========= |
148 |
|
149 |
This document is placed into the public domain. |
150 |
|
151 |
.. vim: set ft=glep tw=72 : |
152 |
|