Hi,
This is the first draft of what I think should be some of the content in
the future Debian GNOME Policy. I wrote it on a train on the way to
work, so I was tired. Expect grammar mistakes, statements which don't
make sense, etc etc...
I will reformat as DocBook when it stabilises a little.
Debian GNOME Mini-Policy
Copyright (C) 2003, Ross Burton
Version: 20020113-1
Author: Ross Burton <ross@burtonini.com>
Currently this document is simply a list of "best practises" for
packaging GNOME libraries and programs. As it evolves it should become
more organised.
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.
Nautilus views should be packaged as "nautilus-[viewname]". As they
are not executable by the user, they should 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.
Panel applets -- "gnome-applet-foo" or "foo-applet"? 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.
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?
The documentation of a program should be included in the binary
package, unless it is large, in which case a separate -doc package is
acceptable. Mention the -doc package in Debian.README. Install
documentation in /usr/share/doc/package/, and include doc-base and
.dhelp files.
The documentation of a library should be generated with a tool such as
gtk-doc or doxygen at package build time, and either included in the
-dev package if it is small, or in a separate -doc package. DEFINE
SMALL. 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").
All API documentation should include a doc-base and .dhelp file. 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. If the documentation is built with gtk-doc,
it will be installed into /usr/share/gtk-doc/html/foo. This should be
moved into /usr/share/doc at build time, either by manually moving it
or by using the --with-html-dir=... argument to ./configure which many
packages support.
If user documentation exists, and a .omf file is provided, the package
should depend on scrollkeeper, 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,
replace the URL with a absolute path.
TODO: example sed script.
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.
postinst:
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 should also un-apply the
schemas. This is currently unimplemented however.
TODO: I plan to write a dh_gconfschema helper which will auto-generate
the relevant postinst/prerm scripts.
Always remember to update the config.{guess|sub} files at build-time,
see the documentation in /usr/share/doc/autotool-dev for
details. Don't forget to build-depend on autotools-dev.
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?
Ross
--
Ross Burton mail: ross@burtonini.com
jabber: ross@nerdfest.org
www: http://www.burtonini.com./
PGP Fingerprint: 1A21 F5B0 D8D0 CFE3 81D4 E25A 2D09 E447 D0B4 33DF
Attachment:
signature.asc
Description: This is a digitally signed message part