/[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.3 - (hide annotations) (download)
Thu Jul 10 22:13:45 2008 UTC (6 years ago) by cardoe
Branch: MAIN
Changes since 1.2: +8 -7 lines
File MIME type: text/plain
Gentoo Development Guide -> Gentoo Development Manual. Correct referrence to Developer Manual to Gentoo Development Handbook. Mark as Accepted since it was approved by Council vote.

1 dev-zero 1.1 GLEP: 56
2     Title: USE flag descriptions in metadata
3 cardoe 1.3 Version: $Revision: 1.2 $
4     Last-Modified: $Date: 2008/07/10 18:15:05 $
5 dev-zero 1.1 Author: Doug Goldstein <cardoe@gentoo.org>
6 cardoe 1.3 Status: Accepted
7 dev-zero 1.1 Type: Standards Track
8     Content-Type: text/x-rst
9     Created: 03-Jun-2008
10 cardoe 1.3 Post-History: 05-June-2008, 13-Jun-2008
11 dev-zero 1.1
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 cardoe 1.2 `Gentoo Developer Handbook` [#devhandbook]_. This follows the current
46     behavior of the ``'restrict'`` attribute in metadata.xml.
47 dev-zero 1.1
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 cardoe 1.3 `Gentoo Development Manual - Ebuild File Format` [#devmanual]_.
59 dev-zero 1.1
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 cardoe 1.3 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 dev-zero 1.1
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 cardoe 1.2 .. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
112 dev-zero 1.1
113 cardoe 1.2 .. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
114 dev-zero 1.1
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 cardoe 1.2
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 dev-zero 1.1 Copyright
147     =========
148    
149     This document is placed into the public domain.
150    
151     .. vim: set ft=glep tw=72 :

  ViewVC Help
Powered by ViewVC 1.1.20