RossBurton ross@debian.org MikaelHallendal micke@codefactory.se Advised on correct gtk-doc usage. ChristianMarillat Documentation clarifications BastienNocera SebastianRittau Gustavo Noronha Silva ColinWalters GNOME-VFS section This document describes the policy requirements for the packaging of GNOME programs in Debian GNU/Linux. 20030502-1 2003-05-03 Clarified gtk-doc layout, added a section on the 'gnome' section, and clarified the section for engines. 20030218-1 2003-02-18 Rewrote section on API Documentation, after talking to gtk-doc developers. 20030119-1 2003-01-19 Added a section on GnomeVFS, and rewrote the API documentation section. 20030114-1 2003-01-14 Reformatted in DocBook. 2003 Ross Burton TODO: insert Open Content License or similar here 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. 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? GNOME applications (not libraries) should be in the gnome section unless they are used by multiple environments (such as KDE). 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. 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. 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 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. 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 pathFor the details of this, see bug #155129. . 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). 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 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. 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. TODO: insert OCL