This document describes the policy requirements for the packaging of GNOME programs. This document is only a draft, as it evolves it should become more organised.

Chapter 2. General Packaging Guidelines

Table of Contents

Package Naming
Use of GConf
Use of Scrollkeeper

Package Naming

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.

If the package contains documentation for a library which is generated using gtk-doc or doxygen, it should be regenerated during the Debian package build process. Some upstream tarballs contains complete and up-to-date API documentation, in this case it is not necessary to rebuild the documentation ^[1].

API documentation should be included in the -dev package if relativly small, otherwise in a separate -doc package. API docs should be installed in /usr/share/doc/foo-{doc|dev]/, normally in a folder named after the type of file (such as "html"). Also package the .devhelp file is it exists (gtk-doc will generate one), in /usr/share/devhelp/specs, with a symlink in /usr/share/devhelp/books to the API documentation. Note that if the documentation is built with gtk-doc, it will be installed into /usr/share/gtk-doc/html/[foo]. This must be moved into the doc directory at package build time.

If the binaries accept the standard GTK+/GNOME options, in the manual pages refer to the GNOME options manual page . TODO: what was the status with this? Is it packaged anywhere?

Use of GConf

Many GNOME applications use GConf for preferences, and they should all provide schemas. These must be installed specially -- before running "make install", GCONF_DISABLE_MAKEFILE_SCHEMA_INSTALL=1 must be set. This will ensure that the schemas are not installed onto your local machine in the package build tree. Then, in the postinst script, register the schemas manually with the following code snippet.

if [ "$1" = "configure" ]; then
    SCHEMA_FILES="foo.schemas bar.schemas"
    for SCHEMA in $SCHEMA_FILES; do
        if [ -e /etc/gconf/schemas/$SCHEMA ]; then
            HOME=/root GCONF_CONFIG_SOURCE=`gconftool-2 --get-default-source` \
            gconftool-2 \
            --makefile-install-rule /etc/gconf/schemas/$SCHEMA > /dev/null
        fi
    done
fi

Simply change the value of SCHEMA_FILES to list all of the schema files, in /etc/gconf/schemas.

When gconftool supports it, the prerm script must also un-apply the schemas when the package is being purged. This is currently unimplemented in gconftool however.

A helper script, dh_gconf, is being written at the moment. This will mean that you do not have to manually create the scripts, but simply call dh_gconf in the binary-* target. It will find any GConf schemas which need to be installed, and register them.

Use of Scrollkeeper

If user documentation exists, and a .omf file is provided, the package must depend on scrollkeeper (>= 0.3.8), and register the documentation in postinst/unregister in prerm.

postinst:

scrollkeeper-update -q

postrm:

if [ "$1" = "remove" ]; then
    scrollkeeper-update -q
fi

Currently, Debian has no XML catalogue. This means that when Scrollkeeper is used to register user documentation, it will try and connect to the Internet and download a DTD. As a temporary measure, you must replace the URL with a absolute local path. For the details of this, see bug #155129.

An example of this would to be to put this in the build target:

find -name '*.xml' -exec perl -i -pe 's,http://www.oasis-open.org/docbook/xml/([^/]+)/docbookx.dtd,/usr/share/sgml/docbook/dtd/xml/\1/docbookx.dtd,' {} \;
find -name '*.omf' -exec perl -i -pe 's,http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd,/usr/share/xml/scrollkeeper/dtds/scrollkeeper-omf.dtd,' {} \;

Run this one-liner before running 'make', and the reverse transformation in the 'clean' target to avoid redundant diffs.

^[1]In the case of gtk-doc, this means passing the --disable-gtk-doc flag to configure.

Chapter 3. Specific Packaging Guidelines

Table of Contents

Panel Applets
Nautilus View
Themes and Theme Engines

Panel Applets

Panel applets -- "gnome-applet-foo" or "foo-applet" (TODO)? If the applet is a binary, these are not directly executable so should be installed into /usr/lib/gnome-panel. If the applet is a shared object, also install it into /usr/lib/gnome-panel, as another program cannot directly link to it.

Nautilus View

Nautilus views should be packaged as "nautilus-[viewname]". As they are not executable by the user, they must be installed into /usr/lib/nautilus. Note that often upstream .server files hard-code /usr/lib, and this will require editing of the Makefile and .server files.

Themes and Theme Engines

GTK+ 1.x engines are named gtk-engines-foo. GTK+ 2.x engines are named gtk2-engines-foo. Note that unless there are special requirements, GTK+ themes should not specify a font. How do we package pure gtkrc themes which use engines (such as GitM, which uses gtk2-engines-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? Metathemes?

Chapter 4. License

TODO: insert OCL

Re: Debian GNOME Policy, Mark II

Debian GNOME Packaging Policy

Ross Burton

Chapter 1. Introduction