GNOME 2.x Platform Interface Specification
Contents
Introduction
This document describes how the GNOME community ensures Platform stability, for instance by listing which GNOME interfaces are Stable, how these interfaces evolve over time, and by listing stability issues. This helps interface consumers (free/open software developers and ISV's, for example) integrate with the GNOME desktop. A program that depends only on Stable interfaces should not need to be recompiled when the user upgrades to new versions of GNOME Stable interfaces.
Different GNOME distributors (e.g. Linux, Solaris, etc. distributions) may support GNOME interfaces differently, so this specification does not imply vendor support. Check with your vendor for specific details.
This document is maintained at http://live.gnome.org/InterfaceSpecification so that interested people within the GNOME community can help document, review, and keep the information up-to-date.
GNOME Interface Stability
The GNOME desktop includes many interfaces, but not all are intended for general use.
Note that the Linux Standards Base (LSB) has set up a Desktop Working Group which is working to standardize interfaces used in the Desktop, including interfaces that the GNOME Desktop depends upon such as glib, ATK, and GTK+. This work is a strong recommendation for the interface stability of these modules.
Software Developer Interfaces
The GNOME Platform and GNOME Platform Bindings modules follow API/ABI stability rules to ensure backwards compatibility. These should be used when writing a GNOME application. GNOME Desktop modules do not offer stable interfaces, unless their documentation clearly marks them as being Stable.
Some parts of the GNOME Platform API may be deprecated. It is recommended that use of deprecated ABI should be avoided and you should minimize dependencies on these interfaces. Instead use any recommended replacement. Refer to the interface documentation for the module to determine which interfaces may be deprecated. This said, deprecated API/ABI will remain stable for any existing applications which use them.
Some GNOME Platform libraries are completely deprecated. The GNOME API Interface Documentation highlights which interfaces are deprecated or planned for deprecation. Also refer to ProjectRidley, which is a project to consolidate the GNOME Platform into a more well organized set of libraries.
The GNOME community might one day create a new ABI-incompatible major version. If they do so, current planning is that this would install in parallel with the existing GNOME functionality which would become deprecated.
Desktop Integration Interfaces
The GNOME community follows FreeDesktop.org specifications to provide interfaces needed by interface consumers for integration tasks, such as adding an application to the menu or updating the MIME database. These specifications are shared between the GNOME and KDE desktops, so applications should work properly in all desktop environments following FreeDesktop specification. The Portland project is working on stability issues concerning the FreeDesktop specifications.
Documentation
Refer to the GNOME Documentation Library.
API Documentation
The GNOME community provides extensive API Reference Documentation. If Stability is required in your application, please make sure that an interface is in the GNOME Platform or otherwise clearly marked as Stable before depending on it. Applications that depend on non-Stable interfaces may need to be recompiled to work with future releases of GNOME.
Most GNOME Platform libraries use gtk-doc to specify appropriate stability levels for exposed interfaces. However any documentation mechanism can be used, as long as the stability levels are clearly defined. Non-library API should also be documented and an appropriate stability level specified. The man page is typically the appropriate place to document non-library API. Some modules use gtk-docs to document non-library API (such as glib-gettextize in glib), which is also acceptable.
FreeDesktop Specifications
The FreeDesktop organization provides numerous Specifications that are used across different free desktop environments, such as GNOME and KDE.
GNOME 2.x Release Notes
THE GNOME Release notes are a useful resource for understanding the evolution of the GNOME desktop from a high level.
Definitions
To provide interface stability, terms like "Interface", "Stable", and "Unstable" must have strong definitions. We must also identify how library versioning relates to stability. This document uses the following definitions.
Interface
The following is a list of interfaces that can impact Stability
- Libraries - APIs (Application Programming Interface) and ABIs (Application Binary Interface).
- Command Line Interface (CLI) - used by applications, configuration, and administration tools
- Input/Output file formats (GConf keys for example)
- Resource, configuration, and log file names and formats and location
- Protocols or inter-component messages
- Environment variables that affect program execution
- URLs (e.g. web interfaces used by weather, stock-ticket, etc. applets or made visibile in programs like gnome-about)
Changes to these interfaces should not break the way applications interact with the GNOME desktop, or break how GNOME modules interact with each other. For example, users should be able to use multiple versions of the GNOME desktop using the same $HOME directory and not experience conflicts caused by
Interface Stability Levels
Interfaces within GNOME are described as being Stable, Unstable, Private, or Internal. These terms have the following meanings:
Level |
Meaning |
Stable |
A Stable interface allows third parties to develop applications to these interfaces, release them, and have confidence that they will run on all minor releases of the product (after the one in which the interface was introduced, and within the same major release). Even at a major release, incompatible changes should be be rare, and have strong justifications. |
Unstable |
Unstable interfaces are experimental or transitional. They provide early access to new unfinished technology, or provide an interim solution to a problem before a more general solution is available. No claims are made about either source or binary compatibility from one minor release to the next. The Unstable interface level is a warning that these interfaces are subject to change without warning and should not be used in unbundled products. (MurrayCumming:What does unbundled mean here?) Nevertheless, changes to these interfaces should still be mentioned in the release notes. |
Private |
An Private interface is intended to be used by other modules in the GNOME stack, but is not intended for end-users. Such functions should only be used in specified and documented ways. Interfaces with "private" in their name (such as "bonobo_activation_private" are considered Private. |
Internal |
An interface that is internal to a module and does not require end-user documentation. Functions that are not documented are assumed to be Internal. This level does not require documentation. |
Deprecated/Obsolete |
An interface that is not recommended for use. There should be an alternative. However applications that depend on the interface should still be supported. Users of the interface are recommended to upgrade. |
Types Of Interfaces
Within the GNOME stack, there are the following types of interfaces:
Interface Type |
Description |
Desktop Integration |
Interfaces needed to integrate an application into the GNOME desktop |
Software Developer |
Interfaces provided by the GNOME stack which can be used to write an application |
System Administrator |
Interfaces to customize the GNOME desktop for a particular machine or set of machines |
There is a close relationship between Desktop Integration and Software Developer interfaces since applications written with GNOME developer interfaces will also likely integrate with the GNOME desktop. Desktop Integration interfaces are separated into a separate category because these interfaces are also used to integrate non-GNOME applications into the GNOME desktop.
Desktop Integration interfaces tend to be described by FreeDesktop.org and Software Developer interfaces tend to be described by gtk-doc style interface documentation.
Library Versioning
The GNOME release team recommends that GNOME libraries use the following Making A Release process, which recommends that GNOME Platform libraries use libtool to version libraries. When used properly, libtool follows a MAJOR.MINOR.MICRO (x.y.z) versioning system.
Term |
Definition |
Major |
Incremented when the interfaces are changed in ways that are ABI incompatible. When incremented Minor and Micro become 0. |
Minor |
Incremented when interfaces are added or deprecated. In other words, only ABI compatible interfaces changes are allowed. When incremented Micro becomes 0. |
Micro |
Incremented when only bugs that do not affect interfaces are fixed. |
Note that this applies to library version numbers and not tarball version numbers. The tarball version number tends to follow the desktop version number for many GNOME modules, so for GNOME 2.10, the module tarballs will be named 2.10.z. This means that you cannot tell how interfaces have changed from the module version number. That said, GNOME Platform interfaces follow ABI policy, so these interfaces should not break when the minor or micro version number changes for either the library or the tarball.
TODO: The text there for "Major" is contrary to what is said in the "Making A Release" page : "The string is of the form C:R:A.. If interfaces have been changed or added, but binary compatibility has been preserved, change to C+1:0:A+1". I think you are maybe talking about the version number in the filename, which is not a one-to-one mapping with the --version-info number that influences it. I've mentioned this before, but please don't just delete my comment this time until we get this cleared up and have made it easy for people to know what to do. MurrayCumming
Requirements
All GNOME modules must follow GNOME Module Requirements. GNOME Platform interfaces must also follow GNOME Platform Requirements and GNOME Platform Bindings must follow GNOME Platform Bindings Requirements.
Note that some programs that are distributed with GNOME may not officially be a part of the GNOME desktop. Many distributions ship additional programs from other locations (such as SourceForge). So, do not assume that all programs with the GNOME look-and-feel is a part of the official GNOME desktop. Only programs that are a part of the official GNOME desktop are required to follow these requirements.
GNOME API documentation is generally in gtk-doc format, and the GNOME stack provides the following API documentation. Maintainers are expected to properly document any changes as described in the requirements above.
All GNOME modules should meet the following requirements:
Follow recommendations at the GNOME Release Team's Maintainer's Corner
- If a non-Platform module exports an interface that should be maintained as Stable, the interface should be clearly marked as such in the documentation.
- Efforts should be made to respect sane file system organization. Files should not clutter /usr/share, all programs installed to /bin, and /sbin should have man pages, programs not intended to be run by the end-user (daemons/helper utilities) should be installed to /libexec, etc.
- All files should be correctly identified with their associated license (GPL, LGPL, etc.).
Process
The GNOME Release Planning Team strives to ensure the quality and stability of GNOME interfaces. Refer to their website for more information about the processes in place to achieve this.
The Release Planning team manages the various freezes (UI, string, functionality), manage the GNOME release schedule, and help improve quality. However it is the expectation that each GNOME module maintainer is careful to ensure they meet the requirements associated with the module.
The GNOME community will obviously treat any interface stability breakage as a bug, and will strive to address the problem. However, users are expected to restrict their usage to Stable interfaces. Breakages caused by using non-Stable interfaces (including undocumented interfaces) may not be addressed. Since GNOME is Free Software, interface consumers may also contribute directly to help address any issues.
Addressing Stability Issues
We recommend that interface consumers test their applications against GNOME beta releases, particularly the Beta2 releases. The GNOME Developer's Release Start Page contains links to the release schedule. This gives interface consumers an opportunity to report bugs to the GNOME community with enough time for the issues to be addressed before final release.
Issues affecting stability, including interface documentation errors, should be reported to GNOME Bugzilla with the "blocking" keyword and given a high priority.
Process Recommendations
For maintainers...
Please follow the requirements and advice as appropriate for the type of module you maintain.
The Glib and GTK+ modules includes explicit listings of the ABI (gtk.symbols, etc.) and running 'make check' verifies that the built libraries conform to that list of symbols. This should be more widely used by Platform libraries.
The Glib and GTK+ modules filter out private interfaces from libraries by using the "LIBTOOL_EXPORT_OPTIONS='-export-symbols-regex "[[_]].*" configure option. This should be more widely used by Platform libriares.
Interface Table