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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations) (download)
Thu Jul 10 18:15:05 2008 UTC (6 years, 3 months ago) by cardoe
Branch: MAIN
Changes since 1.1: +31 -13 lines
File MIME type: text/plain
remove references to PMS. Add backwards compat section. Remove default lang reference. Add details about what data should be preferred in different situations

1 GLEP: 56
2 Title: USE flag descriptions in metadata
3 Version: $Revision: 1.1 $
4 Last-Modified: $Date: 2008/06/05 05:54:10 $
5 Author: Doug Goldstein <cardoe@gentoo.org>
6 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 03-Jun-2008
10 Post-History: 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 Guide - 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 Developer Manual and the metadata.dtd can be found in
71 Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788.
72
73 The following are two concrete examples in tree, [#use-flag-metadata-example1]_
74 and [#use-flag-metadata-example2]_.
75
76 And the following is an embedded example and not from a real package::
77
78 <use>
79 <flag name='acpi'>Enables HAL to attempt to read from
80 /proc/acpi/event, if unavailable, HAL will read events from
81 <pkg>sys-power/acpid</pkg>. If you need multiple acpi readers,
82 ensure acpid is in your default runlevel
83 (rc-update add acpid default) along with HAL. This will also
84 enable HAL to read Toshiba and IBM acpi events which do not
85 get sent via /proc/acpi/event</flag>
86 <flag name='spell'>Enables spell checking capability using
87 dictionaries found in <cat>app-dict</cat></flag>
88 </use>
89
90
91
92 Credits
93 =======
94
95 Thanks to the following persons for their input on or related to this GLEP
96 (even though they might not have known it):
97 Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj),
98 Steve Dibb (beandog), and Tiziano Müller (dev-zero)
99
100
101 References
102 ==========
103
104 .. [#use-flag-metadata-bug] http://bugs.gentoo.org/show_bug.cgi?id=199788
105
106 .. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
107
108 .. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
109
110 .. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
111
112 .. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
113
114 .. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata
115
116 .. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/
117
118 .. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/
119
120 .. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time
121
122
123 Backwards Compatibility
124 =======================
125
126 No changes are necessary to existing ``metadata.xml`` files. Information in
127 the new tags is not mandatory. Tools that currently read ``metadata.xml``
128 files may break if written poorly, while well written tools should just ignore
129 the additional elements. Tools which are capable of handling the new tags
130 should prefer their data over ``use.desc`` and ``use.local.desc``.
131
132 USE flags still must be defined in ``use.desc`` or ``use.local.desc``. If the
133 USE flag is not found in either ``use.desc`` or ``use.local.desc``, the
134 information contained within the new tags in ``metadata.xml`` must be ignored
135 and QA tools should warn as they currently do.
136
137 Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove
138 the ``use.local.desc`` file from CVS and it will be auto-generated for rsync.
139 This will ensure that backwards compatibility is not broken for users of
140 non-CVS trees. At this time, QA tools will need to be updated to verify the
141 contents of ``metadata.xml`` containing the necessary tags which would appear
142 in ``use.local.desc``.
143
144
145 Copyright
146 =========
147
148 This document is placed into the public domain.
149
150 .. vim: set ft=glep tw=72 :

  ViewVC Help
Powered by ViewVC 1.1.20