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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.4
1GLEP: 56 1GLEP: 56
2Title: USE flag descriptions in metadata 2Title: USE flag descriptions in metadata
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.4 $
4Last-Modified: $Date: 2008/06/05 05:54:10 $ 4Last-Modified: $Date: 2008/09/02 20:37:40 $
5Author: Doug Goldstein <cardoe@gentoo.org> 5Author: Doug Goldstein <cardoe@gentoo.org>
6Status: Draft 6Status: Final
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 03-Jun-2008 9Created: 03-Jun-2008
10Post-History: 05-Jun-2008 10Post-History: 05-June-2008, 13-Jun-2008
11 11
12Abstract 12Abstract
13======== 13========
14 14
15This GLEP proposes to add per-package USE flag descriptions to each package's 15This GLEP proposes to add per-package USE flag descriptions to each package's
40 once per USE flag as specified by the ``'name'`` attribute with the 40 once per USE flag as specified by the ``'name'`` attribute with the
41 following exception: 41 following exception:
42 42
43 * The ``'restrict'`` atttribute can limit to specific versions of the 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 44 package, where the attribute value must be a valid CPV as defined by the
45 `Package Manager Specification` [#pms]_. This follows the current behavior 45 `Gentoo Developer Handbook` [#devhandbook]_. This follows the current
46 of the ``'restrict'`` attribute in metadata.xml. 46 behavior of the ``'restrict'`` attribute in metadata.xml.
47 47
48 - The ``restrict`` attribute follows the documented ``restrict``
49 attribute in the `Gentoo Developer Handbook` [#devhandbook]_.
50
51 - e.g. A USE flag may have one behavior for version 0.1 of a package, 48 - e.g. A USE flag may have one behavior for version 0.1 of a package,
52 while version 0.2, the USE flag may differ slightly. 49 while version 0.2, the USE flag may differ slightly.
53 50
54 - Each ``<flag>`` XML tag requires a 'name' attribute which is the full USE 51 - Each ``<flag>`` XML tag requires a 'name' attribute which is the full USE
55 flag name as it would appear in the IUSE section of the ebuild. 52 flag name as it would appear in the IUSE section of the ebuild.
56 53
57 * e.g. "video_cards_i810" or "alsa" 54 * e.g. "video_cards_i810" or "alsa"
58 55
59 - Each ``<flag>`` XML tag allows 0 or more nested ``<pkg>`` XML tags whose 56 - Each ``<flag>`` XML tag allows 0 or more nested ``<pkg>`` XML tags whose
60 character data is a valid CP or CPV as defined by the 57 character data is a valid CP or CPV as defined by the
61 `Package Manager Specification` [#pms]_. 58 `Gentoo Development Manual - Ebuild File Format` [#devmanual]_.
62 59
63 - Each ``<flag>`` XML tag allows 0 or more nested ``<cat>`` XML tags whose 60 - Each ``<flag>`` XML tag allows 0 or more nested ``<cat>`` XML tags whose
64 character data is a valid category. 61 character data is a valid category.
65 62
66 - The ``<use>`` XML tag may appear multiple times inside of the 63 - The ``<use>`` XML tag may appear multiple times inside of the
68 attribute value. 65 attribute value.
69 66
70 * The ``lang`` attribute follows the documented ``lang`` attribute in the 67 * The ``lang`` attribute follows the documented ``lang`` attribute in the
71 `Gentoo Developer Handbook` [#devhandbook]_. 68 `Gentoo Developer Handbook` [#devhandbook]_.
72 69
73 * The default ``'lang'`` attribute value is "C", which is equivilent to "en". 70Documentation for the `Gentoo Developer Handbook` [#devhandbook]_ and the
74 71metadata.dtd can be found in Gentoo's Bugzilla [#use-flag-metadata-bug]_
75Documentation for the Developer Manual and the metadata.dtd can be found in 72bug #199788.
76Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788.
77 73
78The following are two concrete examples in tree, [#use-flag-metadata-example1]_ 74The following are two concrete examples in tree, [#use-flag-metadata-example1]_
79and [#use-flag-metadata-example2]_. 75and [#use-flag-metadata-example2]_.
80 76
81And the following is an embedded example and not from a real package:: 77And the following is an embedded example and not from a real package::
110 106
111.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup 107.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
112 108
113.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup 109.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
114 110
115.. [#pms] http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary 111.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
116 112
117.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4 113.. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
118 114
119.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata 115.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata
120 116
121.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/ 117.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/
122 118
123.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/ 119.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/
124 120
125.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time 121.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time
126 122
123
124Backwards Compatibility
125=======================
126
127No changes are necessary to existing ``metadata.xml`` files. Information in
128the new tags is not mandatory. Tools that currently read ``metadata.xml``
129files may break if written poorly, while well written tools should just ignore
130the additional elements. Tools which are capable of handling the new tags
131should prefer their data over ``use.desc`` and ``use.local.desc``.
132
133USE flags still must be defined in ``use.desc`` or ``use.local.desc``. If the
134USE flag is not found in either ``use.desc`` or ``use.local.desc``, the
135information contained within the new tags in ``metadata.xml`` must be ignored
136and QA tools should warn as they currently do.
137
138Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove
139the ``use.local.desc`` file from CVS and it will be auto-generated for rsync.
140This will ensure that backwards compatibility is not broken for users of
141non-CVS trees. At this time, QA tools will need to be updated to verify the
142contents of ``metadata.xml`` containing the necessary tags which would appear
143in ``use.local.desc``.
144
145
127Copyright 146Copyright
128========= 147=========
129 148
130This document is placed into the public domain. 149This document is placed into the public domain.
131 150

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4

  ViewVC Help
Powered by ViewVC 1.1.20