Copyright © 2000 David Sweet
Copyright © 2003 Caleb Tennis
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 you do these things without losing too much hair.
This HOWTO is geared toward new developers, occasional developers, and anyone considering contributing to 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 web page. To contribute, comment, or
correct, please email me at <caleb@aei-tech.com>
Table of Contents
Table of Contents
The K Desktop Environment is an open source Unix (Linux, FreeBSD, etc.) 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 i18n.kde.org (translators), artist.kde.org (artists), or the KDE web site (http://www.kde.org) for more information.
KDE uses the GPL Qt toolkit which is developed by (Troll Tech). The main components of the desktop are a file manager/webbrowser (konqueror), window manager (kwin), and panel (kicker). 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 many other languages. The KDE code consists of libraries containing classes for, for example:
(libkdecore) an application base (Kapplication), accessing configuration files (KConfig), launching external processes,
(libkdeui) widgets (KFontDialog, KToolBar, etc.),
(libkhtml) KHTML - a full-fledged, HTML 4.0 compliant HTML rendering widget
(libkio) class for implementing network-transparent file access (KIO::NetAccess), and
other utility classes like KFileDialog (a file dialog), KSpell (a spellchecker), and more
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, presentation tool, figure editor, image editor, and more. The currently released version of KDE is 3.1.
The main KDE web site is at: http://www.kde.org.
The developer's library is at: http://developer.kde.org.
Bug reports can be found at (and sent to): http://bugs.kde.org.
Troll Tech (makers of the Qt toolkit) main site: http://www.trolltech.com.
KDE Source Code and binaries: ftp://ftp.kde.org (or mirrors)
Qt Source Code and binaries: ftp://ftp.trolltech.com
KDEs source repository on the web http://websvn.kde.org.
Crossreferenced KDE source http://lxr.kde.org.
There are several mailing lists used by the KDE project. The list kde-devel is for all KDE developers, kde-core-devel is for developer who work on KDE itself. The kde-koffice mailing list is for developers interested in koffice, and kfm-devel is for kfm (the file manager) developers (acutally, it is used for development of konqueror now). More mailing lists are available and are listed at http://www.kde.org/contact.html.
To subscribe, send a message to either
<mailinglistname-request@kde.org> with the message
"subscribe myid@myserver" (where myid@myserver stands for your email
address). For example, to subscribe to kde-devel,
send your email to <kde-devel-request@kde.org>.
A mailing list archive is available at lists.kde.org.
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 the KDE system administrators at <sysadmin@office.kde.org>.
Table of Contents
The KDE CVS (Concurrent Versions System) is the source code repository for the KDE project. You can access it via
(i) World Wide Web: websvn.kde.org,
(ii) the svn command line utility,
(iv) by downloading snapshots (.tar.bz2 files) via FTP, or
(v) through a graphical subversion frontend.
Methods (i), (iii), and (iv) are read-only methods and are available to the public. Methods (ii) and (v) allow either read-only or read-write access to the CVS repository depending on your setup.
The web page for method (i) explains its usage. For method (iii), please see http://developer.kde.org/source/anonsvn.html.
The snapshots, (iv), are .tar.bz2 files which contain a section of KDE code (called a "module"; 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/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-commits mailing list. CVS can be tagged at any time so that the current state can be later recalled. Also, the CVS may branch off into different lines of development; the branches start at the tag points. The branch tagged "HEAD" is used for regular development of the next version of KDE. Near release times the CVS is tagged with different names to help organize the release. The last tag as of this writing was KDE_3_1_BRANCH.
Access through the svn command line utility (ii) and the graphical svn frontends (v) are explained in more detail in the next section.
Many people have commit rights to certain modules. This makes it somewhat difficult to keep track of changes within them if you don't want to keep on updating your repository continuously. Here are a few ways to track changes:
WebSVN lets you look at the CVS repository through your browser.
The kde-commits mailing list is a email feed of all CVS changes, which you can filter in your mailbox.
There's also a news gateway of the commits feed. It is nicely split up by modules. You can also access it through an html interface
CommitFilter lets you create an account and select all subdirs of kde repository you want to have commit messages of.
Table of Contents
Depending on what you want to do, there a a number of alternatives you can choose from. In order to develop KDE applications you need the KDE and Qt headers and libraries. Many distributions provide those in packaged form for you, usually with the -dev extension in the name of the package. So if you do not depend on features in KDE CVS HEAD you can use those packages to develop your application - it wil make your life a bit easier. Keep in mind that the next major KDE release may change APIs which will require you to fix your application.
If however you want to work on some KDE application included in the official KDE release, you'll need to get the CVS sources. Depending on the distribution you're working with there might be a chance that you'll find some precompiled parts to work with, as f.ex. Orth's snapshots for the Debian unstable distribution.
If this is not a valid choice for you, you'll need to compile from CVS. Keep in mind that compiling f.ex. the kdelibs module can take from a couple of hours to days depending on your hardware. Thinking before compiling can spare you a lot of time.
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. Developers try -- and you, if you use CVS are strongly encouraged -- to make sure that the code compiles (note that this is not the same as saying the code works) so that there is always something for other developers to work with. Have a look at the KDE CVS Commit Policy for some guidance.
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.
Make a directory called KDE in the home directory of your
user account. This directory is where your KDE development
will take place in. You should not be doing any of this as root! Make another
directory called KDE/CVS. This is where the KDE sources will be.
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:
arts and kdelibs. kdebase is recommended but not strictly necessary. You should
compile and install them in that order (see below for compiling). Others you might
want are: kdeutils, kdegraphics, kdesupport, etc. Now, make a directory called
KDE/kde-HEAD. This is where you'll store the
compiled code from the HEAD branch and optionally also the latest Qt 3.x!
You may need to tell configure where to find the proper libraries
when compiling. Something like:
export QT_AND_KDE_DIR=/home/joedeveloper/KDE/kde-HEAD export LD_LIBRARY_PATH=$QT_AND_DIR_KDE/lib
Alternatively you can tell configure directly where
to find libraries or headers. Calling:
configure --help
should list all available configuration possibilities.
Compiling Qt should only be necessary if your system has a too old Qt installation or if you can't find a precompiled Qt package for your distribution. KDE's Qt copy contains some fixes, speedups and enhancements which can be useful.
Let's get Qt 3.1. Take the KDE copy of the current Qt library from the KDE CVS with:
cvs 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 -thread make
Now, for the KDE code. cd to KDE/CVS/arts. Type
make -f Makefile.cvs ./configure --prefix=/home/joedeveloper/KDE/kde-HEAD --with-qt-include=/home/joedeveloper/KDE/kde-HEAD/qt-copy/include --with-qt-libraries=/home/joedeveloper/KDE/kde-HEAD/qt-copy/lib makeIf all goes well, then
make installIf not, try to fix things, then type
make installRepeat this process for the other modules.
I usually put that long configure command I mentioned above
into a file called conf and leave it in my CVS directory.
Then I can do a ../conf from any module and get a good
configure.
Sometimes compiling a module takes very long and you'll want to exclude
some subdirectories from compilation. Let's assume that you don't want to build the
kmail and korganizer applications, located under the kmail and
korganizer subdirectores respectively.
In that case you can run:
DO_NOT_COMPILE="kmail korganizer" ./configure
which will exclude the kmail and korganizer
subdirectories from the build process.
Alternatively you can put the subdirs you want to have compiled into a file called
inst-apps in the toplevel directory of a module.
If you are working on modules with strong interdepencies, as f.ex. the kdepim module depending on the latest kdelibs from CVS HEAD, you should make sure to check out all the modules at the same time. Otherwise you risk finding out while compiling that the module depends on recent features of another module. Then you update the other module only to find out that the previous module doesn't compile any more because an API that it depends on API changed ... When you check out all the modules you neeed at the same time your chance is higher that they'll be in a consistent state.
Table of Contents
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 3.x should be done in DocBook. Look at http://i18n.kde.org for more details on using the docbook tools.
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
process 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 page has the annotated list of the core KDE classes.)
It's called kdoc and it's 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 @p argument to mean ...
*
* @return A pointer to another class
* @see KOtherClass
**/
KOtherClass *method (int argument);
}
/**
(two asterisks, mind you!) will be taken by
kdoc as class documentation and formatted
appropriately. The @author and other tags are meaningful to
kdoc and used for formatting.
You can indicate parameters inline using
the @p tag. Please do not use <i> any
more.
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.
Table of Contents
'Packaging' means putting your (in this case source) code into some format that is
easy for others to configure and install, and
easy to transfer,
can be indexed so that it is easy to find.
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 = kexampleto
SUBDIRS = kmyapp
kmyapp here refers to the subdirectory of the same name.
SUBDIRS = kmyapp kmysupportclassAlso 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 directory 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
./configureThis should create:
Makefile
kmyapp/Makfile
config.h
config.h in your source code
with #include "../config.h" and have your code compile
differently on different systems based on the #defines. Eh?
Well, different systems have slightly differnent ideas about
implementing standards and such, and your code may 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
#defines.
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, no example for a shared-library Makefile.am is included. So, I've included one in the next section.
If you distribute a widget, you should also distribute a small program which tests and demonstrates use of 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.1or 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.andamooka.org/~dsweet/KDE/KLab Primary-site: ftp://ftp.kde.org/pub/kde/unstable/apps/scientific Alternate-site: http://www.andamooka.org/~dsweet/KDE/KLab/ Original-site: ftp://upload.kde.org/pub/kde/Incoming Platform: unix Copying-policy: GPL End
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 (that person is probably still maintaining).
If you are developing outside of CVS, you can submit your code
(widgets, applications, etc.) via FTP to ftp://upload.kde.org/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.
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 and patches (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.
I'd also like to thank everyone who wrote to me with words of encouragment and thanks.
Table of Contents
The current version of this document is available at http://developer.kde.org/documentation/tutorials/howto/
Changes by Tomas Pospisek:
Updated release date, release version and contact info
Removed makehowto in favour of an updated Makefile, now all formats we want are produced automatically again
The tar.gz now uncompresses into a directory instead of into the current dir
Cleaned up docbook original somewhat
Removed old developper-HOWTO formats and documents
Added WebCVS to the links section
More links at crossreferences
Moved info about cvs accounts from mailing lists section to own section
Added anoncvs method description
Added cvs frontends (Cervisia etc.)
Referenced the KDE CVS Commit Policy
Minimum requirements are arts and kdelibs only
Documented checking everything out at the same moment (C. Schumacher)
Documented excluding parts of a module from a compile (D. Faure, R. Kainhofer, I. Klcker)
Documented tracking changes (T.Koenig, V.Augustin)
Fixed broken layout
Updated developer-howto.tar.gz for download
Added configuration information for compiling.html
Updated documentation to reflect changes in KDE since the year 2000
Revised to newer KDE Documentation format
Generally made information current.
Added SGML, PDF, and HTML-.tgz-ball formats.