en/glep/glep-0056.txt

GLEP: 56
Title: USE flag descriptions in metadata
Version: $Revision: 1.3 $
Last-Modified: $Date: 2008/07/10 22:13:45 $
Author: Doug Goldstein <cardoe@gentoo.org>
Status: Final
Type: Standards Track
Content-Type: text/x-rst
Created: 03-Jun-2008
Post-History: 05-June-2008, 13-Jun-2008

Abstract
========

This GLEP proposes to add per-package USE flag descriptions to each package's
metadata.


Motivation
==========

Gives Gentoo users the ability to better identify how USE flags affect their
installations of a given package. For example, many global USE flags have very
generic descriptions but no specifics on how it affects a certain package.
Specifically speaking, an example would be net-print/cups and the 'jpeg' USE
flag. Does this flag mean you won't be able to print jpeg files? You can print
them directly? It's interface won't use jpeg files.

 - Motivator References: [#motivators1]_, [#motivators2]_, [#motivators3]_,
   and [#motivators4]_


Specification
=============

This GLEP proposes the addition of ``<use>`` XML tag that is only allowed to
appear inside of a ``<pkgmetadata>`` XML tag.

 - Inside the ``<use>`` XML tag, the ``<flag>`` XML tag is allowed to appear
   once per USE flag as specified by the ``'name'`` attribute with the
   following exception:
   
   * The ``'restrict'`` atttribute can limit to specific versions of the
     package, where the attribute value must be a valid CPV as defined by the
     `Gentoo Developer Handbook` [#devhandbook]_.  This follows the current
     behavior of the ``'restrict'`` attribute in metadata.xml. 
     
     - e.g. A USE flag may have one behavior for version 0.1 of a package,
       while version 0.2, the USE flag may differ slightly.

 - Each ``<flag>`` XML tag requires a 'name' attribute which is the full USE
   flag name as it would appear in the IUSE section of the ebuild.
    
    * e.g. "video_cards_i810" or "alsa"

 - Each ``<flag>`` XML tag allows 0 or more nested ``<pkg>`` XML tags whose
   character data is a valid CP or CPV as defined by the
   `Gentoo Development Manual - Ebuild File Format` [#devmanual]_.

 - Each ``<flag>`` XML tag allows 0 or more nested ``<cat>`` XML tags whose
   character data is a valid category.

 - The ``<use>`` XML tag may appear multiple times inside of the
   ``<pkgmetadata>`` XML tag if and only if it contains a different ``'lang'``
   attribute value.

   * The ``lang`` attribute follows the documented ``lang`` attribute in the
     `Gentoo Developer Handbook` [#devhandbook]_.

Documentation for the `Gentoo Developer Handbook` [#devhandbook]_ and the
metadata.dtd can be found in Gentoo's Bugzilla [#use-flag-metadata-bug]_
bug #199788.

The following are two concrete examples in tree, [#use-flag-metadata-example1]_
and [#use-flag-metadata-example2]_.

And the following is an embedded example and not from a real package::

        <use>
                <flag name='acpi'>Enables HAL to attempt to read from
                /proc/acpi/event, if unavailable, HAL will read events from
                <pkg>sys-power/acpid</pkg>. If you need multiple acpi readers,
                ensure acpid is in your default runlevel
                (rc-update add acpid default) along with HAL. This will also
                enable HAL to read Toshiba and IBM acpi events which do not
                get sent via /proc/acpi/event</flag>
                <flag name='spell'>Enables spell checking capability using
                dictionaries found in <cat>app-dict</cat></flag>
        </use>


Credits
=======

Thanks to the following persons for their input on or related to this GLEP
(even though they might not have known it):
Diego Pettenò (flameeyes), Alec Warner (antarus), Joshua Nichols (nichoj),
Steve Dibb (beandog), and Tiziano Müller (dev-zero)


References
==========

.. [#use-flag-metadata-bug] http://bugs.gentoo.org/show_bug.cgi?id=199788

.. [#use-flag-metadata-example1] http://sources.gentoo.org/viewcvs.py/gentoo-x86/sys-apps/hal/metadata.xml?view=markup

.. [#use-flag-metadata-example2] http://sources.gentoo.org/viewcvs.py/gentoo-x86/media-tv/mythtv/metadata.xml?view=markup 

.. [#devhandbook] http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4

.. [#devmanual] http://devmanual.gentoo.org/ebuild-writing/file-format/index.html

.. [#motivators1] http://blog.flameeyes.eu/articles/2007/11/19/lets-actually-get-some-metadata

.. [#motivators2] http://blog.cardoe.com/archives/2007/11/19/use-flag-metadata/

.. [#motivators3] http://blog.cardoe.com/archives/2007/11/23/metadataxml-updates-examples/

.. [#motivators4] http://technicalpickles.com/posts/pidgin-idle-time


Backwards Compatibility
=======================

No changes are necessary to existing ``metadata.xml`` files. Information in
the new tags is not mandatory. Tools that currently read ``metadata.xml``
files may break if written poorly, while well written tools should just ignore
the additional elements. Tools which are capable of handling the new tags
should prefer their data over ``use.desc`` and ``use.local.desc``.

USE flags still must be defined in ``use.desc`` or ``use.local.desc``. If the
USE flag is not found in either ``use.desc`` or ``use.local.desc``, the
information contained within the new tags in ``metadata.xml`` must be ignored
and QA tools should warn as they currently do.

Once this GLEP is approved, the Gentoo Infrastructure Team will work to remove
the ``use.local.desc`` file from CVS and it will be auto-generated for rsync.
This will ensure that backwards compatibility is not broken for users of
non-CVS trees. At this time, QA tools will need to be updated to verify the
contents of ``metadata.xml`` containing the necessary tags which would appear
in ``use.local.desc``.


Copyright
=========

This document is placed into the public domain.

.. vim: set ft=glep tw=72 :
1	dev-zero	1.1	GLEP: 56
2			Title: USE flag descriptions in metadata
3	cardoe	1.4	Version: $Revision: 1.3 $
4			Last-Modified: $Date: 2008/07/10 22:13:45 $
5	dev-zero	1.1	Author: Doug Goldstein <cardoe@gentoo.org>
6	cardoe	1.4	Status: Final
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 :