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: [6], [7], [8], and [9]

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 Package Manager Specification [4]. This follows the current behavior of the 'restrict' attribute in metadata.xml.
    • The restrict attribute follows the documented restrict attribute in the Gentoo Developer Handbook [5].
    • 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 Package Manager Specification [4].

• 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 [5].
  • The default 'lang' attribute value is "C", which is equivilent to "en".

Documentation for the Developer Manual and the metadata.dtd can be found in Gentoo's Bugzilla [1] bug #199788.

The following are two concrete examples in tree, [2] and [3].

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

Copyright

This document is placed into the public domain.