The K Desktop Environment

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:

    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

    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

    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:

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

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

    Next Previous Table of Contents