# Debian GNOME Packaging Policy

### Ross Burton

`<ross@debian.org>`

### Mikael Hallendal

Advised on correct gtk-doc usage `<micke@codefactory.se>`

### Christian Marillat

Documentation clarifications

### Bastien Nocera

### Sebastian Rittau

### Gustavo Noronha Silva

### Colin Walters

GNOME-VFS section

Copyright © 2003-4 Ross Burton

TODO: insert Open Content License or similar here

Revision History
Revision 20050123-1 | 2005-01-23
Remove section on Nautilus Views, add dh_gconf, and clarify gtk-doc paths.
Revision 20040816-1 | 2004-08-16
Quick update to cover changes up to GNOME 2.6.
Revision 20030502-1 | 2003-05-03
Clarified gtk-doc layout, added a section on the 'gnome' section, and clarified the section for engines.
Revision 20030218-1 | 2003-02-18
Rewrote section on API Documentation, after talking to gtk-doc developers.
Revision 20030119-1 | 2003-01-19
Added a section on GnomeVFS, and rewrote the API documentation section.
Revision 20030114-1 | 2003-01-14
Reformatted in DocBook.

Abstract

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

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

## Package Section

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

## Documentation

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.

## Use of GConf

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

[1] Alternatively, the documentation can be installed into `/usr/share/doc/[package]/` and a symbolic link to it created in `/usr/share/gtk-doc/html/`.

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

## 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 something sane.