Debian KDE Packaging
=-=-=-=-=-=-=-=-=-=-


This document is meant as a aid for Debian Developers who are packaging
up KDE based applications.    

                              - Ivan

------------------------------------------------------------------------

=======
dh-make
=======

You can now find a dh-make template for a single binary package under

    /usr/share/doc/kdelibs4-dev/dh-make/

Refer to the dh-make man package for information on how to use these templates.
These templates include the bits mentioned in this file.


===============
KDE Menu System
===============

With the release of 3.2, KDE adopted the freedesktop.org desktop entry
specification for its menu system.  This specification is available at
http://www.freedesktop.org/Standards/desktop-entry-spec.

In versions of KDE prior to 3.2, a program's .desktop file existed in a
subdirectory of /usr/share/applnk, where the subdirectory name corresponded to
the desired submenu of the overall KDE menu.

Now, however, a program's menu entry .desktop file should exist in the
/usr/share/applications/kde directory, and should fully conform to the
freedesktop.org specification format.  Note that the KDE submenu in which the
program's entry will appear is now determined by the values given to the
Categories key in the .desktop file.  A list of suggested categories is
provided in the draft freedesktop.org menu specification, available at
http://www.freedesktop.org/Standards/menu-spec.

Up-to-date upstream source should use the freedesktop.org standard location and
format.  Presently, .desktop files in /usr/share/applnk and its subdirectories
are still incorporated into the KDE menu, for the sake of backwards
compatibility.  However, unless backwards compatibility with pre-3.2 KDE
releases is explicitly desired, a .desktop file under /usr/share/applnk and/or
one which does not conform to the freedesktop.org format should be considered
a bug.

Note that with KDE 3.2, the KDE submenu of entries generated from .desktop
files in /usr/share/applnk, and its subdirectories, is determined by the values
of the Categories key in the .desktop file, if that key exists.  If it does
not, then the KDE submenu of the entry will be determined by the name of the
/usr/share/applnk subdirectory in which the .desktop file resides.


==================
Debian Menu System
==================

Though KDE and GNOME have adopted freedesktop.org standards and thus
can share a common menu, most other desktop environments and window
managers have not, nor have most non-KDE and non-GNOME applications.
Thus Debian provides its own menu system (in the package "menu") that
all DEs and WMs use, making all installed applications consistently
accessible in all environments without configuration.  A KDE
application must therefore provide a Debian menu entry, in addition to
its entry in the native KDE menu system.

The Debian menu is added to by installing a file in /usr/lib/menu with the name
of the package.  This file contains one or more menu entries describing the one
or more applications the package provides.

The format of these menu files is described in the Debian menu policy
document, available at http://www.debian.org/doc/packaging-manuals/menu.html.
Note that Debian menu entries for KDE applications require the use of the hints
feature. Specifically, KDE based apps must include the "KDE" hint.  The minimal
hints line in a the proper menu entry of a KDE application is thus hints="KDE".

A typical menu file would therefore look like this:

   ?package(konqueror):\
        needs="x11"\
        section="Apps/Net"\
        icon="/usr/share/pixmaps/konqueror.xpm"\
        hints="KDE,Web browsers"\
        title="Konqueror"\
        command="kfmclient openProfile webbrowsing"
						   
In Debian, versions of KDE prior to 3.2 broke down the various categories of
the Debian menu, and interspersed these menu entries throughout the KDE menu,
in subfolders named "Debian".  To avoid the unnecessary and sometimes
problematic duplication of entries, the Debian menu files of KDE applications
contained the special "kderemove" tag, signalling KDE to hide the entries
of applications which it presumably already had an entry for in the native
KDE menu.

With KDE 3.2, however, the Debian menu hierarchy is taken intact and placed
into a single submenu of the KDE menu, named "Debian".  This greater separation
between the KDE and Debian menus means that duplication is unobtrusive, and
therefore that the "kderemove" tag is no longer required, and should be
removed if present.


=============
Build-Depends
=============

Build-Depends are very important in the Debian world.  Most of the package
building on non-i386 ports are done with the aid of buildd's.  Buildd's are
automated building systems that basically build packages that are not already
built for the arch they are building on.  In order to do this and actually
be successful things like Build-Depends have to be accurate.  A typical 
Build-Depends line for a KDE based application will look something like this:

  Build-Depends: automake1.8, debhelper (>> 4.2.0), kdelibs4-dev (>= 3.2.0)

