]> July 1, 2003 2.1 David Sweet Andamooka

dsweet@andamooka.org

Caleb Tennis

caleb@aei-tech.com

Distributed under the Open Content License v1.0 as of version September 13, 2000 2000 David Sweet 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 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 processs (KProcess), (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 CVS tree on the web http://webcvs.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@kde.org. The KDE CVS (Concurrent Versions System) is the source code repository for the KDE project. You can access it via (i) World Wide Web: webcvs.kde.org, (ii) the cvs command line utility, (iii) the cvsup command line utility, (iv) by downloading CVS snapshots (.tar.bz2 files) via FTP, or (v) through a graphical cvs 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/cvsup.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-cvs 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 cvs command line utility (ii) and the graphical cvs frontends (v) are explained in more detail in the next section. To gain access to the KDE CVS respository (discussed below), you firstly 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 system administrators at sysadmin@kde.org along with an encrpyted password (see next paragraph). 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 cvs utility is probably on your system. If not, you should visit http://www.cvshome.org. To learn to use I would recommend reading the man page! But, I've included explanations of some common functions below. In some situations you may want to use a graphical cvs client to make your life easier. There are many cvs GUIs, like f.ex. Cervisia. Let's assume for this section that you've got a cvs account as described in the previous section. Your cvs 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 Inside the bash shell you'd do the following: export CVSROOT=":pserver:joedeveloper@cvs.kde.org:/home/kde" or setenv CVSROOT ":pserver:joedeveloper@cvs.kde.org:/home/kde" if you are using tcsh/csh. In case you do not have a cvs account or you do not want to access it that way, you can use the anonymous method. In that case you can set the environment variable CVSROOT to :pserver:anonymous@anoncvs.kde.org:/home/kde. You can't do this directly unfortunately. You can, however, view the contents of the file /home/kde/modules (which is similar, but not necessarily the same as a list of modules :) with cvs -z4 co -c The -z4 option tells the server to compress the code at "level 4" (higher levels mean more compression, but also more compression time) 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.) For example, check out kdelibs from the default branch. cvs -z4 checkout -r HEAD kdelibs cvs -z4 checkout kdelibs The -r options tells cvs which branch you want to checkout from. The default is the HEAD branch. For example, check out kdelibs, from KDE_3_1_BRANCH cvs -z4 checkout -r KDE_3_1_BRANCH kdelibs You could use co as an abbreviation for checkout. For example: Check out kjots, which is in the kdeutils module, from the HEAD branch. (1) cvs -z4 co -l kdeutils (2) cvs -z4 co -l admin (3) cvs -z4 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.) For example, update kdeutils/kjots. cvs -z4 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. For example, commit kdeutils/kjots. cvs -z4 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.) For example, add the file kdeutils/kmyapp/greatnewcode.cpp. (create the file first!) cd kdeutils/kmyapp cvs add greatnewcode.cpp cvs commit For example, delete the file kdeutils/kmyapp/badoldcode.cpp. cd kdeutils/kmyapp rm badoldcode.cpp cvs remove badoldcode.cpp cvs commit For example, add 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) You need to have files in a directory to commit it. For example, remove 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) cvs also provides the ability to store commonly used switches in a resource file. In your home you can create a file called .cvsrc. The KDE developers recommend the following settings in this file: cvs -z4 -q diff -u3 -p update -dP checkout -P Having these items store in this file keeps you from having to specify them on the command line every time you perform a command. 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: WebCVS lets you look at the CVS repository through your browser. The kde-cvs 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 cvs changes feed. It is nicely split up by modules. You can also access it through an html interface CVSfilter lets you create an account and select all subdirs of kde cvs you want to have cvs commit messages of. 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 Note that when checking out qt-copy, we did not need to specify -z4 on the command line, as our .cvsrc now has that specified for us. 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 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. 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. 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); } The text in the comments beginning with /** (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. '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. 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 kmyapp here refers to the subdirectory of the same 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 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 ./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 #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.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.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 You can copy and paste this text into a file called "kmyapp.lsm" and make the appropriate changes. Note that the file will automatically be placed in the directory indicated by Primary-site (I think). 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/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. 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. The current version of this document is available at http://developer.kde.org/documentation/tutorials/howto/index.html The DocBook source of this howto is here This howto organized with each chapters in a separate html file (online version) for local viewing (or mirroring) can be found here The same as one continuous HTML document is here And finaly in PDF format here 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. Klöcker) 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. 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)