Debian GNOME Packaging Policy

Ross Burton

gtk-doc 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 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
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 only 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?

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. [1].The only exception to this rule is if the upstream tarballs contains incomplete or old API documentation.

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/[package]/, normally in a folder named after the type of file (such as html). This is so that multiple formats are supported, for example PDF.

Also package the package.devhelp file if it exists (gtk-doc should have generated one), in /usr/share/devhelp/specs, with a symlink in /usr/share/devhelp/books to the root of the API documentation.

DevHelp 2 introduces several new book formats to make this easier. The policy will need to be updated them, but this works for DevHelp 1.

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 /usr/share/doc at build time.

Can gtk-doc cross-reference other packages? Should we be regenerating the docs at build time with other api documentation installed so that cross-references work?

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 unimplemented in gconftool however.

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 believe 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] In the case of gtk-doc, this means passing the --disable-gtk-doc flag to configure.

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

Chapter 3. Specific Packaging Guidelines

Panel Applets

Panel applets -- "gnome-applet-foo" or "foo-applet" (TODO)

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

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