Next Previous Table of Contents
David Sweet <dsweet@chaos.umd.edu>
August 14, 1999
To help develop KDE or a KDE application you need to know how to (i) find KDE information and code, (ii) use CVS, and (iii) compile. This document aims to help to you do these things without losing too much hair. This HOWTO is geared toward new developers, occasional developers, and anyone considering contributing the the most excellent free software project that is KDE. It addresses questions that I and others have been asking on the kde-devel mailing list recently along with some more general information. You can find a current version of this document at the KDE Developer's HOWTO homepage. To contribute, comment, or correct, please email me at dsweet@chaos.umd.edu
The K Desktop Environment is an open source Unix desktop created by volunteers from around the world. There are many ways to contribute to the project. You can write new code, improve old code, write documentation, translate to other languages, create artwork, sounds, & music, report bugs, and suggest new features. If you would like to develop code, read on. If you would like to contribute in another way, please visit the KDE web site ( http://www.kde.org name="http://www.kde.org">) for more information.
KDE uses the Qt toolkit which is developed by Troll Tech ( http://www.troll.no). The main components of the desktop are a file manager (kfm), window manager (kwm), and panel (kpanel). There are many more utilities and applications which are included in the base distribution and available elsewhere.
The primary programming language used for development is C++, although bindings are available for Python (pyKDE). The KDE code consists of libraries containing classes for, for example: (libkdecore) an application base (KApplication), accessing configuration files (KConfig), launching external processs (KProcess); (libkdeui) widgets (KEdit, KFontDialog, KToolBar, etc.); and other utility classes like KFileDialog (a file dialog) and KSpell (a spellchecker). Various desktop, configuration, and system administration utilities are also included in the distribution. These are some of the things KDE developers work on. A more recent creation is KOffice, a productivity suite which includes a word processor, spreadsheet, and presentation tool.
The currently released version of KDE is 1.1.1. KDE 1.1.2 (that's right, 1.1.2 is the name, not 1.2, according to release schedule announcments made to kde-devel by Matthias Hoelzer-Kluepfel) will introduce theme support (which allows users to dramatically change the appearance of their desktops), an integrated development environment, KDevelop, and other development tools for KDE developers, and include bugfixes. The KDE 1.1.2 release schedule current reads:
KDE 2.0, which is, perhaps, the main focus of development right now, will include rewrites or major updates of kfm, khtmlw (an HTML widget), kpanel, kmail, and maybe kwm, unicode support, and much more.
KDE 2.0 requires mico, a free CORBA implementation. CORBA is used to make the new kfm (dubbed Konquerer) easily extensible and to create a document-centric user interface for KOffice. The user can, for example, embed a chart created and edited with KSpread into a document which has text created and edited by KWord. Here's a bit from Simon Hausmann about KOM/OpenParts
OpenParts is based on KOM. It provides an easy way to graphically embed other application's "widgets" , provides a clever way to manage shared GUI elements, together with a CORBA/KOM interface/implementation of these, and it implements the basic support for the document view model, extensively used by KOffice.See kdenonbeta/corbadoc/komop.html in CVS for more.
The list kde-devel is for KDE developers in general. The kde-koffice mailing list is for developers interested in koffice, and kfm-devel is for kfm (the file manager) developers.
Send a message to either kde-devel-request or koffice-request with the message "subscribe myid@myserver" (where myid@myserver stands for your email address). Go to the KDE mail page a click on "Mailing Lists" for more information about other KDE mailing lists and the mailing list archive.
Toll Tech provides a list for users of the Qt 2.0 snapshots (discussed below). You may subscribe to this by sending an email to snapshot-users-request@troll.no with the message "subscribe".
As a KDE developer you may want or need a kde email address, like joedeveloper@kde.org. To obtain one, send an email with a polite request to Martin Konold at konold@kde.org.
To gain access to the KDE CVS respository (discussed below), you firsly need to have a good reason for wanting access. For example, you may be maintaining a CVS module. If you think you have a good reason, send a polite email request to Stephan Kulow <coolo@kde.org>.
You'll also need to send him an encrypted password to get the account set up. To create your encrpyted password, type:
perl -e print\ crypt\('passwd','sa'\)\.\"\\n\"
where passwd
is your choice of password and sa
is two random
characters from the set (a-zA-Z0-9./). The output is your encrypted
password.
The KDE CVS (Concurrent Versions System) is the source code repository for the KDE project. You can access it via (i) WWW: http://www., (ii) cvs utility, (iii) cvsup utility, or (iv) snapshots. You will need CVS access only for (ii); (i), (iii), and (iv) are read-only methods and available to the public.
The web page for method (i) explains its usage. I haven't an explanation for method (iii), cvsup, yet. Please see http://www.kde.org/cvsup.html { -- Perhaps someone who uses it will contribute a short explanation of usage and information on obtaining it. -- } The snapshots, (iv), are .tar.bz2 files which contain a section of KDE code (called "modules"; ex, kdelibs, kdeutils) as it looked on some specified day (specified in the filename: ex, kdelibs990517.tar.bz2). The snapshots are posted daily inftp://ftp.kde.org/pub/kde/unstable/CVS/snapshots. { (ii) is described below. }
The repository (or, just "CVS") stores all of the changes made to the source code by all of the contributors so that changes may be undone. Each time a user makes a change (s)he includes a comment so that the devlopment of code can be more easily followed. These comments are sent to the kde-cvs mailing list. The CVS splits into _branches_ which may contain different versions of the KDE project. For example, the two branches being developed now are KDE_1_1_BRANCH and HEAD. They both are derived from the same code (i.e., if you "undid" enough of the changes made to either branch you'd reveal identical source code) but used for different purposes. Here are some branches and descriptions for your reference:
cvs
The cvs utility is probably on your system. If not, you should visit http://www.cyclic.com/cyclic-pages/howget.html To learn to use it I would recommend reading the man page! But, I've included explanations of some common functions below.
Let's assume for this section that your username is joedeveloper
.
As written below you should enter all of these commands from some base
directory. (KDE/CVS is not a bad choice!)
Set the environment variable CVSROOT
to
:pserver:joedeveloper@cvs.kde.org:/home/kde.
Listing CVS modules You can't do this directly unfortunately. You can, however, view the contents of the file /home/kde/modules with
cvs -z6 co -c
The -z6
option tells the server to compress the code at "level 6"
before sending it to you. This may speed things up for you. (In this
case, since the module listing is small, it may not matter.)
Checking out a module, e.g. kdelibs from HEAD
cvs -z6 checkout -r HEAD kdelibs
cvs -z6 checkout kdelibs
The -r options tells cvs which branch you want to checkout from. The default is the HEAD branch.
Checking out a module, ex. kdelibs, from KDE_1_1_BRANCH
cvs -z6 checkout -r KDE_1_1_BRANCH kdelibs
Note: you could use co as an abbreviation for checkout.
Checking out an application from within a module (ex kjots, which is in the kdeutils module) from the HEAD branch
(1) cvs -z6 co -l kdeutils
(2) cvs -z6 co -l admin
(3) cvs -z6 co -l kdeutils/kjots
(4) cd kdeutils; ln -s ../admin
The -l
in line (1) tells cvs not to recurse the subdirectories of
kdeutils. This means will get the configure script and its
companions (discussed below), but none of the application source code.
Line (2) gets the admin directory which contains support files for autoconf and friends. (This directory is retrieved automatically when checking out an entire module.)
Line (3) gets the kjots source.
Line (4) makes a link to the admin directory. (This is better than copying or moving the directory here. If you leave admin where cvs put if then you can easily update the admin directory with cvs. You could also make links to admin from any other modules you check out this way and thus have only one, up-to-date copy of admin.)
Updating source code you've previously checked out (ex. kdeutils/kjots)
cvs -z6 update kdeutils/kjots
The source code for kjots on your hard drive will be updated to match
the code in the CVS. You don't need to specify the branch here. The
correct branch is stored in kdeutils/kjots/CVS/Tag
.
Commiting changes (putting them into CVS) (ex. kdeutils/kjots)
cvs -z6 commit kdeutils/jots
You'll be prompted to edit a comment. Enter a short one which desribes the changes you're making with this commmit. (You can use your editor of choice by setting the EDITOR or CVSEDITOR environment variable.)
Adding a file (ex. kdeutils/kmyapp/greatnewcode.cpp)
(create the file first!)
cd kdeutils/kmyapp
cvs add greatnewcode.cpp
cvs commit
Deleting a file (ex. kdeutils/kmyapp/badoldcode.cpp)
cd kdeutils/kmyapp
rm badoldcode.cpp
cvs remove badoldcode.cpp
cvs commit
Adding a directory (a module, like a new app) (ex. kdeutils/kmyapp, with the source file kmysource.cpp)
cd kdeutils
mkdir kmyapp
(create the kmyapp/kmysource.cpp file)
cvs add kmyapp
cvs add kmyapp/kmysource.cpp
cvs commit (actually puts the directory and file in the CVS)
Note: You need to have files in a directory to commit it.
Removing a directory (a module, like a new app) (ex. kdeutils/kmyapp)
cd kdeutils/kmyapp
(delete all files, as described above in "Deleting a file")
cd ..
cvs -P update (will remove the local kmyapp automatically)
Before you start downloading and compiling the latest sources you should be aware that there's a good chance they won't work! They are in a state of constant development so they could very well have bugs.
Knowing this, you should find a way to compile and run new KDE stuff without interfering with your existing stable KDE setup. Here's one way, using the HEAD branch as an example. We, again, assume your login is joedeveloper. We also assume that your home directory is in /home/joedeveloper. (This would be the case for Red Hat systems.)
Make a directory called KDE in the home directory of your *user* account. You should not be doing any of this as root! Make another called KDE/CVS-HEAD. cd into that directory and get the KDE sources from the HEAD branch that you want. The (minumum) modules needed to use an application are: kdesupport, kdelibs. You should compile and install them in that order (see below for compiling). Others you might want are: kdebase, kdeutils, kdegraphics, etc. Now, make a directory called KDE/kde-HEAD. This is where you'll store the compiled code from the HEAD branch -- as well as Qt 2.0!
Let's get Qt 2.0. (Get the official releascan also be found at e version. It's
available now). Put the sources in KDE/kde-HEAD. To compile the
code, cd
to KDE/kde-HEAD and
gzip -d qt-2.00.tar.gz
tar -xvf qt-2.00.tar
ln -s qt-2.00 qt
cd qt
setenv QTDIR $PWD (if you use csh/tcsh)
OR
export QTDIR=`pwd` (if you use bash)
cd configs
mv linux-g++-shared linux-g++-shared.orig
sed s/-fno-rtti// linux-g++-shared.orig > linux-g++-shared
(Note, this step may not be needed with the release version of Qt 2.0, but it shouldn't hurt.)
make linux-g++-shared
make
You should compare the files configs/linux-g++-shared and
configs/linux-g++-shared.orig if you don't know what the sed is doing.
Then look up the -fno-rtti option of egcs
if you'd like to learn more.
Now, for the KDE code. cd
to KDE/CVS-HEAD/kdesupport. Type
make -f Makefile.cvs
./configure --prefix=/home/joedeveloper/KDE/kde-HEAD
--with-qt-dir=/home/joedeveloper/KDE/kde-HEAD/qt
--with-qt-libs=/home/joedeveloper/KDE/kde-HEAD/qt/lib
make
If all goes well, then
make install
If not, try to fix things, then type
make install
Repeat this process for the other modules. You should alter the
./configure line to read
./configure --prefix=/home/joedeveloper/KDE/kde-HEAD
--with-qt-dir=/home/joedeveloper/KDE/kde-HEAD/qt
--with-qt-libs=/home/joedeveloper/KDE/kde-HEAD/qt/lib --enable-new-stuff
--enable-tutorials when you compile the code in the kdelibs module.
conf
and leave it in my CVS-HEAD directory. Then I can do a ../conf
from any module and get a good configure.cd
to /$QTDIR/extensions/imageio/src
and type make install
./configure --disable-mini-stl
(and any other options you want). And be sure you have version 2.2.7!
It's important to document your application so that end-users can make
the most of it. You should be clear and concise. Describe any
non-standard installation, usage and UI features. There's no need to
talk about how to use the File menu, for example, unless you've put
some special entry on it. Include contact and bug-reporting
information as well as a hyperlink to the application's home page.
The best way to do this is by writing SGML and processing it with
ksgml2html
.
You should also document your widgets and other classes. You can
include comments in your header ( .h
) files which describe
each public
or protected
method. It you do this as you
write the methods it will make the documentation proceSss seem easier.
(It may also help you be certain about what function(s) that method is to
perform.) The script kdoc
will turn your header files into
beautiful class documentation. You can see examples of kdoc
output if you look at
http://www.ph.unimelb.edu.au/~ssk/kde/srcdoc/kdecore/index-long.html.
This is the annotated list of the core KDE classes.
You can find ksgml2html
and kdoc
in the KDE SDK which
is available in the kdesdk module of CVS. (Methods for getting
things from CVS are described above.)
The great thing about writing your documents in SGML (Standard Generalized Markup Language) is that you can turn them into nice text, HTML, LaTeX or Postscript files.
You'll need SGML Tools which are available from
There's a good chance it's already on your system or, at least, on
your Linux distribution's CD-ROM. You should read the documentation
and look at the example.sgml
file. (On my system, RH6.0, they are in
/usr/doc/sgml-tools
). It's fairly straightforward to learn.
If you know HTML, then it's cake.
If you create an application, put the documenation in a subdirectory
of your source code directory called doc
.
To process the .sgml file, ex. mydocs.sgml, into KDE-style HTML type
ksgml2html mydocs.sgml en
where en
stands for English. You should use the code for your
language.
It's called kdoc
and is in the kdedoc subdirectory of the CVS
module kdesdk.
If you mark up your header files like this:
/**
* Short description of this class
*
* This is a longer description of my class. It does the following
* @li Some bulleted thing
* @li Some other bulleted thing
* You should use it when ... It's not appropriate for ...
*
* @author My Name <myemail@wherever.edu>
* @version 0.0.1
**/
class KMyClass
{
.
/**
* Describe method. It takes <i>argument</i> to mean ...
*
* @return A pointer to another class
* @see KOtherClass
**/
KOtherClass *method (int argument);
}
The text in the comments beginning with /**
(two asterisks,
mind you!) will be taken by kdoc
as class documentation and
formatted appropriately. You can use some HTML tags (like the
<i> above). The @author
and other tags are meaningful
to kdoc
and used for formatting.
To run kdoc
, use the following command
kdoc -dhtml -L$KDEDIR/share/kdoc -a Title header1.h header2.h ...
This instructs kdoc
to generate HTML output (the default) in the
html
directory (by the -d
option) from the specified header
files. It uses Title
as the title for the documentation. ( -a
says to do work on all header files, even if they don't "ask for it". I
haven't told you how to "ask for it." The -L
tells kdoc where
its libraries are.) Type kdoc -h
for more information.
'Packing' means putting your (in this case source) code into some format that is
These three concepts are expanded upon in the next three subsections.
The standard KDE application (or other code) source code package
includes the GNU configure
script which determines some
information about the user's system and provides it to your
source code as #define
statements in a header file called
config.h
.
To get started with this, get the kdesdk from CVS using a method described above. Then prepare kexample, an example package, for your application
cd kdesdk
cd kexample
make -f Makefile.cvs
cd ..; cp -r kexample ~/KDE/kmyapp-0.0.1
(That last directory is just an example. Replace kmyapp with your
application's (or widget's) name, and replace 0.0.1 with its version
number.)
Now, we'll put your source code into the example package. Let's say your source code was in the directory /KDE/KMyApp:
cd ~/KDE/kmyapp-0.0.1
mkdir kmyapp
cp ~/KDE/KMyApp/*.cpp kmyapp
cp ~/KDE/KMyApp/*.h kmyapp
(There may be other files to copy, but leave your old Makefile behind!)
Now, edit kmyapp-0.0.1/Makefile.am and change the line
SUBDIRS = kexample
to
SUBDIRS = kmyapp
Note: kmyapp here refers to the subdirectory by that name. You
could include more subdirectories to be compiled. For example:
SUBDIRS = kmyapp kmysupportclass
Also edit the last line of configure.in to read
AC_OUTPUT(Makefile \
kmyapp/Makefile \
po/Makefile)
The po
directory contains translations of strings that you
used in your code (this is about i18n(), which is not covered in this
HOWTO). We'll get to that it a minute.
Now we want to set up the Makefile for the kmyapp subdirectory. Edit
kmyapp/Makefile.am
according to the instructions given in the
comments. They should be clear enough.
Now cd ~/KDE/kmyapp
and type
./configure
This should create:
#include "../config.h"
and have your code compile differently on different systems based
on the #define
s. Eh? Well, different systems have slightly
differnent ideas about implementing standards and such, and your
code my need take this into account to be portable, i.e. to work on
various Unices. Take a look inside config.h
for descriptions
of the #define
s.
Shared Libraries! If you are packaging a widget or other class you should be compiling a shared library. Luckily, this is easy to do within the kexample packge. You only need to change the Makefile.am that resides in your code's sudirectory. Unluckily, now example for a shared-library Makefile.am is included. So, I've included one in the next section. Note: If you distribute a widget, you should also disrtribute a small program which tests the widget. Put that program in the same package in another subdirectory and have it compile along with the widget.
Next, make a compressed archive. You can do it this way
cd ~/KDE
tar -cvf kmyapp-0.1.1.tgz kmyapp-0.1.1
or however you like. Just be sure that the archive expands to
one directory containing all of the files. This is neater and
easier for the user to deal with.
# Example Makefile.am for a shared library. It makes a library
# called "example" as libexample.so.2.1.2
# This Makefile.am was taken from the kdelibs distribution and modified
# to serve as an example.
#
# David Sweet
#
INCLUDES= $(all_includes)
lib_LTLIBRARIES = libexample.la
# Note: If you specify a:b:c as the version in the next line,
# the library that is made has version (a-c).c.b. In this
# example, the version is 2.1.2.
libexample_la_LDFLAGS = -version-info 3:2:1 $(all_libraries)
include_HEADERS = header1.h header2.h\
header3.h
# Which headers shouldn't be installed when a make install is done?
noinst_HEADERS = version.h
libexample_la_SOURCES = code1.cpp code2.cpp
code3.cpp
# USE_AUTOMOC is great. This takes care of all of your moc'ing
# dependencies.
# (You still need to include, for example, header1.moc in code1.cpp.)
libexample_la_METASOURCES = USE_AUTOMOC
Next, you need and LSM file. You can keep a copy in kmyapp-0.1.1 for distribution.
Here's a sample .lsm
:
Begin3
Title: KLab
Version: 0.1.0
Entered-date: 3/1/99
Description: GUI and more for RLab
Keywords: kde rlab math plot plotting
Author: David Sweet <dsweet@chaos.umd.edu>
Maintained-by: David Sweet <'dsweet@chaos.umd.edu>
Home-page: http://www.glue.umd.edu/~dsweet/KDE/KLab
Primary-site: ftp://ftp.kde.org/pub/kde/unstable/apps/scientific
Alternate-site: http://www.glue.umd.edu/~dsweet/KDE/KLab/
Original-site: ftp://upload.kde.org/pub/kde/Incoming
Platform: unix
Copying-policy: GPL
End
You can copy and paste this text into a file called "kmyapp.lsm" and make the appropriate changes.
If you are hacking at CVS, you should follow the commit procedure outlined above. If you want to submit changes to code that you are not maintaining, you should first check with the maintainer of the application. You can usually find his/her email address in the directory containing the source. Also check the program's "About" box if it has one. If no maintainer is specifically listed, you should contact the author.
If you are developing outside of CVS, you can submit your code (widgets, applications, etc.) via FTP to ftp://upload.kde.org/pub/kde/Incoming
When you do this be sure to include an .lsm
(Linux Software Map) file.
This way your code can be automatically placed in the appropriate spot
on ftp.kde.org and its mirrors and an announcement can be
automatically sent to the kde-announce mailing list.
Note: The .lsm
file should be uploaded separately from the
source code (as a plain ASCII file). The source code should be
packaged as a .tar.gz (or .tgz) or .tar.bz2. This archive should
expand to a single directory with all of your stuff in it.
I'd like to thank the following people for their suggestions (in no particular order): Roberto Alsina, Waldo Bastian, Harri Porten, Samuel Wuethrich, Richard Moore, Daniel Naber, Ralf Nolden, Martin Konold, and Pietro Iglio, Stephan Kulow, Junji Takagi.
The current version of this document is available at http://www.chaos.umd.edu/~dsweet/KDE/MiniHOWTO.
A Japanese language version is available at http://www.asahi-net.or.jp/~hc3j-tkg/kde-jp/DevelMiniHOWTO-jp.txt thanks to Junji Takagi.
This document is included in the KDE Developer's Web Site ( http://developer.kde.org) and is part of the KDevelop ( http://www.kdevelop.org) programming manual.
Next Previous Table of Contents