David Sweet <dsweet@chaos.umd.edu>
March, 11, 2000
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.2.
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, Inter-Process-Communication protocols and much 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.1 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 in ftp://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_2_RELEASE
cvs -z6 checkout -r KDE_1_1_2_RELEASE 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 -P -d 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.1!
Let's get Qt 2.1. Take the KDE copy of the current Qt library from the KDE CVS with
cvs -z6 co qt-copy
cd qt-copy
setenv QTDIR $PWD (if you use csh/tcsh)
OR
export QTDIR=`pwd` (if you use bash)
make -f Makefile.cvs (creates symlinks -without that, qt will not compile !)
./configure (-gif optionally)
make
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-copy
--with-qt-libs=/home/joedeveloper/KDE/kde-HEAD/qt-copy/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-copy
--with-qt-libs=/home/joedeveloper/KDE/kde-HEAD/qt-copy/lib
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
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. Writing documentation for KDE 2 should be done in docbook-sgml. Look at http://developer.kde.org for more details how to get the needed packages for installing the docbook tools. KDE extends these tools by the module kdesdk/ksgmltools. This module also contains information where to get the docbook tools, additional documentation as well as how to use docbook and KDE.
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 ksgmltools
in the KDE SDK which is available in the kdesdk module of CVS, kdoc
in the kdoc module. (Methods for
getting things from CVS are described above.)
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:
You can now include config.h in your source code with #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 distribute 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/kmyapp
make dist
OR
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
# AUTO 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 = AUTO
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 manuals.