Project:GNOME/Gnome Team Ebuild Policies

This page is a draft.

This page is intended to link or to write down Gnome team policies about its own packages or how packages using Gnome team packages as dependencies should handle some particular aspects.

gtk-doc
gtk-doc is the framework for documentating libraries for developer audience. It provides tools to extract, compile and install documentation from the source code of the library directly. In gentoo, this used to be handled by USE=doc for all packages using gnome2.eclass however the behavior was not fit to what users expected. After much discussion gnome team came to the following conclusions:
 * gtk-doc must always be installed. gtk-doc is part of the package as distributed by upstream (pre-built), hence it costs no extra CPU time, no extra dependencies and has relatively low disk space requirements. Corollary, there is no need to rebuild documentation, so just pass --disable-gtk-doc to configure.
 * gtk-doc must be installed in /usr/share/gtk-doc. gtk-doc is a framework for documentation, just like any other framework, files targeted for it must be usually be installed in a defined place to be any useful (such as in devhelp). Also, until there is a better solution, this allows users to easily avoid any gtk-doc documentation if they have no use for it by using install-mask feature.
 * All packages using gtk-doc must DEPEND on gtk-doc-am. This package provides macros for autoreconf and tools to relink installed documentation to local resources instead of http://library.gnome.org.

introspection
The introspection USE flag is used to control whether or not a package should install its gobject-introspection description files. This is currently mainly used throughout Gnome for using regular C libraries transparently from languages such as python and javascript.

Current policy is: * make support optional only when it is possible * make use flag default enabled when support is optional. Since it is used throughout the Gnome desktop, it is simpler to default it to be enabled since most user will want it and will not want to change this USE flag on a per-package basis when portage will check the dependencies. Exceptions are system packages such as udev until libgudev is eventually split. * in all cases make sure to add [introspection] or [introspection?] (depending on the case) to required dependencies according to build system information and .gir files.