Debian GNOME Packaging Policy

Programs that the end user can actually run (such as File Roller) should be packaged as the name of the program. Do not suffix the package with a 2 to represent the GNOME 2 package; if upstream is maintaining both GNOME 1 and GNOME 2 releases, then name the GNOME 1 package foo-gnome1 instead.

GNOME applications (not libraries) should be in the gnome section unless they are used by multiple environments (such as KDE).

If any binaries accept the standard GTK+ or GNOME command-line options, the manual pages should refer to the GTK+ and/or GNOME common command-line option manual pages, gtk-options.7 and gnome-options.7 (in the packages libgtk2.0-bin and libgnome2-common respectively).

If the upstream tarball contains API documentation for a library which is generated using gtk-doc or doxygen, it should not be regenerated during the Debian package build process. In the case of gtk-doc, this means passing the --disable-gtk-doc flag to configure. An exception to this rule is if the upstream tarball contains incomplete or old API documentation, or if it is not installed when --disable-gtk-doc is used.

API documentation should be included in the -dev package if relatively small, otherwise in a separate -doc package. API docs should be available in /usr/share/doc/[package]/, normally in a directory named after the type of file (such as html/). This is so that multiple formats can be packaged (PDF for example).

However, if gtk-doc is used to generate the API documentation, the documentation should be installed in the default location, /usr/share/gtk-doc/html/[package], with a symbolic link in /usr/share/doc/[package]/html/. ^[1] The [package].devhelp file must also be installed. This ensures that gtk-doc and other tools which use the gtk-doc metadata (such as DevHelp) can find the documentation.

TODO: There is the issue of rebuilding documentation if upstream didn't generate it with cross-references. Ideally all types will be cross-referenced, down to gint.

Many GNOME applications use GConf for preferences, and most applications provide schemas for the keys they set. These schemas must be handled specially in the package build process. There are two issues: the location of schema files on disk, and registering schemas at install time.

GConf schema files are by default installed into /etc/gconf/schemas, but as they are not configuration files we move them to /usr/share/gconf/schemas/. This can be done with the configure flag --with-gconf-schema-file-dir=/usr/share/gconf/schemas. Alternatively dh_gconf will move any schemas found in /etc/gconf/schemas if it is called in debian/rules.

If debian/rules is using CDBS, simply include /usr/share/cdbs/1/class/gnome.mk. This will call dh_gconf which will set the relevant environment variables and create the maintainer scripts. Note that dh_gconf will move the schema files from /etc/gconf/schemas to /usr/share/gconf/schemas, as GConf schemas are not configuration files.

If the package doesn't use CDBS however, before running make install, the variable GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL must be set to 1. This will ensure that the schemas are not installed on your machine in the package build tree. Then in the relevant binary- target call dh_gconf to create the maintainer scripts.

If you use dh_gconf via either CDBS or manually, you must depend on debhelper >= 4.1.87, although debhelper >= 4.2.16 is recomended for the move of schemas to /usr/share/gconf/schemas.

If user documentation exists, and an OMF file is provided, the package must depend on scrollkeeper (>= 0.3.8), and update the ScrollKeeper database in the maintainer scripts. Again, CDBS with the gnome class does this automatically, but otherwise call dh_scrollkeeper in the relevant binary- target.

If you use dh_scrollkeeper, you must depend on debhelper 4.2.1 or higher.

TODO: Panel applets -- "gnome-applet-foo" or "foo-applet" or "gnome-foo-applet"?

Panel applets must be installed into /usr/lib/gnome-panel as they are never directly executabled by the user. This applies to both shared library and executable panel applets. TODO: Or should they go into /usr/share/gnome-applets?

GTK+ 1.x engines must be named gtk-engines-[name], and GTK+ 2.x engines must named gtk2-engines-[name]. All engines should be in the gnome section.

Unless there are special requirements, GTK+ themes should not specify a font. This is because a font specified in a theme can not be changed by the user trivially.

TODO: How do we package pure gtkrc themes which use engines (such as GitM, which uses mist)? Should engine packages include a set of decent themes for this engine, even if they were not written by the same author?

TODO: Icon themes? Metacity themes?

It is recommended that any GnomeVFS methods included with a program should be packaged separately, with just the necessary shared library and the GnomeVFS module configuration file. If a package provides just a single method, it should be named like gnomevfs-method-[prefix], where [prefix] is the URI prefix that the method provides.

If a single upstream source package provides multiple methods, it may either be packaged as gnomevfs-methods-[name], where [name] is the name of the upstream source, or it may be split into multiple individual packages as above.