Debian GNOME Packaging Policy

Ross Burton

Advised on correct gtk-doc usage.: Mikael Hallendal

Documentation clarifications: Christian Marillat

Bastien Nocera

Sebastian Rittau

Gustavo Noronha Silva

GNOME-VFS section: Colin Walters

TODO: insert Open Content License or similar here
Revision History
Revision 20030502-12003-05-03
Clarified gtk-doc layout, added a section on the 'gnome' section, and clarified the section for engines.
Revision 20030218-12003-02-18
Rewrote section on API Documentation, after talking to gtk-doc developers.
Revision 20030119-12003-01-19
Added a section on GnomeVFS, and rewrote the API documentation section.
Revision 20030114-12003-01-14
Reformatted in DocBook.

Abstract

This document describes the policy requirements for the packaging of GNOME programs in Debian GNU/Linux.


Table of Contents

1. Introduction
2. General Packaging Guidelines
Package Naming
Package Section
API Documentation
Use of GConf
Use of Scrollkeeper
3. Specific Packaging Guidelines
Panel Applets
Nautilus View
Themes and Theme Engines
GnomeVFS Methods
4. License

Chapter 1. Introduction

This document describes the policy requirements for the packaging of GNOME programs.

This document is currently a draft, as it evolves it should become more organised.

This document only mentions packaging guidelines appropriate for GNOME packages. The Debian Policy still applies to all packages.

Chapter 2. General Packaging Guidelines

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 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?

Package Section

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

API Documentation

If the upstream tarball contains 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).

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

Use of GConf

Many GNOME applications use GConf for preferences, and they should all provide schemas for the keys they set. These must be installed specially. 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 postinst maintainer 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
      

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 implemented only in the development gconftool at present.

A DebHelper script, dh_gconf, is being written. 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 correctly.

GConf schemas are installed into /etc/gconf/schemas, but they are not configuration files. Havoc has said that this was a mistake, and they should be in /usr/share. I really want to force a relocation of GConf schemas into /usr/share/gconf/schemas. Havoc has said that this may expose lots of bugs in programs install rules. I don't believe it will be that many. I think that if we put our collective feet down and move schemas to /usr/share where they belong, we can fix any bugs we find and then upstream GConf can be corrected.

Use of Scrollkeeper

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 postinst and postrm scripts. A DebHelper script to do this is currently being written, but for now use the following snippets.

postinst:

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

postrm:

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

Currently, Debian has no XML catalogue of available DTDs. However, it looks like it is coming at last. This means that when Scrollkeeper registers the documentation, it will try and connect to the Internet to download a DTD. As a temporary measure, you must replace the URL with an absolute local path[2].

An example snippet of code to remove the remote URLs:

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 these lines before running make, and the reverse transformation in the clean target (to avoid redundant lines in the diff).



[1] Alternatively, the documentation can be installed into /usr/share/doc/... and a symlink to it created in the correct place in /usr/share/gtk-doc/html.

[2] For the details of this, see bug #155129.

Chapter 3. Specific Packaging Guidelines

Panel Applets

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?

Nautilus View

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

Themes and Theme Engines

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?

GnomeVFS Methods

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.

Chapter 4. License

TODO: insert OCL