From kde-devel Tue May 18 02:13:33 1999 From: David Sweet Date: Tue, 18 May 1999 02:13:33 +0000 To: kde-devel Subject: KDE-Developer's mini-HOWTO X-MARC-Message: https://marc.info/?l=kde-devel&m=92699359421237 Things have gotten a little more complicated for developers recently. I thought maybe a mini-HOWTO would help. I'm open to suggestions/contributions. Included are some CVS and compilation FAQs as well as some general information for new developers. Dave -------------------------------------------------------------------- The KDE Developer's mini-HOWTO By David Sweet I. Introduction 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 mini-HOWTO is geared toward new developers, occasional developers, and anyone else who can't seem to get the HEAD branch to work. 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 http://www.chaos.umd.edu/~dsweet/KDE/DevelMiniHOWTO.txt To contribute, comment, or correct, please email me (dsweet@chaos.umd.edu). II. 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 (www.kde.org) for more information. KDE uses the Qt toolkit which is developed by Troll Tech (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 programming language used for development is C++. 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.1. KDE 1.1.2 will introduce theme support (which allows users to dramatically change the appearance of their desktops) and include bugfixes. One should expect KDE 1.1.2 to be released in about 4-6 months. 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, maybe kwm, and much more. KDE 2.0 requires mico, a free CORBA implementation. CORBA is used to make the new kfm (dubbed Konquerer) easily extensible and to create a document-centric user interface for KOffice. The user can, for example, embed a chart created and edited with KSpread into a document which has text created and edited by KWord. KDE uses CORBA through the K Object Model (KOM), which is based on Openparts. There's more to this CORBA stuff, but I'm just learning. [Please feel free to correct me! :] See the URL list below for some good CORBA/KOM links. URLs The main KDE web site is at: http://www.kde.org See the "Developer information" section in the navigation side bar. Bug reports can be found at: 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 CORBA Info: http://www.omg.org/ A good CORBA paper: http://www.cs.wustl.edu/~schmidt/vinoski.ps.gz MICO: http://diamant-atm.vsb.cs.uni-frankfurt.de/~mico/ (read the documentation! It's good.) OpenParts/KOM: http://www.chaos.umd.edu/~dsweet/KDE/KTrans/KOM Mailing lists The list kde-devel is for KDE developers in general. The koffice mailing list is for developers interested in koffice. Send a message to either kde-devel-request or koffice-request with the messag "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. As a KDE developer you may want or need a kde email address, like joedeveloper@kde.org. To obtain one, send an email to Martin Konold at konold@kde.org. To gain access to the KDE CVS respository (discussed below), send an email with an encrypted password to Stephen Kulow . To get your encrpyted password, do the following: On your system, change your account password with passwd to the password you would like to use for the CVS. Copy and paste the encrypted password from the file /etc/passwd into the email that you send to coolo. The line in /etc/passwd should look something like: dsweet:NHjGa4Fw4psGKo:500:500::/home/dsweet:/bin/tcsh The part you want to copy and paste is the "NHjGa4Fw4psGKo". That's your encrypted password. Don't forget to change your password again with passwd. II. KDE CVS 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. [-- 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 inftp://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_1_RELEASE - code that was considered stable, released, and distributed as KDE 1.1.1 KDE_1_1_BRANCH - derived from KDE_1_1_1_RELEASE; being developed for KDE 1.1.2; will include themes and bugfixed; based on Qt 1.42. HEAD - code which will become KDE 2.0. It is based on Qt 2.0, requires mico, has a new kwm, kpanel, etc. LOTS of changes. The cvs utility is probably on your system. To learn to use it I would recommend reading the man page! Below is an explanation of some common functions. Let's assume below 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. Checking out a module, ex. kdelibs from HEAD cvs -z6 checkout -r HEAD kdelibs cvs -z6 checkout kdelibs 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. 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_BRANCH cvs -z6 checkout -r KDE_1_1_BRANCH 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 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) III. 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.) 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.0! Let's get Qt 2.0 (snapshots are available from ftp://ftp.troll.no/qt/snapshots. Get the latest one. Don't expect it to work without a little help, though.) Put the sources in KDE/kde-HEAD. To compile the code, cd to KDE/kde-HEAD and gzip -d qt-2.00beta-snapshot-1999xxxx.tar.gz tar -xvf qt-2.00beta-snapshot-1999xxxx.tar ln -s qt-2.00beta-snapshot-1999xxxx qt cd qt setenv QTDIR $PWD (if you use csh/tcsh, change this for bash) cd configs mv linux-g++-shared linux-g++-shared.orig sed s/-fno-rtti// linux-g++-shared.orig > linux-g++-shared make linux-g++-shared make You should compare the files configs/linux-g++-shared and configs/linux-g++-shared.orig if you don't know what the sed is doing. The look up the -fno-rtti option of egcs. 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 --with-qt-libs=/home/joedeveloper/KDE/kde-HEAD/qt/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 --with-qt-libs=/home/joedeveloper/KDE/kde-HEAD/qt/lib --enable-new-stuff --enable-tutorials when you compile the code in the kdelibs module. IV. The KDE SDK [-- (Information on making documentation will go here --]