Next Previous Table of Contents

### 2. The KDE Developer's mini-HOWTO

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

### 2.1 Information and Source Code

#### General Information

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.

#### URLs

- 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.troll.no.
- KDE Source Code and binaries: ftp://ftp.kde.org (or mirrors)
- Qt Source Code and binaries: ftp://ftp.troll.no

#### Mailing lists

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.

### 2.2 KDE CVS

#### Introduction

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:

- KDE_1_1_2_RELEASE - code that was considered stable, released, and distributed as KDE 1.1.2
- HEAD - code which will become KDE 2.0. It is based on Qt 2.1, has a new kwm, kpanel, etc. LOTS of changes.

#### Using `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)

> `

### 2.3 Compiling and Safe Development Practices (with configure)

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.)

#### Organizing

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!

#### Compiling 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

> `

#### Compiling KDE (HEAD)

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

> `

#### Compiling tips

- I usually put that long configure command into a file called `conf` and leave it in my CVS-HEAD directory. Then I can do a `../conf` from any module and get a good configure.
- It seems that you need to compile and install qimageio (part of Qt) separately. Just `cd` to `/$QTDIR/extensions/imageio/src` and type `make install`

### 2.4 Documentation

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.)

#### KDOC: The KDE Class Documentation Tool for C++

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.

### 2.5 Packaging and Submitting Code to KDE

#### Packaging

'Packing' 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.

These three concepts are expanded upon in the next three subsections.

#### GNU Configure

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:

- Makefile
- kmyapp/Makfile
- config.h

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 Makfile.am for a Shared Library

> `

>     # 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

> `

#### LSM file

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.

#### Submitting

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.

### 2.6 Acknowledgements

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.

### 2.7 About this document

#### Finding

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.

#### Changes

#### Changes from version <July 1, 1999> to version <March, 11, 2000>:

- Added "About this document" section
- Added more acknowledgements
- Multiple formatting changes (thanks Ralf!)
- Fixed instructions for getting CVS access
- updated contents for current KDE 2 development state (March, 11, 2000)

Next Previous Table of Contents