/[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.2
1GLEP: 56 1GLEP: 56
2Title: USE flag descriptions in metadata 2Title: USE flag descriptions in metadata
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.2 $
4Last-Modified: $Date: 2008/06/05 05:54:10 $ 4Last-Modified: $Date: 2008/07/10 18:15:05 $
5Author: Doug Goldstein <cardoe@gentoo.org> 5Author: Doug Goldstein <cardoe@gentoo.org>
6Status: Draft 6Status: Draft
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: 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 Guide - 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
67 ``<pkgmetadata>`` XML tag if and only if it contains a different ``'lang'`` 64 ``<pkgmetadata>`` XML tag if and only if it contains a different ``'lang'``
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
73 * The default ``'lang'`` attribute value is "C", which is equivilent to "en".
74 69
75Documentation for the Developer Manual and the metadata.dtd can be found in 70Documentation for the Developer Manual and the metadata.dtd can be found in
76Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788. 71Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788.
77 72
78The following are two concrete examples in tree, [#use-flag-metadata-example1]_ 73The following are two concrete examples in tree, [#use-flag-metadata-example1]_
110 105
111.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup 106.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup
112 107
113.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup 108.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup
114 109
115.. [#pms] http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git;a=summary 110.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4
116 111
117.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4 112.. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html
118 113
119.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata 114.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata
120 115
121.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/ 116.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/
122 117
123.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/ 118.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/
124 119
125.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time 120.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time
126 121
122
123Backwards Compatibility
124=======================
125
126No changes are necessary to existing ``metadata.xml`` files. Information in
127the new tags is not mandatory. Tools that currently read ``metadata.xml``
128files may break if written poorly, while well written tools should just ignore
129the additional elements. Tools which are capable of handling the new tags
130should prefer their data over ``use.desc`` and ``use.local.desc``.
131
132USE flags still must be defined in ``use.desc`` or ``use.local.desc``. If the
133USE flag is not found in either ``use.desc`` or ``use.local.desc``, the
134information contained within the new tags in ``metadata.xml`` must be ignored
135and QA tools should warn as they currently do.
136
137Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove
138the ``use.local.desc`` file from CVS and it will be auto-generated for rsync.
139This will ensure that backwards compatibility is not broken for users of
140non-CVS trees. At this time, QA tools will need to be updated to verify the
141contents of ``metadata.xml`` containing the necessary tags which would appear
142in ``use.local.desc``.
143
144
127Copyright 145Copyright
128========= 146=========
129 147
130This document is placed into the public domain. 148This document is placed into the public domain.
131 149

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

  ViewVC Help
Powered by ViewVC 1.1.20