Your app may need a lot more than that to actually build; however, first take a
look at the Dependencies for kdelibs4-dev:

    Depends: kdelibs4 (= 4:3.2.1-1), kdelibs-bin (= 4:3.2.1-1), libart-2.0-dev, libarts1-dev (>> 1.2.1), libcupsys2-dev, libfam-dev, libpcre3-dev, libssl-dev, libxml2-utils, libxrender-dev

and the Dependencies for libqt3-mt-dev:

    Depends: xlibs-dev (>= 4.2.1), libmng-dev (>= 1.0.3), libpng12-0-dev, libjpeg62-dev, zlib1g-dev, libfreetype6-dev, libc6-dev, libqt3c102-mt (= 3:3.2.3-2), libqt3-headers (= 3:3.2.3-2), qt3-dev-tools (= 3:3.2.3-2), xlibmesa-gl-dev | libgl-dev, xlibmesa-glu-dev | libglu1-mesa-dev | libglu-dev, libxft-dev, libxrender-dev, libxcursor-dev, libaudio-dev, xlibs-pic

so between the 2 of them you have Build-Depends that equate to:

  kdelibs4 (= 4:3.2.1-1), kdelibs-bin (= 4:3.2.1-1), libart-2.0-dev, libarts1-dev (>> 1.2.1), libaudio-dev, libc6-dev, libcupsys2-dev, libfam-dev, libfreetype6-dev, libjpeg62-dev, libmng-dev (>= 1.0.3), libpcre3-dev, libpng12-0-dev, libqt3c102-mt (= 3:3.2.3-2), libqt3-headers (= 3:3.2.3-2), libssl-dev, libxft-dev, libxml2-utils, libxcursor-dev, libxrender-dev, qt3-dev-tools (= 3:3.2.3-2), xlibmesa-gl-dev | libgl-dev, xlibmesa-glu-dev | libglu1-mesa-dev | libglu-dev, xlibs-dev (>= 4.2.1), zlib1g-dev

99% of the time that will more than cover a KDE app.  There will of course
be specific stuff you'll need to add.  For example, knetfilter requires
iptables to be installed in order for it to build, while kdemultimedia requires
ncurses, slang and other things to build.  Either way you should make sure you
get them all.


===========
debianrules
===========

    If your KDE based app uses the kde-common stuff you'll have a admin/
subdir which if it's recent will contain a debianrules perl script.
The current version of it does very little.  The biggest job it has is
to make sure that all the KDE variables are set properly for
build; this includes a configure line.

With the code in the rules file of the kde dh-make template, you can
see we create a file called debian/debiandirs which contains all the
variables like kde_htmldir set to the proper Debian settings.  It also
sets up the configkde variable which currently looks like this:

    configkde=--disable-debug --disable-rpath --prefix=$(kde_prefix) --sysconfdir=$(sysconfdir) --includedir=$(kde_includedir) --infodir=$(infodir) --mandir=$(mandir) --with-qt-dir=$(qtdir)

You can add your custom configure bits after the $(configkde).  However 9 times
out of 10 you won't have to do a thing.


====
CDBS
====

You might also want to consider building your package with the Common
Debian Build System (CDBS).  This system encapsulates the best-practices
for packaging in a central system that can be kept up-to-date independent
of the actual packages.

The simplest way to get started with CDBS is probably to use the
dh-make template described above, then add cdbs to your Build-Depends
( versionned to some recent version, like >= 0.4.21 ) and replace the
generated debian/rules file with something like the following 3 lines:

    #!/usr/bin/make -f
    include /usr/share/cdbs/1/rules/debhelper.mk
    include /usr/share/cdbs/1/class/kde.mk

Before you do anything though, you should install the cdbs package and read
its documentation; especially look in /usr/share/doc/cdbs/examples for some
more example rules files.


==================
Missing something?
==================

If there's something I'm missing from this document (and I'm sure there is)
please send mail off to debian-qt-kde@lists.debian.org and I'll get it added
for future releases.  I'd like it if this could answer 99% of the questions
one might have about packaging up a KDE based app for Debian.

Ivan

