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

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

Parent Directory | Revision Log | View Patch Patch

Revision 1.1		Revision 1.2
1	GLEP: 56	1	GLEP: 56
2	Title: USE flag descriptions in metadata	2	Title: USE flag descriptions in metadata
3	Version: $Revision: 1.1 $	3	Version: $Revision: 1.2 $
4	Last-Modified: $Date: 2008/06/05 05:54:10 $	4	Last-Modified: $Date: 2008/07/10 18:15:05 $
5	Author: Doug Goldstein <cardoe@gentoo.org>	5	Author: Doug Goldstein <cardoe@gentoo.org>
6	Status: Draft	6	Status: Draft
7	Type: Standards Track	7	Type: Standards Track
8	Content-Type: text/x-rst	8	Content-Type: text/x-rst
9	Created: 03-Jun-2008	9	Created: 03-Jun-2008
10	Post-History: 05-Jun-2008	10	Post-History: 13-Jun-2008
11		11
12	Abstract	12	Abstract
13	========	13	========
14		14
15	This GLEP proposes to add per-package USE flag descriptions to each package's	15	This 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
75	Documentation for the Developer Manual and the metadata.dtd can be found in	70	Documentation for the Developer Manual and the metadata.dtd can be found in
76	Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788.	71	Gentoo's Bugzilla [#use-flag-metadata-bug]_ bug #199788.
77		72
78	The following are two concrete examples in tree, [#use-flag-metadata-example1]_	73	The 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
		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
127	Copyright	145	Copyright
128	=========	146	=========
129		147
130	This document is placed into the public domain.	148	This document is placed into the public domain.
131		149

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.2
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.2
-Removed from v.1.1
+Added in v.1.2

	ViewVC Help
Powered by ViewVC 1.1.13