/[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 - (hide annotations) (download)
Thu Jul 10 18:15:05 2008 UTC (6 years 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 dev-zero 1.1 GLEP: 56
2     Title: USE flag descriptions in metadata
3 cardoe 1.2 Version: $Revision: 1.1 $
4     Last-Modified: $Date: 2008/06/05 05:54:10 $
5 dev-zero 1.1 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 cardoe 1.2 Post-History: 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.2 `Gentoo Development Guide - 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     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 cardoe 1.2 .. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
111 dev-zero 1.1
112 cardoe 1.2 .. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
113 dev-zero 1.1
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 cardoe 1.2
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 dev-zero 1.1 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