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 documenting 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.

gtk3
Since the release of gtk+-3, Gentoo has three gtk+ slots in tree. Long ago, packages tried to handle support for both gtk+-1 and gtk+-2 by using USE=gtk and USE=gtk2. However this proved to be confusing. Some packages would have both when actually only one was useful. Some other packages only had USE=gtk for gtk+-2 support. These two simple examples shows that this was the wrong approach. It created much more support than necessary and users were not happy.

At the time gtk+-3 was added to the tree, it was discussed on the mailing list and approved by other Gentoo developers that having only USE=gtk to mean "Enable gtk+ related support" was the best way to go. This means that having USE=gtk3 to enable gtk+-3 instead of gtk+-2 support is forbidden.

This still leaves a few questions for maintainers to resolve hence the following policy:
 * package is an application with support for multiple gtk+, maintainer is free to select whatever slot he desires to support. It is strongly advised to use gtk+-3 if functionality is equivalent. This is to reduce workload of bugs being triggered with one slot but not the other.
 * package is a library shipping gtk+ based library only, it must be slotted. Working with upstream on this might be needed for those who do not understand the principles of soname and soversion.
 * package is shipping gtk+ based libraries and gtk+ based utilities. Package must be slotted and binaries should be suffixed with slot.
 * package is shipping gtk+ based libraries and non-gtk+ based libraries or utilities. Package should be split or if maintenance cost if too high, USE=gtk and USE=gtk3 is allowed to enable support for gtk+:2 and gtk+:3 respectively. This should concern a minority of packages like avahi, gtk-vnc, spice-gtk, etc.

Please note that loading a gtk+-3 based library in a gtk+-2 application will fail and crash the application so it is important to properly depend on relevant USE flags and slots.

Remember: gtk USE flag means gtk+ support, whatever slot is needed by the package using it