# &kdevelop; User Manual

## About this Manual

This user manual is intended to describe the contents and use of the &kdevelop; &kdevrelease; Integrated Development Environment (IDE) from a user's point of view. It is no programming manual nor does it describe the development process in detail. It's only aim is to guide you in the handling of the IDE.

You will here find information on the following topics:

- In a nutshell—a quick reference of the most used commands and actions.

- Development on UNIX—a historical survey of UNIX program development, the main tools necessary and why you need an IDE.

- Installing &kdevelop;—tells you where to obtain &kdevelop; and how to get it up and running.

- Survey of the Features of &kdevelop;—is some kind of a warm-up, giving a short overall view of what is built-in into &kdevelop; and makes you acquainted with the look and feel of this IDE.

- Menus and Toolbars Survey—(in the appendix) provides you with a short overall view of the menu and toolbar selections available.

- Shortcut Keys—(in the appendix) lists the key sequences you may use to quickly access some specific &kdevelop; operation.

- Configuring &kdevelop;—shows how you can taylor the IDE to suit your needs.

- Getting started: the &appwizard;—describes the basics on how to set up a new project in &kdevelop; using the built-in &appwizard;.

- Advanced Project Management—shows how to load existing projects, convert projects from older &kdevelop; versions, and import other existing projects. Furthermore the configuration of a project's options to suit your needs is discussed.

- Editing tools—all you need to write your source files: using the editor, searching for text both locally and project-wide, up to integrating new files and classes into the project.

- The File Browsers—demonstrates various tools to look at the structure of your project and how to access the files you want to work with.

- The Class Browsers—describes one of the most powerful tools of &kdevelop; which lets you navigate through class dependencies and allows to easily create and access the classes and methods you need.

- Documentation—shows how to access the rich built-in documentation &kdevelop; provides and tells you how to create documentation of your project, concise and powerful API documentation providing you an overall view of all your project sources as well as docbook-based user documentation.

- Building and Project Management—deals with the creating and management of your project, describing the basics of autoconf and automake as well as how to set up custom make files and how to use compiler or make options to taylor your application to suit your needs.

- Advanced Project Management—looks at ways to keep multiple build configurations, to cross-compile for diverse platforms, or to make an embedded system using the Qt/embedded library.

- The Debugger Interface—describes how to use the integrated gdb debugger interface so you can hunt down bugs without leaving &kdevelop;.

- Using CVS—tells you how you can maintain your project using the CVS versioning system, a must especially if many developers work at the same project.

- Leveraging External Programs—shows how to access external programs and tools from within &kdevelop; thus greatly extending its capabilities.

- Plugin tools—provides you a survey of the parts which make up &kdevelop; and how you can taylor it to suit your needs by loading the necessary parts only, both IDE and project-wide.

## In a Nutshell

The information in this chapter is meant as a quick reference for a head start or if you (momentarily) forgot about some basic concept. If you want more information on a topic just follow the link in the title starting that advice.

## Look and Feel

- ## Full Screen Mode

  Select View Full-Screen Mode from the menus or press Ctrl Shift F .

- ## Hide/Unhide the Menubar

  To hide the menubar select Settings Show Menubar from the menus or press Ctrl M . To redisplay the menubar only Ctrl M is available.

## Projects

- ## Create New Project

  Project New Project... will start the &appwizard;.

- ## Use Project Options Early

  Whenever you start a new project do not forget to set the Project Project Options... to your needs.

## Compilation

- ## Missing detail in compilation messages

  If during compilations you miss some valuable information in the Messages Output View window, you may have selected a too low level of messages detail. Right click in the window and select another detail level from the menu which will pop up.

## &automanag;

- ## Create New Files in a Project

  Select the subproject in the upper half of the &automanag;, then right click in the lower half on the groups title you want to have the files added and select Create New File....

- ## Add Existing Files to a Project

  Select the subproject in the upper half of the &automanag;, then right click in the lower half on the groups title you want to have the files added and select Add Existing Files....

- ## Remove a File from a Project

  Select the subproject in the upper half of the &automanag;, then in the lower half open the groups list you want to have the file removed from, right click on the file in this list and select Remove.

## Compile/Make Problems

- ## Wrong `autoconf` version etc. Error

  There are several error messages concerning too old versions of autoconf etc. prohibiting `configure` to work properly. Run `autoreconf` in the directory tree where the `configure.in` files in question are. This command will try to update the information in the &GNU; Build System files. See `man autoreconf` for more information.

## Development on UNIX

### Some Historical Remarks

From the beginning, UNIX has maintained two very different development paradigms. One is the world of system and application programming languages, where some source code is translated to machine code by a translation program, usually a compiler or an interpreter. The programming language C is an example. UNIX was the first operating system kernel to be written in such a high level language instead of tightly machine-oriented assembler which was common before that time. (In fact, the C language once even was invented to write the UNIX kernel and associated programs on a DEC PDP-11 computer.)

The other paradigm is the world of scripting languages. This world evolved with the invention of the UNIX shell which was the user's interface to the operating system—and at the same time a very high level programming language. A shell script is built from a set of small utility programs like e.g. `grep`, `sed`, or `find`. Each such utility is designed for some tightly defined job. The trick is that any such utility can be connected to another one via a simple transport mechanism, called a pipe, which directs the output of the foregoing utility into the input of the next processed one. This makes up for a very powerful and highly flexible programming tool.

As time has gone by, both worlds have evolved. While C is still used mainly as a system programming language, C++ as a variant of C enriched by object-oriented and generic extensions has found its place for the development of complex applications in the 1990's. There are numerous other programming languages, even older ones keep their place—FORTRAN77 and Ada e.g. still have their stronghold in numerical applications.

### Contemporary Scripting Languages

In the scripting area, there has been a shift away from the shell, which suffers from portability concerns, to languages which unify all commonly needed functionality in their standard libraries, while still being able to interface to the outside through pipes when necessary.

All these scripting languages have in common that they are widely portable between UNIX variants, &Microsoft; &Windows;, &Mac; OS or even VMS. Also, they all have implementations that are freely distributable.

#### &perl;

&perl; has become popular as a text processing and system administration language. In the beginning of the World Wide Web, CGI scripts written in &perl; were a widely used method to create dynamic web pages from databases. Today, this method has been replaced mostly by the `mod_perl` plugin for the &apache; web server. Among &perl;'s strengths are its built-in support for advanced regular expression matching and its rich archive of freely distributed modules.

For more information see the Comprehensive Perl Archive Network (CPAN) website.

#### Python

&python; shines by the elegance of its class system and the ease and flexibility with which external libraries can be wrapped in a way that they appear like standard &python; classes and functions. In contrast to &perl;, &python; has a clear and concise embedding API, which makes it the language of choice for making C and C++ programs scriptable.

#### PHP

&php; was invented as a language directly embeddable into HTML pages and consequently has its main uses in delivering dynamic content in the web.

### Higher-level Scripting

Higher-level UNIX applications usually miss the speed and flexibility of the traditional character-oriented shell scripting mechanisms. This is especially true in the world of graphical user interfaces (GUI) as e.g. &kde;.

There have been attempts to provide similar mechanisms which will work on a higher application level, most notably CORBA and, in the &kde; environment, DCOP.

#### The CORBA Protocol

CORBA (Common Object Request Broker Architecture) is an attempt to let computer applications work together over networks. It was devised by the private, vendor independent OMG (Object Management Group) standards comittee.

CORBA-based programs use the IIOP standard protocol to communicate. Implementations based on IIOP are available on a wide variety of operating systems, programming languages, and networks and are thus highly portable.

The main drawback of CORBA is its rather low speed. While this may be tolerable in networks, it is a real hindrance for inter-application communications in a non-networked environment such as &kde; running on a single computer.

#### The DCOP Interface

Another evolution on UNIX-like scripting is the DCOP protocol which was devised for communication between &kde; applications to overcome the limitations of CORBA.

DCOP stands for Desktop Communication Protocol and is implemented as a simple IPC/RPC mechanism built to operate over sockets. In effect this provides facilities similar to the traditional UNIX pipe mechanism.

Traditional shell scripting is based on fairly small tool programs which were designed to work on a strictly textual basis. DCOP allows elaborate graphical programs to communicate with each other in a quite similar way. This enables e.g. a &kde; program to send messages to another &kde; program, or receive data from it for its own purposes.

There are drawbacks, however. To use DCOP a program must be designed to contain a special DCOP interface. And the DCOP communication process runs somewhat slowly (although a lot faster than CORBA). But it returns much of the power and flexibility of UNIX scripting to high-level programs which are based on a graphical user interface.

For more information, see the DCOP: Desktop COmmunications Protocol paper or The DCOP Desktop Communication Protocol library API reference of the &kde; dcop library.

### Build Systems

Except in very simple cases a programming project will consist of a lot of building blocks of source code each put into a separate file for easier maintenance. To make this running one has to effectively translate all this stuff into a few machine language units in a suiting format which allows the operating system to load and execute the program.

To accomplish this, the basic tools needed are

- a text editor to write the source code files,

- a translating program, usually a compiler to turn the source code into object files,

- a librarian which collects object files into libraries to reuse them easily without the need to recompile,

- a linker which binds several object files and libraries together into one executable,

- a make system which provides some means to manage all this stuff and—not to forget

- a debugger to (hopefully) find all errors in the program and possibly some other diagnosis tools to get everything running smoothly.

When you have a large project consisting of possibly hundreds of source code files, the process of compiling may become quite laborsome. You do not want to recompile all files each time you have changed only some of them. Instead, you only want to compile those files which are affected by the changes. In general, it is not always easily obvious which of the files have to be recompiled.

When you e.g. change a function prototype in a header file, you need to compile every file which includes this header file. If your project contains many such files you may easily miss one or two of them if you have to do the job manually. Thus some means of automization is necessary.

#### The Make Process

A tool which takes care of recompilations is `make`. It keeps track of all work using a set of rules which describe what to do in case some piece of information (usually a source or object code file) was changed. All rules belonging to a certain project are stored in a so-called `Makefile` which is processed by `make` any time you want to update your work.

Each rule consists of several building blocks, namely

- a target, i.e. the file to be built

- a set of dependencies, basically the names of those files the target depends on (e.g. the name of a source file, where then the target will be the name of the object file to be built) and

- the commands which are to be executed to make the target (i.e. to compile it or to link other object files together to build an executable progam file).

Basically the `make` command will read the rules one after another, check each file in the dependency list of a given target and make this target anew if any one of these files has changed, using the commands listed in that rule.

There are several additional possibilities to control such a make process, and a `Makefile` can thus grow very complex. We cannot go into the details here. However, we recommend that you make yourself accustomed to the syntax of `make`. Even if you do not normally use it directly, an understanding of the fundamentals of the build system can be useful. See the GNU Make Manual for more information.

For more &kdevelop; specific detail see the Building and Project Management chapter of this manual.

There are several tutorials available, see the references in the Building and project management chapter.

### GUI Development

Application developers become even more encumbered by having not only to create program libraries and logic, but also to provide an easy to use custom built user interface that is both intuitive and functional. Most programmers receive little to no training in GUI development, and as a result user interfaces often are poorly designed.

During the years some common design principles have evolved. It is strongly advised to adhere to them. This way your user interfaces will retain a common look and feel that the users of your application will gratefully appreciate.

For &kde; GUI development there is a style guide available. It is found in the &kde; User Interface Guidelines on the &kde; Developer's Corner page.

A short introduction to common GUI design principles can be found here.

### Integrating Concepts and Tools – the IDE

There are separate tools available for almost any step in the programming process—planning, editing, managing files and compilation processes, debugging, documentation and the like. But once the projects grow the programming processes will most likely become quite cumbersome.

Much repetitive work has to be done when designing, compiling, and debugging a program. A lot of such work can be saved through the use of templates and scripts. And another lot by keeping these tools easily available and able to communicate with each other under a common GUI.

For example—would it not be convenient if a debugger were able to open the source file in question in an editor and place the cursor directly at the position of that bug just found?

To more easily accomplish such a scheme, Integrated Development Environments (IDEs) were devised. Such an IDE integrates all templates, tools, and scripts which are commonly needed in the development process into one single environment.

For the &kde; platform &kdevelop; is such an IDE. It provides a wide range of tools which ease program development and maintenance, even for different programming languages and across platforms.

#### Basic Features of &kdevelop; &kdevrelease;

- Manages all development tools needed for C++ programming, such as compiler, linker, debugger and build system.

- Provides an &appwizard; which generates complete, ready-to-go sample applications.

- Allows the user to select an integrated editor based on the &kde; programmer's editor KWrite, Trolltec's QEditor, or others.

- A class generator, for creating new classes and integrating them into the current project.

- File management for sources, headers, documentation etc. to be included in the project.

- Assistance in creating application user manuals written with KDE tools.

- Automatic HTML-based API-documentation for a project's classes with cross-references to the used libraries.

- Internationalization support, allowing translators to add their target language to a project easily, including support of KBabel.

- Support for managing a project via one of several versioning systems (e.g. CVS) by providing an easy-to-use frontend for the most needed functions.

- An integrated debugger frontend.

- An integrated shell console emulator.

- Syntax highlighting in source texts.

- An auto-code completion facility for class variables, class methods, function arguments and more.

- Templates for creating various projects (KControl modules, Kicker (panel) applets, KIOSlaves, Konqueror plugins and desktop styles).

- Four navigation tree views for easily switching between source files, header files, classes and documentation, obviating the need for an external file manager.

- Cross-compiling support, with the ability to specify different compilers, compiler flags, target architecture, etc.

- Support for Qt/Embedded projects (such as the Zaurus and iPAQ).

- Inclusion of any other program you need for development by adding it to the Tools menu according to your individual needs.

## Installing &kdevelop;

In this chapter we will discuss the steps necessary to compile and install the &kdevelop; IDE:

- How to obtain &kdevelop; mainly concentrates on downloading the most recent &kdevelop; sources from CVS.

- &kdevelop; requirements lists the programs and libraries which you need installed to successfully compile the IDE.

- &kdevelop; compilation and installation leads you trough all steps of compilation and installing the application.

- How to obtain a &kdevelop; API documentation tells what an API is and how you get such a useful tool for navigating the &kdevelop; sources.

### How to Obtain &kdevelop;

&kdevelop; is available in binary form from many different &Linux; distributions such as SuSE, RedHat and others. These binaries are packed in some convenient format, mostly RPM, for easy installation. To install, follow the standard instructions given in your distribution.

You may as well obtain the &kdevelop; sources, compile and install them by yourself. These sources can be found via the project home page at http://www.kdevelop.org or via the &kde; ftp site.

#### Get Daily &kdevelop; Snapshots from &CVS;

If you want be in front of current development, anonymous &CVS; repository snapshots are available. The module name is kdevelop at `:pserver:anonymous@anoncvs.kde.org:/home/kde`.

##### Initial &CVS; Checkout

To obtain an initial version of &kdevelop; you must download it from anonymous &CVS;. For this so-called checkout operation follow these steps.

We assume you want to put your &kdevelop; copy into the `kde3src` subdirectory of your home directory (`~`).

- # Create the destination directory, if necessary:
- `~>` `mkdir kde3src`
- `~>` `cd kde3src`
- `~/kde3src>` `cvs -z3 -d :pserver:anonymous@anoncvs.kde.org:/home/kde co kdevelop`
- `~/kde3src>` `cd kdevelop`

Once you have successfully checked out your &kdevelop; version, you may keep up with the changes using the update procedure shown in the next section.

Keep the server load low. Please do not checkout every time you want to keep your &kdevelop; up to date! Use CVS update for this purpose.

Now you may compile your &kdevelop; version as shown in the &kdevelop; Compilation and Installation section.

##### Keeping Your &CVS; Copy Actual

After you checked out (and successfully compiled) &kdevelop; from CVS as shown above, you'll want to keep it up to date in order to get all the patches. Follow these steps. (We again assume you have put your &kdevelop; copy into the `kde3src` directory.)

Note the `up` (= update) command instead of the `co` (which stands for checkout).

- `~>` `cd kde3src`
- `~/kde3src>` `cvs -z3 -d :pserver:anonymous@anoncvs.kde.org:/home/kde up kdevelop`
- `~/kde3src>` `cd kdevelop`

Keep an eye on the messages &CVS; produces during the update sequence. The exact steps in the compilation sequence depend on this.

Now you can compile a new &kdevelop; version as shown in the Special &CVS; compilation considerations chapter.

### &kdevelop; Requirements

In order to successfully compile and use &kdevelop;, you need the following programs and libraries. They are available on most platforms as distribution packages and thereby can be installed easily.

### Required:

- gcc/g++ ≥ 2.95.3 (or compatible)

  Available from gcc.gnu.org

- &gnu; make (or compatible)

  Available from www.gnu.org/software/make

- &perl; 5.004

  Available from www.perl.com

- autoconf ≥ 2.52

  Available from www.gnu.org/software/autoconf

- automake ≥ 1.6

  Available from www.gnu.org/software/automake

- flex 2.5.4

  Available from www.gnu.org/software/flex

- Qt ≥ 3.0.3

  Available from www.trolltech.com/products/qt

- KDE ≥ 3.0.2

  Available from www.kde.org

### Optional:

- The ctags source navigation tool, from http://ctags.sourceforge.net, which enables you fast access to declarations and definitions by a few simple clicks on a name in the editor.

- dot, a graphics language compiler, from http:/www.graphviz.org. This tool is needed in conjunction with &doxygen; below if you want to have class relationships graphically displayed (which is highly recommended).

- The &doxygen; documentation tool, from http://www.doxygen.org if you want to generate concise and powerful API documentation from your projects.

- valgrind from http://developer.kde.org/~sewardj/ helps you to find memory management problems in your applications.

- CVS from http://www.cvshome.org if you want to use the &CVS; versioning system.

- Any other compiler and/or tool in case you want to develop for another language/platform than C++/&kde; or use some special facility.

1. You can to a certain extent circumvent the need for &autoconf; ≥ 2.52 and &automake; ≥ 1.6. Just remove the `admin` directory in your &kdevelop; installation directory and type

   - `(your-kdevelop-directory)>` `ln -s $KDEDIR/share/apps/kdelibs/admin admin`

   at the console. This causes &kdevelop; to use the standard settings in the &kde; `admin` directory instead.

2. Be careful not to mix &qt; versions. Always link &kdevelop; to the same &qt; version your &kde; library was compiled. Otherwise you will most likely experience very strange behaviours.

### &kdevelop; Compilation and Installation

Once all requirements are met, you are ready to compile and install &kdevelop;. This chapter will discuss the necessary steps to do so.

- Preliminary Steps tells you about setting up a proper environment.

- Compile &kdevelop; deals with obtaining the &kdevelop; sources from &cvs;, how to prepare them for the installation process, and finally shows the steps necessary to compile and install &kdevelop;.

- How to Compile on FreeBSD discusses special considerations about the Berkeley Database systems in order to compile and install &kdevelop;.

- Some Notes on configure Options tells you how to run &kdevelop; if it has been installed in another location than the &kde; directory.

#### Preliminary Steps

Before entering the compile sequence you must make sure all libraries and tools are available to the make system. To accomplish this some environment variables need to be properly set. The actual steps to be performed depend on the console shell you use.

To avoid typing in all the statements that set the necessary environment variables every time you want to compile, you should put them into your `.bashrc` or `.cshrc` file. This way the environment variables will be properly set every time you start the shell.

##### Setting the Environment for the bash Shell

If you use the bash shell add the following lines:

- `export KDEDIR=`(path to your KDE installation)
- `export QTDIR=`(path to your Qt library)
- `export LD_LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib:$LD_LIBRARY_PATH`
- `export LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib:$LIBRARY_PATH`
- `export PATH=$QTDIR/bin:$KDEDIR/bin:$PATH`

##### Setting the Environment for the tcsh Shell

If you use the tcsh shell add the following lines:

- `setenv KDEDIR` (path to your KDE installation)
- `setenv QTDIR` (path to your Qt library)
- `setenv LD_LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib:$LD_LIBRARY_PATH`
- `setenv LIBRARY_PATH $QTDIR/lib:$KDEDIR/lib:$LIBRARY_PATH`
- `setenv PATH $QTDIR/bin:$KDEDIR/bin:$PATH`

#### Compile &kdevelop;

In the following discussion we assume that you have put your &kdevelop; sources in the `~/kde3src/kdevelop` directory.

##### Special &CVS; Compilation Considerations

In case you use a &kdevelop; snapshot from &CVS; the initial compilation steps depend on whether you just did a complete checkout or only updated the source.

##### After a CVS Checkout

You must initialize the make system after a fresh checkout. The same is true every time you need to start over from scratch. Type:

- `~/kde3src/kdevelop>` `make -f admin/Makefile.common cvs-clean`

and then all of the following steps.

You might need access to the &CVS; repository for the clean-up if any corrupted or missing files must be reconstructed.

The `cvs-clean` command will remove every file not in &CVS; from the directory! Make sure to back up any valuable information before you issue this clean-up command.

##### After a CVS Update

The next step depends on the output of the &CVS; update sequence. If you got something like (there may be a U or a P marker in the leftmost column, both denoting the file has been changed):

    U /some_directory_path/Makefile.am

or if you just did a full checkout, you must enter:

- `~/kde3src/kdevelop>` `make -f Makefile.cvs`

before you proceed with all of the following steps.

##### Basic `make` Command Sequence

Once the basic make system is set up you must decide which type of the &kdevelop; system you want to use. This is done in the following configure step which builds the actual `Makefile`s the `make` command will use.

You may drop the `--prefix` option in the following `configure` command lines if you want &kdevelop; be installed in the default &kde; directory. See the Some notes on configure options chapter for this.

##### A Debug-Compiled Version

If you want to keep track of what your &kdevelop; application does at run-time you may build a debug-compiled version. Just command `configure` to do so:

- `~/kde3src/kdevelop>` `./configure --enable-debug=full --prefix=`(where-your-kde3-is)

##### A Release-Compiled Version

If you only want to use &kdevelop; as-is a (smaller and faster running) release version suffices. `configure` defaults to this.

- `~/kde3src/kdevelop>` `./configure --prefix=`(where-your-kde3-is)

If you want to build your own API documentation for &kdevelop; you must include yet another option in the `configure` command:

- `~/kde3src/kdevelop>` `./configure --`(options-as-above) `\`
- `--with-kdelibsdoxy-dir=$KDEDIR/share/doc/HTML/en/kdelibs-apidocs`

##### Make and Install &kdevelop;

`configure` will check the system and build some `Makefile`s according to what it found. The `make` command will use the main `Makefile` by default. Thus

- `~/kde3src/kdevelop>` `make`

suffices. If necessary, now gain root user rights using the command

- `~/kde3src/kdevelop>` `su`

and entering the root password. Then install the application:

- `~/kde3src/kdevelop>` `make install`

That's all. If you installed &kdevelop; in the default &kde; directory you may now run the IDE. Otherwise some additional steps will be necessary as shown in the Non-default installation directory section below.

#### How to Compile on FreeBSD

If you want compile and install &kdevelop; on a FreeBSD system follow the normal instructions but after

- `~/kde3src/kdevelop>` `make -f Makefile.cvs`

you must make the Berkeley specific include files and libraries available to the compiler. This is done through the `CXXFLAGS` environment variable:

- `~/kde3src/kdevelop>` `export CXXFLAGS="-L/usr/X11R6/lib -I/usr/local/include/db41 \`
- `-I/usr/local/include -L/usr/local/lib -I/usr/X11R6/include"`

You need the berkeley db 4.1 database version installed, if you have another version, you must adjust the path.

##### Check the Berkeley Database Version

To find out which berkeley database version you have installed, run:

- `~>` `pkg_info | grep db41`

This should return something like:

    db41-4.1.25_1       The Berkeley DB package, revision 4.1

##### More Changes

Change the line

`ac_cv_bdb=no`

to

`ac_cv_bdb=yes`

in the `configure` file because otherwise configure can't find the db libraries.

As `make -f Makefile.cvs` rebuilds the `configure` file you have to change this `ac_cv_bdb` entry every time after you issued this command.

As the FreeBSD guys renamed `libdb.so` to `libdbxx.so` you must replace

`libkdevcatalog_la_LIBADD = -ldb`

by

`libkdevcatalog_la_LIBADD = -ldb41`

in the `lib/catalog/Makefile.am` file.

Now continue with the usual `configure` and `make` steps as shown above.

#### Some Notes on `configure` Options

##### Non-default Installation Directory

By default `configure` prepares the IDE to be installed in the default &kde; directory. This is necessary because &kdevelop; assumes direct access to some tools and parts which reside there. If want to use your own installation directory, you must tell `configure` this by the `--prefix` option:

- `~/kde3src/kdevelop>` `./configure --prefix=`(where-your-kde3-is)

There is a caveat if you do so. You must provide a means for &kdevelop; to access the needed tools and parts in the &kde; directory when running. (You can still use the IDE without doing so, but with very restrained capabilities.)

Call up a shell and have the following commands executed before you start &kdevelop; at the shell prompt.

Take care to use the plural: It is `KDEDIRS`, not just `KDEDIR`)

- `~>` `export KDEDIRS=/usr/local/kde:/opt/kde3`
- `~>` `kbuildsycoca`
- (Now start &kdevelop;:)
- `~>` `kdevelop`

- The `KDEDIRS` environment variable must be set to the list of active &kde; directories in your system. We use
- `/usr/local/kde`:`/opt/kde3`
- as an example only.
- The `/usr/local/kde` directory may for instance contain an incomplete &kde; version you compiled for debug purposes, and the `/opt/kde3` directory may in addition contain the standard &kde; version from your distribution that is used for everyday work.

In a tcsh shell you must set the environment variables using:

- `~>` `setenv KDEDIRS /usr/local/kde:/opt/kde3`

The `kbuildsycoca` command (build system control cache) looks around for libraries and caches their location and version, so that &kdevelop; can find them. The caveat is that it takes noticeable time—and it has to be run any time you call up the shell to start &kdevelop; from a non-default directory. You may want to put the above commands into a shell script to reduce the typing effort.

(You could as well put the lines in your `.bashrc` or `.cshrc` file, but this is not advisable as `kbuildsycoca` will then be run any time you call up the shell.)

The `kbuildsycoca` command does not run from within the root. You must call it from a non-root user. (But is not a very good idea after all to do software development from within the root!)

### How to Obtain a &kdevelop; API Documentation

API is the short form of Application Program Interface. Actually such an API cotains a series of descriptions (i.e. calling conventions) by which an application program can access the operating system and other services. In our context, however, a broader definition was adopted. The API of a &kde; or &Qt; application is an abstract of the classes and methods interfaces, a synopsis to be used like a dictionary to navigate the sources.

There is a version of the most current API available at the KDevelop-Home website. It will be automatically updated every 24 hours so you can keep up.

Alas, this version is best used read-only over the internet. If you do not allways have net access you may as well build your own API documentation from the &kdevelop; sources. To do so, you must tell the automake system where to find the KDELIBS API in your system. This is accomplished by the special option `--with-kdelibsdoxy-dir` in the `configure` command when you prepare to compile the &kdevelop; sources:

- `~/kde3src/kdevelop>` `./configure --`(options-as-usual)`\`
- `--with-kdelibsdoxy-dir=$KDEDIR/share/doc/HTML/en/kdelibs-apidocs`

(`make` will replace the global `$KDEDIR` variable with the actual &kde; directory setting recorded therein.) Then issue a `make` command as usual. After the &kdevelop; IDE has been built you have the option to build the API as well. For this you must issue

- `~/kde3src/kdevelop>` `make apidocs`

This will build a `Doxyfile` in your &kdevelop; base directory which in turn will be processed by the Doxygen application to build quite a lot of `.html` API files. When this rather lengthy API building process (may last more than an hour on a slow system) finally comes to an end, you must install the API just like you have to install the &kdevelop; IDE itself. If necessary obtain superuser rights by

- `~/kde3src/kdevelop>` `su`

and entering the root password. Then install the API files:

- `~/kde3src/kdevelop>` `make install-apidox`

Once this is done, `make` will inform you about the directory where you can finally look at the API documentation's contents. Note this address, you can use it from the &konqueror; as well as from inside &kdevelop;, in case you have set up the &kdevelop; sources themselves as a project to work on.

You will most probably see a lot of warning and/or error messages during the API build run by Doxygen. Best ignore them, they are of interest to the &kdevelop; developers only. If the API generation ever comes to a successful end, the `.html` API files will be useable.

## Survey of &kdevelop; Features

&kdevelop; integrates a lot of tools, scripts, and templates in a common user interface. Basically it consists of

- several user interface modes from which you can select the look and feel of the workspace,

- an &appwizard; which aids you in setting up a new project,

- several project management systems which aid in building and managing your project,

- some editing tools to easily work on your program texts

- various file browsers providing you different views on your file system,

- various class browsers to aid you in maintaining the classes and their relationships of your object-oriented programming project,

- a debugger interface to find and remove program errors from within &kdevelop;, and

- several plugin tools, extensible modules which can be loaded at runtime and on demand. This allows you to only turn on those features you really need.

- a set of other diagnosis, documentation, and optimization helper tools.

### Available User Interface Modes

&kdevelop; offers developers four separate user interface modes (click on the mode name to view an example):

- IDEAl

  This is a novel user interface approach optimizing both work space and intuitive handling of the tools.

  - All tool views are docked in a tabbar fashion around the mainframe area. They are grouped left, bottom, and right according to the services provided.

  - Editor and browser views will be stacked in a big sized tabbed window inmidst the mainframe area.

- Child Frame Windows

  - All tool views are initially docked to the mainframe.

  - Editor and browser views will live like toplevel windows within a view area of the mainframe.

- Tabbed Pages

  - All tool views are initially docked to the mainframe.

  - Editor and browser views will be stacked in a tabbed window.

- Toplevel Windows

  - All editor, browser, and tool views will be toplevel windows directly on the desktop.

  - The main widget only contains the menu, toolbars, and statusbar.

#### How to Switch User Interface Modes

To switch the user interface mode select Settings Configure KDevelop... from the menus. The Customize KDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the settings page shown below.

Select a user interface mode

Select the radio button of the user interface mode you want to switch to, then press OK.

#### How to Maximize the Work Space Area

To maximize space, there is a full-screen window mode available which expands the mainframe area to the screen borders. Additional space can be reclaimed by hiding the menubar. And you can of course hide any toolbar as usual in KDE applications.

#### Full Screen Mode

To switch to or from full screen mode select View Full-Screen Mode from the menus or press Ctrl Shift F . There is also a Full-Screen Mode icon in the Browse Toolbar available.

#### Hide/Unhide the Menubar

To hide the menubar select Settings Show Menubar from the menus or press Ctrl M . You may also include a Show Menubar icon in a suiting toolbar, e.g. the Browse Toolbar for that purpose. To unhide the menubar you must press Ctrl M or use the Show Menubar icon if available.

### Elements of the User Interface

(... to be written ...)

#### The Workarea

(... to be written ...)

#### The &kdevelop; Titlebar

(... to be written ...)

#### The &kdevelop; Statusbar

(... to be written ...)

#### The menubar

(... to be written ...)

#### The Toolbars

(... to be written ...)

#### The Tree Tool Views

(... to be written ...)

#### The Output Tool Views

(... to be written ...)

### Project Management Systems

Globally, a project will rely on some form of project management system. &kdevelop; offers four project management systems the programmer can select from when creating a new project.

- Automake projects use the &gnu; standard development tools.

- QMake projects use the trolltech QMake project manager.

- ANT projects use the Apache ANT project manager for Java development.

- Custom projects require you to maintain your own `Makefiles`.

#### Automake Projects

Projects created with &kdevelop;'s &automanag; make it very easy for developers to use the &GNU; standard development tools. They provide

- a better way of `Makefile` generation and

- a good and safe way for fast adaption towards different systems by autoconf-generated `configure` scripts.

#### QMake Projects

For developers who enjoy the flexibility and feel of &qt;'s qmake system, &kdevelop; offers the ability to handle qmake based projects (.pro files) within the GUI.

For more information on the QMake project manager see the qmake User Guide which should be included in your distribution or have a look at the TROLLTECH Documentation home page where you may find the QMake documentation of your Qt C++ GUI Application Development Toolkit version.

#### ANT Projects (Java Projects)

Java developers may want to use the Apache ANT project manager for their projects. To set up a new Ant project in &kdevelop; select Project New Project... Java Ant Project Application.

For more information see The Apache Ant Project home page.

#### Custom Projects

If you prefer to maintain your own `Makefiles` for your project you may use the custom project option of &kdevelop;. This may be feasible in unusually structured projects or if you want to retain full control over the `make` process.

Yet, if you do not really need the extra flexibility and control of the custom project manager you should consider &automanag; or one of the other project managers, because they considerably ease the program building and distribution processes.

#### How to Distribute Your Application

The distribution of your applications does not require the end-user to have anything different installed other than

- an appropriate compiler,

- a linker, and

- the appropriate development libraries,

which at least for C++ applications is most often the case. But you can as well distribute binary packages of your application. In either way, the end-user of your product does not need &kdevelop; installed.

For giving away your sources, we advise to include the project file of &kdevelop; as well. This makes it very easy for other developers—if they use &kdevelop;—to work with your sources.

For projects where several developers, maybe working on different places, are involved, this should be the case anyway. So you can ensure consistency of the `Makefiles` to not run into trouble.

Especially on multi language applications, translators won't actually work with the source code, except in cases that require correction for enabling translation support.

## Configuring &kdevelop;

&kdevelop; is a very powerful and flexible IDE which offers many ways to taylor it to your needs. To start configuration select Settings Configure KDevelop.... This will cause the configuration dialog to pop up consisting of a selection window to the left and the configuration dialog on the right hand side whose contents will vary upon the configuration item you did select.

Select a configuration item

We will discuss these configurations in a different order, split up into the main topics of General Configuration, Configuring the Documentation Tree, and Advanced Configuration which makes for a more intuitive reading.

If you want directly look up a certain configuration item use one of the following links.

- General
- Plugins
- Source Formatter
- User Interface
- Editor
- Abbreviations
- Tools Menu
- External Tools
- Code Snippets
- File Selector
- Documentation Tree

### General Configuration

General configuration concerns the more common tasks of tayloring &kdevelop; as there are:

- General Setup

- Selecting the User Interface

- Source Edit Tasks

  - Selecting an Editor

  - Selecting a Source Format Style

  - Setting Up the Code Snippets Tool

- Configuring the File Selector

#### General Setup

The General configuration dialog allows you to define some basic &kdevelop; behaviour which seldom will change in everyday work. This concerns:

- General project options as

  - defining a default parent directory &kdevelop; shall use for new projects.

  - deciding whether you want &kdevelop; to automatically load the project you last worked on.

- Selecting a font for the most commonly used output view windows, namely

  - the Messages Output View &kdevelop; uses to communicate e.g. compilation progresses, and

  - the Application Output View which will show error and state information concerning a running application.

- Some common behaviour concerning the displayed lines in the Messages Output View window, namely

  - whether long lines will wrap around, and

  - if directory entry and exit messages issued by `Make` will be shown.

- The level of detail of messages concerning the compilation process shown in the Messages Output View window.

The general configuration dialog

#### Load last project on startup

Mark this checkbox if you want to continue to work with the last project you worked on. This will cause &kdevelop; to automatically load this project on startup. It will usually be shown in the state you left work so you can readily proceed.

#### Default projects directory

By default, &kdevelop; uses a common parent directory for all new projects. Enter the absolute path of this common directory in the box or select it from your directory structure. &kdevelop; will place the any new project here as a subdirectory.

You may of course change the directory path of a new project at the time you set it up in the &appwizard;.

#### Messages Output View window font

To select a font suitable for the Messages Output View window press the Window Font button showing the currently selected font (it says Luxi Sans in the above illustration). The &kde; standard Select Font dialog will pop up from which you may select the font to be used.

On first startup, &kdevelop; initializes this font setting to the standard font for which your &kde; user has been configured. This setting is fixed, so if you alter Preferences Appearances & Themes Fonts in the Control Center, this will not effect this &kdevelop; font selection. You will have to explicitely reselect the Messages Output View window font.

#### Line wrapping

By default, &kdevelop; will wrap long lines around in the Messages Output View window so that valuable information will not be easily overlooked. In some cases this will clutter long message lists. Remove the checkbox mark if you do not want the lines wrap around.

There is an alternative way to switch the line wrapping. Just right click in the Messages Output View window and mark/unmark the Line Wrapping entry in the menu which will pop up.

#### Directory navigation messages

The `Make` tool usually will display messages like Entering directory, or Leaving directory when it switches the directories it currently works in. As this clutters the messages list in the Messages Output View window, &kdevelop; suppresses those messages by default. Mark the checkbox if you want to protocol which directories `Make` worked in.

Changes in this setting effect the processing of new messages only. Old directory navigation messages will be kept visible when you switch this feature off.

#### Compiler output

&kdevelop; preprocesses the messages the Messages Output View window receives during the build processes in order to filter superfluous information. You can control the level of detail &kdevelop; will display using the radio buttons in this field.

Very Short

- Displays only warnings, errors, and the filenames which are compiled.

Short

- Suppresses all compiler flags and formats the output to be more readable.

Full

- Displays all output messages unmodified.

There is an alternative way to switch the compiler output detail. Just right click in the Messages Output View window and select the according detail level from the popup menu.

#### Application Output View window font

The Application Output View window is used to display error and state information from applications which are run from inside &kdevelop;. These are informations the applications usually sends to the console when run stand-alone. So you do not need to leave the IDE when testing the application you currently work on.

To select a font suitable for the Application Output View window press the Window Font button showing the currently selected font (it says Luxi Sans in the above illustration). The &kde; standard Select Font dialog will pop up from which you may select the font to be used.

On first startup, &kdevelop; initializes this font setting to the standard font for which your &kde; user has been configured. This setting is fixed, so if you alter Preferences Appearances & Themes Fonts in the Control Center, this will not effect this &kdevelop; font selection. You will have to explicitely reselect the Application Output View window font.

#### Selecting the User Interface

As already said in the Available User Interface Modes chapter there are four different ways the &kdevelop; work area may be set up, namely:

- IDEAl Mode

- Child Frame Windows Mode

- Tabbed Pages Mode

- Toplevel Windows Mode

To switch the user interface mode select Settings Configure KDevelop... from the menus. The Customize KDevelop dialog will pop up, where you have to select User Interface in the left hand tree. This will display the followig settings dialog to the right.

Select a user interface mode

Select the radio button of the user interface mode you want to switch to, then press OK.

#### Selecting an Editor

&kdevelop; allows you to select your favorite text editor tool. Mark the Editor entry in the left hand side selections tree of the Configure KDevelop window. The following dialog will be displayed to the right.

Select an editor

To select a new editor, click on the arrow on the drop down list field. Depending on the editor parts interfaces your &kde; version has compiled in you will be provided with a list of editors you may select from (see the Important note below for this). Click on the editor of your liking and press OK. Currently there are tree possibilities:

Embedded Advanced Text Editor

- This is the &kde; standard Kate editor part.

Embedded Vim Component

- This provides the look and feel of the base Linux vi editor.

  - You need to have a suitable Vim application installed. Have a look at the KVim website for more information.

  - Furthermore you need to configure the KParts Vim component in the &kde; Control Center (KDE Components Vim Component Configuration) before you can use it.

Qt Designer Based Text Editor

- This is the editor Qt provides in its Designer component.

These editor interfaces are fully integrated in the &kdevelop; IDE concept. Particularly the possibility to jump to the offending source code line by just clicking on an error message in the Messages Output View window has been provided.

Changing the editor will not effect already open files. There are two possibilities to proceed. Either close all open text windows and reopen them one by one. Or simply close the whole project and reopen it again. The windows will then automatically open under the new text editor interface.

KDevelop lets you use editor interfaces which have registered with &kde; and that provide a KatePart interface. If you miss one one of the selections shown above check your &kde; installation if the corresponding KPart was correctly installed.

#### Selecting a Source Format Style

&kdevelop; automatically formats a source text in a predefined style. This style is highly configurable. Select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select Source Formatter in the left hand tree. This will display a series of three settings dialog tabs to the right, namely a General Formatting Setup, a Indentation Style Setup, and a Other Formatting Setup.

Any style changes apply to newly entered text only. If you want to change the formatting style of an already existing source text you will have to explicitely use the Edit Reformat Source command.

The exact outcome of these style formatting definitions depends on the editor you use. Currently, most settings are taylored to the Kate editor part (the Embedded Advanced Text Editor). Some other editors (e.g. the Qt editor) may rely on their own configuration settings. You will have to experiment in this case to find out the exact effects of the style settings provided here.

Tere may be incompatibilities between the configuration style settings provided here and the editor you use up to the extent that in extreme cases it even might destroy your files. Make sure you have a backup of your source files before you try out these settings with an none KDE standard editor.

##### General Formatting Setup

The General tab of the Source Formatter dialog allows you to select one out of five predefined source format styles.

Source format style general setup

A formatted source example will be displayed in the field to the right. If none of the predefined styles is to your liking, you may press the top User defined radio button and define your own source formatting style preferences on the other two tabs which will become available then.

Currently only the predefined source formatting styles will be demonstrated by an example text. If you decide to define your own style, no example display will be available. You have to experiment on an actual source text to taylor the settings to your liking.

##### Indentation Style Setup

Proper indentation is the main means to enhance readability of a source text. I you selected the Indentation tab of the Source Formatter dialog you will be presented with a series of indentation formatting choices grouped into three boxes as following.

Source format indentation style setup

##### Default Settings

The preset format choices will cause the source text to resemble the ANSI formatting style:

    namespace foospace
    {
      int Foo()
      {
        if (isBar)
        {
          bar();
          return 1;
        }
        else
          return 0;
      }
    }

##### Defining Indentation Width and Characters

The radio buttons grouped in the Filling group define how indents in the source text will be drawn.

Use tabs

- This will cause the editor to insert a tab character for each indentation level. The tab width is predefined in the editor settings (8 or 4 character columns usually). Use Settings Configure Editor... to redefine it.

  The actual tab width definition procedure depends on the editor you selected in the Selecting an Editor configuration step. You will have to look up the corresponding editor help to find out.

Use spaces

- If you select this radio button, the editor will enter a number of spaces for each indentation level. Change the number from the default 2 to the indentation width you prefer.

##### Indented Entities

This defines which of the (C/C++) entities will be formatted with an extra indent beyond the current indentation level.

By default only namespaces and labels will be extra indented. You may want to experiment with various settings to taylor those extra indents to your liking.

##### Continuation

The settings grouped here apply to those cases where the source formatter automatically wraps around long source lines. It takes two special cases in account, namely that in deeply nested indents there should remain enough room for the source and that conditionals should get extra indent levels on continuation to make them stand out properly.

This applies to static word wrap cases only where a fixed maximum line width is used in the source text. If you set up your editor to dynamically wrap around long lines in display only (which is possible in the Kate editor part) the effects of these settings usually will not show.

Maximum in statement

- This setting limits the maximum possible indentation for the continuation lines so that enough space will remain to keep the text readable. No continuation line will ever be indented beyond the number of columns you selected in this field.

  The default is set to 40 character columns (half a standard 80 column page). You may want to increase this value to account for wider paper (e.g if you use landscape printing for your sources). Or decrease the value accordingly to take larger margin settings of your printouts into account.

Minimum in conditional

- Conditionals or source following e.g. an assignment operator should usually get an extra indent on continuation lines in order to keep the text readable. The amount of this extra indent is defined here.

  The default is set to Twice current which means that continued conditionals will get an extra indent level of the standard indentation size you selected in the Filling group. You may change this extra indent to another fixed width (including zero) using the arrows or by entering the value directly.

##### Other Formatting Setup

Other source format style settings

##### Controlling the position of braces

The radio buttons the (somewhat misnamed) Brackets group control the position of block delimiting braces in a (C/C++) source text. There are three possibilities from which you can select.

Break

- This inserts a line break before each opening brace. Both delimiting braces of any block will be put at the same indentation level as the block head statement.

      namespace foospace
      {
        int Foo()
        {
          if (isBar)
          {
            bar();
            return 1;
          }
          else
            return 0;
        }
      }

Attach

- This will keep the opening brace of a block in line with the block head statement. Closing braces will be on the same indentation level as the block head statement. The else of an if statement will be kept in line with the closing brace of the preceding block.

      namespace foospace {
        int Foo() {
          if (isBar) {
            bar();
            return 1;
          } else
            return 0;
        }
      }

Linux Style

- This is a compromise of the above listed styles. Functional block delimiting braces will be put on extra lines. Braces opening a block in a conditional or loop statement will be kept in line.

      namespace foospace
      {
        int Foo()
        {
          if (isBar) {
            bar();
            return 1;
          } else
            return 0;
        }
      }

##### Controlling extra spaces

By default &kdevelop; does minimize the use of spaces in source texts.

    if (isBar(fooArg)==barValue)

You may enhance readability if you force the source formatter to insert extra spaces in special positions.

Add spaces around parentheses

- In fact what is meant is to add spaces around the text put in parentheses. This enhances the readbilitiy of function arguments and conditionals.

      if ( isBar( fooArg )==barValue )

Add spaces around operators

- This will put spaces around assignment and comparison operators to enhance the readability.

      if (isBar(fooArg) == barValue)

##### Controlling the formatting of one-line constructs

There are a few cases where you don't want the source formatter to split a long line apart. For C/C++ code this can be controlled here.

Keep one-line statements

- This keeps single line statements together in some situations even if they exceed a fixed maximum line length.

Keep one-line blocks

- This keeps single line blocks together in some situations even if they exceed a fixed maximum line length.

#### Setting Up the Code Snippets Tool

When editing in &kdevelop; you can store often used parts of code as Code Snippets. To configure the capabilities of the code snippets part select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select Code Snippets in the left hand tree. This will show the following dialog in the right hand side.

Configuring the Code Snippets tool

#### Activate snippet preview

Mark the Show snippet's text in tooltip checkbox if you want to view the stored text in a tooltip window whenever you keep the mouse cursor over the title of that snippet.

#### Working with snippet variables

The Code Snippets tool allows for a variable text in predefined places any time you insert a snippet into a file. To accomplish this Code Snippets provides its own variables' mechanism. You can set up it's behaviour in the Variables group.

Delimiter

- The Code Snippets tool distinguishes variables in the text by surrounding the variable name with special delimiter symbols. To use your own delimiter symbol, change the predefined $ character in the Delimiter field.

Input method for variables

- - Single dialog for each variable within a snippet – will in turn pop up a separate dialog for each variable which the tool finds when inserting the selected code snippet.

  - One dialog for all variables within a snippet – will pop up a common dialog where the user has to fill in the values of all variables before the snippet will be inserted

#### Configuring the File Selector

&kdevelop; provides a File Selector plugin which, when loaded at startup, allows to navigate to any file or directory in the system.

The file selector (IDEAl mode)

The behaviour of the File Selector can be highly configured. Select Settings Configure KDevelop... from the menubar. The Customize KDevelop dialog will pop up, where you have to select File Selector in the left hand tree. This will show the following dialog in the right hand side.

Configuring the file selector

#### Configuring the toolbar

There is a toolbar on top of the File Selector which can be configured as usual in the Toolbar group.

#### Add an action to the toolbar

1. Select an item in the right hand Selected actions list after which the new action should be inserted.

2. Select the action to be inserted in the left hand Available actions list.

3. Click the right (upper) arrow between both lists.

   The action will be removed from the Available actions list and inserted into the Selected actions list below the selected item.

#### Remove an action from the toolbar

1. Select the item to be removed in the right hand Selected actions list.

2. Click the left (lower) arrow between both lists.

   The selected item will be removed from the Selected actions list and put back into the Available actions list.

#### Reorder the actions on the toolbar

1. Select the action to be moved in the right hand Selected actions list.

2. Click the up or down arrow to the right of this list.

   The selected item will be moved up or down the Selected actions list.

#### Defining when the contents should change

Updating the contents in the File Selector window takes time and resources, esp. when changing to another directory. Therefore File Selector is set up by default in such a way that its contents change only on demand, i.e. when you select another directory or when you explicitely want to refresh its contents.

You can however configure the File Selector to immediately reflect certain changes in your work. The settings in the Auto Synchronization group of the configuration dialog are responsible for this.

You can always update the contents of the File Selector by pressing the Reload button in the toolbar. This is not availble by default, however. You must insert it there first.

#### The file selector may update its content...

...When a document becomes active

- If you select this checkbox, the contents in the File Selector window will be updated whenever you go to another already open document, e.g. when you click on the tab of the according edit window in IDEAl mode. If necessary the File Selector will switch to the directory this file belongs to and update the display to show the actual contents in there.

...When a document is opened

- If you select this checkbox, the contents in the File Selector window will be updated whenever a document will be opened, e.g. by the File Open menu. If necessary the File Selector will switch to the directory this file belongs to and update the display to show the actual contents in there.

...When the file selector becomes visible

- If you select this checkbox, the contents in the File Selector window will be updated whenever it gets visible again. If necessary it will switch to the directory the actual document belongs to and update the display to show the actual contents in there.

You may freely combine these settings to taylor the actualization behaviour of the File Selector to your liking.

#### Controlling the history in the comboboxes

There are two comboboxes on top and bottom of the File Selector contents window which control the directory to be diplayed (top combobox) and the filters to be applied to the file display (bottom combobox). A history of the most recent settings is kept in the selection field of each combobox. You can configure the number of history entries as follows.

Remember locations

- Enter here the maximum number of directory selections the upper combobox shall remember.

Remember filters

- Enter here the maximum number of filter definitions the lower combobox shall remember.

#### Controlling what should be remembered between sessions

By default the File Selector is set up so that it shows the display of the most recent session again at the next &kdevelop; startup. You may change this behaviour in the Session configuration group.

If &kdevelop; was automatically restarted by the KDE session manager the changes in these settings will have no effect. In this case location and filter settings of the most recent KDE session will always be restored.

Restore location

- Remove the checkbox mark here if you don't want the displayed location be remembered between sessions.

  If you selected one of the automatic update settings the displayed location might automatically change regardless what has been remembered from the recent session.

Restore filters

- Remove the checkbox mark here if you don't want the filters applied to the display be remembered between sessions.

### Configuring the Documentation Tree

(... to be written ...)

### Advanced Configuration

(... to be written ...)

#### Plugin Tools

(... to be written ...)

#### Abbreviations for the Word Completion

(... to be written ...)

#### Adding &kde; Standard Applications to the Tools Menu

(... to be written ...)

#### Adding External Applications to Menus

(... to be written ...)

##### Adding to the Tools Menu

(... to be written ...)

##### Adding to the File Context Menu

(... to be written ...)

##### Adding to the Directory Context Menu

(... to be written ...)

## Getting Started—the &appwizard;

In &kdevelop; software development work is organized in projects. Such a project keeps everything together which belongs to a complete programming task: source files, additional data files, any actually needed management facilities as the make system as well as access to all components and any additional tools needed to get the application up and running.

Organizing all development work in projects allows you to easily switch between the global tasks at hand. This is quite handy if you e.g. work on several applications at the same time as is often the case. Tell &kdevelop; to open the project you want to work at and you may proceed in the environment just where you left.

### New Projects

Whenever you want to initiate a new programming project quite a lot of formal setup procedures need to be done. An initial directory structure has to be set up, initial header and source files must be provided, the make system has to be initialized, etc.

&kdevelop; provides an easy way to initiate a new programming project—the &appwizard;. You will find the &appwizard; at menu entry Project New Project.

Only a short series of steps is necessary to start a new programming project, using the &appwizard;:

1. Select the programming language you want to use and the type of the application you want to build from a set of predefined templates.

2. Supply some general information as application name, directory where the application shall be built, etc.

3. Decide whether you want to use a version control system, like e.g. CVS, and supply the necessary data if needed.

4. Set up some templates for initial header and source files (if applicable).

5. Finally tell &appwizard; to set up all initial stuff, directory structure, starting header/source file templates, and management tools, like e.g. an initial make skeleton, etc.

Voilà—that's all. &appwizard; will have provided you with a primary functional set of programming files, where you can readily start working.

Let's look at all this in more detail now ...

#### Initial Steps

To create a new project in &kdevelop;, select New Project from the Project menu. The Create New Project dialog will pop up showing an initial General page:

Initial dialog to set up a new project

As you see, this dialog is divided into an upper and a lower part. In the upper part you can decide on the programming language and application type, the lower part holds some general information.

##### Select Programming Language and Application Type

The left hand side of the upper part in this dialog is where you do the selection work. When it shows up, you'll find there a list of folders each labeled with a programming language, as there are:

- Ada

- C

- C++

- Database (SQL Projects)

- Fortran

- Haskell

- Java

- PHP

- Pascal

- Perl

- Python

- Ruby

- Shell (Scripts for the Bash Shell)

To be precise, these folders do not contain real programming tools actually. They do lead to pre-defined templates you can use as a starting point for development in that language. To get an idea of what is provided, just open the folders one after the other. There will be a series of subfolders on some, one or more simple entries only on others. The subfolders you see organize the available templates according to some tasks, the simple entries name the templates you may select.

We cannot go into detail here on which tasks each template provides, but it's easy to find out. Whenever you select a template entry some information is displayed in the fields to the right. In the lower field you will find a short description on what the template is supposed to do. In the field above that a picture will be shown, if available, about the outcome of the application this template produces if you compile and run it unmodified. Usually this is a screenshot of the main window the application will display.

Select the template which best fits your application's goals as a starting point. Then enter the general properties information in the lower field as shown in the next chapter.

##### Selecting a Project Management System

Each template is bound to a specific Project Management System. Currently there is no direct means to freely select such a Project Management System. You have to find a template which suits your needs or alter your project accordingly after creation.

##### Provide General Information

The lower part of the Create New Project dialog General page is a framed field labeled Properties. You must provide some general information about your project here so that the &appwizard; knows how to build the initial structure.

##### Application Name

Your application needs a name of course. Enter this in the uppermost Properties field, called Application Name. We use MyApp as an example.

When you do so, you will notice that the &appwizard; refuses to accept special characters of any kind. The only characters accepted are:

- upper and lower case characters

- numbers

- the underline character

One prominent cause of this restriction is that the &appwizard; will use this application name as the basis of some class names it will construct when it sets up an initial project. Thus the name of the application must stick to the rules of the programming language you use.

##### The Project Directory

The other prominent cause of this restriction you can see at the bottom line of the Properties area. It is labeled Final location and shows the directory where the &appwizard; will create the application.

As you type the application name you will notice that the &appwizard; repeats your input at the end of the Final location line, using lower case only characters.

Thus you must select the name of your new application with care. If you end up with an already used directory the &appwizard; will not allow you to continue to the next step, keeping the Next > button deactivated (grayed). Yet, it will warn you in this case by appending (dir/file already exist) to the Final location line.

##### The Starting Path

There are two ways to select another path for your new application. One is to select another name. Yet, this is not always feasible (you might e.g. set up for another version of an already existing application). As an alternative you may select another path to the application directory.

This is done in the second row input field of the Properties, named Location. What you enter here is the starting path of the new application development directory. The &appwizard; appends the application name to this path when it initializes the new project. The result is shown in the Final location line to give you better control on what is going on.

&appwizard; will copy an initial value to the Location field on start-up. This is taken from what you have chosen in the Default projects directory field during the general configuration steps. In our case we have &kdevelop; set up to use `/home/devel/projects/` as initial path for new projects.

Alter the Location field contents so that the application development directory shown in the Final location line will be unique.

Take care that the path you enter in the Location field already exists. Otherwise you will not be able to continue to the next step. The &appwizard; will warn you about non-existing paths by appending (invalid) to the Final location line.

##### Personal Information

The fields following this are not so critical. Just supply your name (i.e. the name of the person who is responsible for the application) in the Author field, and a valid e-mail address in the Email field, so that users can give you feedback on the application.

1. The &appwizard; fills these fields with some default values, taken from the Email presets in the KDE control center. If these defaults in the Create New Project Author and Email fields do not suit, you may want to have a look at your mail configuration in the KDE control center.

2. The &appwizard; will integrate this information into the starting program templates if applicable. In KDE C++ programs for instance you will find it near the beginning of the `main.cpp` source file.

3. Of all fields, the Email is optional, reflecting the fact that not every developer may have access to the internet. You may keep this field empty if you wish and proceed nevertheless.

##### Version and License Info

Finally enter a starting version number for your new application in the Version field, and select the license under which you want your application be put from the License tab.

If you select an application type for which the &appwizard; provides common source template texts (e.g. C/C++), you may view the license notification text on the third page of this Create New Project dialog (see the Supply header/source templates chapter below).

If you selected Custom from the License tab you must provide a license text on your own.

Both version and license information will as well be integrated into the starting templates in a suiting format the application type you selected does provide.

Once you have correctly entered all this information stuff, press the Next > button to proceed as shown in the following chapters.

#### Supply Version System Information

In a second step the &appwizard; will lead you to the Version Control System page where you can decide which version control system you want to use.

This discussion concentrates on the needs for project creation only. For more information on CVS see the Using CVS chapter below.

#### No Version Control System Wanted

Initially there is None selected in the Version control system tab, and the page will be empty otherwise. If you don't want to use a version control system, just click the Next > button and go on.

#### Using CVS

Otherwise you must reselect the version control system you want to use from the Version control system tab. We use &cvs; for our example. If you select this, the &appwizard; will redisplay the page, now showing a series of fields you must fill in.

Set new project up for CVS

A version control system such as &CVS; (which means Concurrent Versions System) stores copies of selected project files in some sort of a database. If you use &CVS; you can amongst others upload (commit) those files or load them back into your project directory (checkout, or update). The special thing about this is that the files in the versioning database are stored in a structured way which allows you to always revert to an earlier development state if you need so. And &CVS; allows multiple designers to fairly easily collaborate on a big project (such as &kdevelop;) without disturbing each others work.

#### CVS Root

&cvs; needs to manage the versioning database it keeps from your project files. To accomplish this it keeps some special database information in an own directory, called the &cvs; root. The first step on setting up &cvs; for your new project thus is to tell &kdevelop; where this root is located.

Local &cvs; root. There are two basic possibilities. Either you want to use a local CVS database or you use a database which is held on a remote server. If you develop for your own, you may want use the &cvs; database as some sort of a backup system on your own computer. Usually this is set up in your home directory root and given the name `cvsroot`. This may look as follows:

``/home/devel/cvsroot`` (where `devel` simply denotes the developing user, just for example)

In fact, this is a short form. Exactly, the local &cvs; root should be addressed using the `:local:` prefix. The short form is only allowed in cases where the filename starts with a slash (`/`). The full name for our example local &cvs; root would exactly look like: `:local:/home/devel/cvsroot`

Enter the name of the &cvs; root directory your system has been set up for in the CVS root field. In principle you can select any name, even use multiple &cvs; databases, but it is advisable that you stick to the &cvs; root once set up.

Initialize a new &cvs; root. If there does not exist a &cvs; root yet, &kdevelop; can command the &CVS; system to create one for you in the given directory. Just check the Init root checkbox below the CVS root field.

As said, &kdevelop; only commands the &CVS; system to initialize a new &cvs; root. It does nothing by itself to this directory. Fortunately &cvs; is clever enough to check whether the &cvs; root directory already exists. Hence it does no harm if you should have inadvertently checked Init root on an already existing &cvs; root directory.

Remote &cvs; root. There are occasions where the &cvs; database is to be kept on a remote server, especially when several developers work at the same project. Then you must enter the &cvs; root URL of this server in the CVS root field. For example, if you want access to the &kde; &cvs; server:

``:pserver:mylogin@cvs.kde.org:/home/kde`` (where `mylogin` denotes the login name set up in your &kde; &cvs; account)

#### Remote &cvs; Server Types

Basically there are two widely used remote &cvs; server types, the pserver which uses a password-secured non-encrypted protocol, and the ext server which uses an rsh or ssh encrypted data transfer. They are distinguished by the URL prefix they use:

`:pserver:`

for the password protected server non-encrypted type, and

`:ext:`

for an rsh or ssh encrypted server type. For example

``:ext:mylogin@cvs.cervisia.sourceforge.net:/cvsroot/cervisia``

accesses the &cvs; root of the widely used Cervisia &cvs; management tool on the SourceForge server.

If you want to use an rsh or ssh encrypted server for &cvs; access you must tell &kdevelop; the encryption protocol to be used. Just enter `rsh` or `ssh` in the CVS_RSH field of the Create New Project Version Control System page.

There is a caveat if you use an encrypted server for &cvs; from within &kdevelop;. See the Using CVS chapter for details.

#### The &cvs; Repository

So far you have told &kdevelop; where the &cvs; root resides which manages the versioning database and how to access it. Now you need to tell &kdevelop; under which name you want &CVS; save your project files in that database. Such a place your project files will be held in &cvs; is called a repository.

In principle you can use any name for the &cvs; repository of your project files as long as it adheres to the specifications of naming a file. Yet, most developers simply use the name of the application itself. &CVS; will build a directory with this name in the &cvs; root, hence it is more easily found if you keep the application name for it.

Just enter the repository name you want to use in the CVS repository field of the Create New Project Version Control System page. In our example this is: `MyApp`

Take care not to use a repository which already exists! The &CVS; system does not warn about duplicate files but will shovel everything in which does not produce a formal conflict. You will mess up everything!

#### The Remaining Fields

There is not much work left to do. &appwizard; has already set up the remaining fields for you. In detail:

The Vendor field is used for compatibility reasons only. You can stick to the vendor default the &appwizard; puts in here.

The Message field allows you to comment the initial &cvs; contents. Use any text you like or just stick to the new project default the &appwizard; did put in.

The Release tag holds the name which tags the initial state of your project. Such a tag names a certain point within the &CVS; repository by which you can later access this state of your development. (See more in the Using CVS chapter.)

The &appwizard; has put a default start tag in here which is a worthy proposal. Just stick to it.

When any information of all these is wrong &kdevelop; usually will not know about until project construction time. It is the &CVS; system which will figure out those errors when it tries to build the repository. Hence you must keep an eye to the Messages window of &kdevelop; when the project is created in the final setup step. If anything was in error with &CVS; you will in most cases see an error message like this:

    * cd '/home/devel/test' && cvs -d '/home/devel/mycvsroot' \
      import -m 'new project' '' 'vendor' 'start' &&\
      sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . '' \
      '/home/devel/mycvsroot'
    * cvs [import aborted]: /home/devel/mycvsroot/CVSROOT: No such file or
      directory
    * *** Exited with status: 1 ***

If this happens you will have to either manually set up &cvs; (&kdevelop; should have successfully initialized your project files at this time) or delete the project directory and start over again with New Project from the Project menu.

After you have entered all &CVS; related information, click the Next > to go on.

If you want to correct an error on the previous Create New Project page, just press the < Back button. The &appwizard; will remember your settings on the current page, so you can easily proceed when you come back.

#### Supply Header/Source Templates

The next step brings you to a series of pages where you can set up common information you want to include in your source and header files, if the task at hand allows.

Both header and source templates are provided for C and C++ applications, each on its own page. For other languages there may be source templates only. And in some cases you will even find this template page empty.

If the page is used, &appwizard; will fill in some common header comment which for a C++ based application might look like:

    /***************************************************************************
     *   Copyright (C) 2003 by Your Name                                       *
     *   you@you.com                                                           *
     *                                                                         *
     *   This program is free software; you can redistribute it and/or modify  *
     *   it under the terms of the GNU General Public License as published by  *
     *   the Free Software Foundation; either version 2 of the License, or     *
     *   (at your option) any later version.                                   *
     *                                                                         *
     *   This program is distributed in the hope that it will be useful,       *
     *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
     *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
     *   GNU General Public License for more details.                          *
     *                                                                         *
     *   You should have received a copy of the GNU General Public License     *
     *   along with this program; if not, write to the                         *
     *   Free Software Foundation, Inc.,                                       *
     *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
     ***************************************************************************/

Other templates will provide similar information in a format according to the definitions of the programming language you want to use.

As you might have noticed, the applications manager did readily fill in some information you provided on the first General page of the Create New Project dialog, namely the contents of the Author and Email fields. Also proper license information will have been inserted according to your selection in the License tab.

##### How to Edit the Templates

The templates you set up in the Create New Project dialog will later be processed whenever you command &kdevelop; to set up a new source and/or header file. The information you provided here will be included at top as a documentation header, before the code parts begin.

You are not restricted to plain text however. &kdevelop; knows of several variables which allow you to include actual information in the file. The &appwizard; did in fact use some such variables to insert the Author, Email, and License informations into the initial template text.

##### Include &doxygen; File Information

If, for example, you want the &doxygen;-built API documentation to display some further information about the file's contents in its filenames list, you may include the following lines in the source file template:

    /**
     * \file $MODULE$.cpp
     * \brief (put some short descripion here).
     **/

Whenever you create a new source file, &kdevelop; will replace the `$MODULE$` variable by the name body of the newly created file. For example, if you created a new C++ class named `ASimpleTest` you will see the following lines in the `asimpletest.cpp` file:

    /**
     * \file asimpletest.cpp
     * \brief (put some short descripion here).
     **/

You will still have to provide the short description after the \brief keyword, but part of the job is automatically done for you.

##### The License Text File

As another example you could include an explicit hint to the license text you want to use into the template. Use the `$LICENSEFILE$` variable for this and add for example this line:

    //   See $LICENSEFILE$ for the full license text.

The &appwizard; will replace the `$LICENSEFILE$` with the name of the file where the full license text is to be found, namely:

    //   See COPYING for the full license text.

for the GPL license, or

    //   See LICENSE.BSD for the full license text.

if you decided to put your application under the BSD license.

Thee are of course more variables &kdevelop; knows of. See the Editing the templates section in the Editing tools chapter for what is possible.

The templates you define here will come in effect only after the &appwizard; has created the new project. You will find this information on top of the files you created yourself in the development process. When creating the initial files the &appwizard; will use some predefined standard templates. You will have to manually adapt those initial files to your needs.

#### Build the Initial Project Files

Almost everything is done now. On the last templates page the Next > button will have changed to read Finish now.

Think twice before you click on it! You still have the option to revise everything by repeatedly using the < Back button. As the &appwizard; remembers all information you did input so far, it may be advisable for you to take the time and look back once again. In case you use local CVS, do not forget to double-check the CVS repository name (there should be no subdirectory with that name in the CVS root directory already—if it does, try another repository name).

If ever you don't want the new project be built, abort the Create New Project dialog by the Cancel button. Otherwise click Finish and watch in the Messages window how the &appwizard; initiates the project.

If you want to use a versioning system (&CVS;) there will be two runs actually. &appwizard; will first build the project directories and files and then call up the &CVS; program which restarts the Messages window with its own contents. If any error occurs in either of these runs, the process will stop showing you an according error message in the window.

In many cases when your new project has been set up this way, &kdevelop; will automatically load the source file(s) of one or more basically important modules so you can readily start work. (Which source modules will be displayed—if any at all—however depends on the template initially selected in the &appwizard;.)

Do not forget to initially check what the &appwizard; has provided. For example you may want to change the initial heading informations according to your own templates. Usually you will find these in a `templates` subdirectory in your project directory. Some simple copy operations will mostly suffice.

Then it is adviceable that you compile the initial project before you attempt to change any code. In most cases this initial compilation should be possible. Thus you can make up whether the project really was set up according to your needs. If it was not, simply remove the project directory (in your local &CVS; root as well if you use one) and start over again.

Before you compile your new project the first time, have a look at Project Build Configuration. If there are three selections displayed: default, optimized, and debug, with debug selected, by all means stick to this, or use optimized instead.

Due to some limitations in the current autoconf/automake setup you should by no means build in the default configuration. This will corrupt some internal directory settings, thus making `configure` complain when you try to use it in the optimized, or debug build configuration afterwards.

(This applies to these multiselection capabilities only. If the application type you selected provides a default build configuration only, you should of course use this one.)

### Behind the Scenes

It is always advisable to look at the messages output and try to understand what had happened. At least in principle you should know what was be done when the &appwizard; initiated your new project. We cannot go into the details but will have a survey of those messages to get an idea of what was going on behind the scenes.

If your project was set up for local &CVS; you will have got two series of messages of which the first set most probably was gone before you could thoroughly read, as &CVS; used the Messages window for its own purposes. So we caught both series in separate runs—set up the application twice, one time without &CVS;, then removed the directory and started over, this time setting the application up with &CVS;.

You may want to follow this same procedure if anything weird happened and you just could not catch the messages of the first setup step.

We will have look at the Messages outputs of both steps:

- Setting up the application as well as

- Setting up &CVS;.

#### Setting Up the Application

If you set up MyApp as in our previous example the &appwizard; should have printed the following messages (we re-arranged the output a bit for readability and you may click on a line to directly jump to its description):

    * perl /opt/kde3/share/apps/kdevappwizard/template-kapp/script \
      --author='Your Name' \
      --email='you@you.com' \
      --version='0.1' \
      --appname='MyApp' \
      --dest='/home/devel/projects/myapp' \
      --source='/opt/kde3/share/apps/kdevappwizard' \
      --license='GPL' \
      --licensefile='COPYING' \
      --filetemplates='h,/tmp/kde-devel/kdevelopcDE5Ja.tmp,\
                       cpp,/tmp/kde-devel/kdevelopsRrLab.tmp'
    * Making destination directory
    * Installing file templates
    * Installing license file
    * Installing admin directory
    * Installing GNU coding standard files
    * Installing Docbook template
    * Installing project file
    * Installing application framework
    * Installing application sources
    * Finished
    * *** Success ***

#### A &perl; Script Called

As you see from the first line, the &appwizard; did construct a &perl; program call from the settings you made in the Create New Project dialog. The called `script` resides in a directory which was determined from the application type template you selected in the upper part of the Create New Project dialog General page.

In our case this `script` is located in the `/opt/kde3/share/apps/kdevappwizard/template-kapp/` directory. Just replace `/opt/kde3/` by the &kde; directory on your system.

This &perl; `script` is called with a series of parameters, all marked by `--` prefixes, wherein the &appwizard; put information from the other selections you made in the Create New Project dialog.

The exact series of initialization steps depends on which &perl; `script` was called. If you want to check, just look into the `script` file the `perl` command on the first Messages window line did call.

The setup scripts make use of a set of &perl; subroutines collected in the `kdevelop.pm` file which you may find in the `share/apps/kdevwizard/template-common/` subdirectory of your &kde; installation.

#### The Application Base Directory

When the &perl; script is run, you get a series of messages of what is about to be done in the next installation step. At first a `destination directory` will be set up. This is the base directory of your application, just what you got displayed in the Final location line on the Create New Project dialog General page. The script uses the value of the `--dest` parameter in the &perl; command above.

#### The File Templates

In the next step the file templates you set up in the Create New Project dialog will be copied to the `templates` subdirectory of this destination directory. As you can see from the `--filetemplates` parameter, the templates are submitted in pairs—the suffixes they are used for first, followed by the name of a temporary file in which the &appwizard; has copied the contents of the templates dialog pages. These suffixes will be taken as the filenames of where to store the template texts.

In our example two such template files were installed, namely `templates/h` for C++ header and `templates/cpp` for C++ source files.

#### The License File

On the General page of the Create New Project dialog you selected the license you want to put your application under. The &appwizard; initiated two actions from this. One was the license indication it put into the templates. The other action causes the according license file to be copied in your application base directory.

The `--licensefile` parameter tells the &perl; `script` which license text file to copy. In our example the `/home/devel/projects/myapp/COPYING` file will have been installed in this step.

#### The Administration Directory

&kdevelop; needs a bunch of files to administrate the project. These are put in the `admin` subdirectory of your application base directory.

&appwizard; creates the `admin` subdirectory in this step and extracts the standard set of files it needs from the `share/apps/kdevappwizard/template-common/admin.tar.gz` tarball in your &kde; directory.

&kdevelop; always uses the same set of standard files for its administration purposes. Hence no parameter is needed in the &perl; `script` call to set up the `admin` subdirectory.

#### The &gnu; Coding Standard Files

There are several standard files to be distributed with every application which conforms to the &gnu; coding standard. The &perl; `script` extracts these files from the `share/apps/kdevappwizard/template-common/gnu.tar.gz` tarball of your &kde; installation directory and customizes them according to the information you provided in the Create New Page dialog.

After this step you will find the following files in your application base directory:

- `AUTHORS`, initially containing information from the `--author` and `--email` parameters.

- `COPYING`, this is the general &gnu; license, which all &gnu; conforming applications must contain—even if you decided to put your application under another license.

- `ChangeLog`, initially empty—you should protocol all major changes here.

- `INSTALL` contains generic installation instructions—modify this if special precautions and/or procedures are needed to install your application.

- `README`, initially empty—put any information here the user should know before installing your application.

- `TODO`, initially empty—put information here about what has to be done to further develop your application. You can use this as a notebook for your own purposes, but it is all the well really helpful once you have put your application in public domain.

#### The Initial Application Documentation

Every project you set up will contain an initial DocBook template from where you can start to write your application documentation. The &perl; `script` will in this step have set up `doc` and `doc/en` subdirectories of the application base directory with an initial `doc/en/index.docbook` template and some &automake; `Makefile.am` files from which &kdevelop; can later build help system files.

#### The Project File

Up to here most of the more global stuff has been set up, things which more or less are to be found in any &kdevelop; project. With this step the more application-specific setup processes start. These may vary upon the type of application you selected. Have a look at the actual &perl; `script` the &appwizard; called up for your new application if you want to lookup details. We will continue to follow the example steps listed above.

In the first step of these the &kdevelop; project management file is copied out of the template directory, where the &perl; `script` resides. In our case the `share/apps/kdevappwizard/template-kapp/app.kdevelop` file was copied into the application base directory and then customized according to the selections made in the Create New Project dialog.

You may want to have a look at the resulting project file which in our case was saved as `/home/devel/projects/myapp/myapp.kdevelop`. It is written in XML format and easily to be displayed with Kate or any other text editor. But take care nothing to change as &kdevelop; relies on its contents.

#### The Application Framework

Now it is about time that the directory structures and other maintenance files be set up to put the new application in and have it maintained. A so-called application framework will be set up in this step. Its structure basically dependends on the type of application you selected in the Create New Project dialog, but parts of it are common enough to be found in other projects, too.

In our case the following directory structure has been created in the `/home/devel/projects/myapp/` application base directory:

- The `src` subdirectory is meant to hold the source files of your application.

- The `debug` subdirectory will hold the compiled output of the debug build configuration. (See the Build configurations chapter to learn more about that.) As the name says, you should use this directory for debug purposes.

- The `optimized` subdirectory will hold the compiled output of the optimized build configuration. You should test an optimized version of your application from within here.

- The `po` subdirectory is meant for translation purposes. It will hold so-called Portable Object files (`.po` files) and templates (`.pot` files) which will be processed by a translation program as e.g. KBabel.

All these directories will not kept empty but filled with a series of `Makefile` and other files &kdevelop; uses to process the sources of the application. Also some initial icon files for the new application will have been put into the `src` subdirectory, if applicable. In our case you will find two of them: `src/hi16-app-myapp.png` and `src/hi32-app-myapp.png` which both hold standard &kde; application icons.

#### Application Sources Installed

This framework finally will be used to put the initial source files of your new project in the `src` directory. The actual files highly depend on the application type you selected in the Create New Project dialog. You will soon see yourself as this is the stuff you will actually have to work on.

#### Setting Up &CVS;

Now let us have a look at what the Messages window will contain when the &appwizard; continues to build our example project. If no error occurred during the first pass, the Messages contents will revert to create the local &cvs; repository.

As before we reformatted the output lines a bit for readability. And we removed some superfluous lines (where the . . . dots are).

    * cd '/home/devel/projects/myapp' \
      && cvs -d '/home/devel/cvsroot' \
             import -m 'new project' \
                    'MyApp' \
                    'vendor' \
                    'start' \
      && sh /opt/kde3/share/apps/kdevcvs/buildcvs.sh . \
                                                     'MyApp' \
                                                     '/home/devel/cvsroot'
      . . .
    * N MyApp/NEWS
    * N MyApp/TODO
    * N MyApp/README
      . . .
    * N MyApp/admin/configure.in.bot.end
    * N MyApp/templates/h
    * N MyApp/templates/cpp
    *
    * No conflicts created by this import
    *
    * *** Success ***

As you see from the first message line, the &appwizard; built another shell command line which conducts the &cvs; work to be done. At first the shell changes to the newly created application base directory to use it as default in the following steps.

#### Building the &cvs; Repository

In the second command line part the &CVS; application will be called to import the initial project contents into the wanted repository. Again, the work in detail is commanded by a series of command line arguments to the &CVS; application call.

- `-d '/home/devel/cvsroot'`—the `-d` option tells &CVS; which root directory is to be used. In our case this is the local &cvs; root located in `/home/devel/cvsroot`.

- `import`—tells the &CVS; application which operation to perform in this root. We want to import files into the &cvs; database. To accomplish this, the `import` command needs some arguments of its own:

  - `-m 'new project'`—the `-m` option provides import some message text for this action. It will be stored in the database and can later be recalled to identify the data which was kept in this step. In our case `new project` denotes the storage of our first files in the database.

  - `'MyApp'`—the second argument tells &CVS; which repository to use. If it does not exist, it will be created prior to the file import actions. In this case the `MyApp` repository will be created.

  - `'vendor'`—this following argument is a tag, a symbolic name which marks a series of files in the directory. There are several different meanings such a tag can have (see Using CVS for more information), this one in principle marks the whole bunch of files which subsequently will ever be stored in this repository. It is of no particular use to us, so `vendor` is as good a name as any other.

  - `'start'`—is another tag. It marks the release, in easy words a series of subsequently saved files which belong together. We used `start` here, a meaningful description of the use of this initial series.

#### The Imported Files

The &CVS; application will create the repository and then start to import all files from our `/home/devel/projects/myapp` directory. It subsequently reports any file which is loaded—this is the contents of the whole bunch of `N` lines following in the Messages window. The `N` denotes that this file was newly imported into the repository.

Depending on the type of the new application there will be quite a lot of those `N` lines. We truncated the output showing only the first and last three lines as an example.

#### The &CVS; Success Message

&CVS; always reports when an operation was successfully performed. In our case the `No conflicts created by this import` message was printed, followed by the general `*** Success ***` line as no other operation had to be performed.

There could have been some error messages about conflicting files if the repository already existed because &CVS; checks the file contents according to some formal criteria and will report any conflict it possibly finds.

#### Building the &cvs; Administration Entries

The &CVS; import operation is concluded at this point. The repository has been set up and all files we want to be kept were stored in the database. Yet there is more work to do, because the &CVS; application needs some administration information kept in every directory of the application. It uses this information later to communicate with the cvs root and repository.

If we were working with &CVS; alone we had to provide a means for &CVS; to store this information in our working directory. For instance we could check out the files again in an empty base directory in which case &CVS; automatically would write all administrative operation together with the checked out files.

In &kdevelop; fortunately there is an easier way. It provides the `buildcvs.sh` shell script in the `/opt/kde3/share/apps/kdevcvs/` directory (again replace `/opt/kde` with your &kde; installation directory), which the &appwizard; called after the &CVS; application had successfully finished its work.

The `buildcvs.sh` script mainly will put a `CVS` subdirectory into each directory of the application framework. Each of these `CVS` subdirectories will hold three file entries as follows:

- `Root` holds the name of the server on which the &cvs; root is located. In our case this is the local `/home/devel/cvsroot` root. The rationale behind this is to always use the same repository for these files, because &CVS; does not store them as a whole but will record only the differences of the subsequent parts. This will save lots of disk space yet makes it mandatory that all subsequent information be kept together under all circumstances.

- `Repository` serves the same purpose. &CVS; keeps the name of the repository to use herein, `MyApp` in our case.

- `Entries` holds the names and some other data about the files &CVS; will care of in this directory. This is because &CVS; does not necessarily keep every application file in the repository. You can tell it which files to store and which to ignore—this information is kept in the `Entries` file.

All these efforts are necessary because &CVS;'s work is directory-oriented. As &CVS; previously had stored all files in the `MyApp` framework, the `buildcvs.sh` script simply scans every directory and puts the names of all application files it finds into the according `CVS/Entries` file.

The script runs silently, just closing without any more line in the Messages window when the work was done.

## Advanced Project Management

### Loading Projects

#### Loading a Recently Used Project

(... to be written ...)

#### Loading an Existing Project

(... to be written ...)

#### Converting Old KDevelop Project Files

&kdevelop; allows you to open old KDevelop 2.x project files and convert them to &kdevelop; files. To do so go to Open Project... and select KDevelop 2 project files in the Filter:. Then select project file you want to open. The project gets converted to &kdevelop; and saved as a &kdevelop; project file.

#### Importing an Existing Project

To import an existing directory in &kdevelop; select Import Existing Directory from the Project menu. You should see the Import Directory Wizard, as seen below:

##### The Import Directory Dialog

### Tayloring the Project—Project Options

(... to be written ...)

## Editing Tools

### Code Snippets

### Features (preliminary survey)

- SnippetPart adds a tool-view which by default docs to the right

- Adding, editing and removing of snippets is available via a popup-menu

- Double-clicking a snippet form the list inserts it into to the active view at the current cursor position

- Tool tips show the content of a snippet

- Snippets are stored in the users home-directory, so every user can have his own snippets

- Snippets can contain variables in the style of $VARNAME$. On using the snippet the user is prompted to enter replacement value for the variables

### Keyboard Mapping

In the following, we will list the default keybindings of the default editor. You can configure them as you like (how?)

Left | Moves one character left
Right | Moves one character right
Ctrl Left | Moves one word left
Ctrl Right | Moves one word right
Up | Moves up one line
Down | Moves down one line
PgUp | Moves up one page
PgDn | Moves down one page
Ctrl PgUp | Moves to the beginning of the file
Ctrl PgDn | Moves to the end of the file
Home | Moves to the beginning of the line
End | Moves to the end of the line

For all the keys above, the Shift can be pressed additionally, to mark from the current cursor position to the one afterwards.

Backspace | Deletes one character left
Delete | Deletes the character under the cursor
Ctrl C | Copies the selected text to the clipboard
Ctrl V | Pastes the selected text from the clipboard
Ctrl X | Deletes the selected text and puts it into the clipboard
Ctrl Z | Undo
Shift Ctrl Z | Redo

### The Problem Reporter

(... to be written ...)

### Searching and Grepping

#### Searching for Text

Ctrl F- Find Ctrl R- Replace

#### ISearch

The conventional search with Edit Find requires you to specify the full search term before starting. Most of the time, it is much faster to search incrementally. If you click into the edit field labeled ISearch in the toolbar, the search is performed as you type. You will find that often the desired term is already found after typing in 3 or 4 letters.

#### Grep

Both search mechanisms described above are restricted to searching within one source file. An additional tool which allows you to search through a (possibly large) number of files is available through the Search in Files... item in the Edit menu. It is basically a frontend for the &grep;(1) program.

In the dialog, you can specify which files are searched. There is a number of wildcard patterns available in a combobox. In this way, you can easily restrict the find mechanism to header files. Furthermore, you specify a directory where the search is started. If you check the Recursive box, the search iterates through all directories in the hierarchy below this one.

The search term is in general a regular expression following POSIX syntax. For example, you can use the term `"\<K.*"` if you want to find all words which begin with the letter K. The following characters are interpreted in a special way:

`.` | Matches any character
`^` | Matches the beginning of a line
`$` | Matches the end of a line
`\<` | Matches the beginning of a word
`\>` | Matches the end of a word
`?` | The preceding item matches less than once
`*` | The preceding item is matched zero or more times
`+` | The preceding item is matched once or more times
`{n}` | The preceding item is matched exactly n times
`{n,}` | The preceding item is matched n or more times
`{,n}` | The preceding item matches less than n times
`{n,m}` | The preceding item matches at least `n` times but less than `m` times

Backreferences to bracketed subexpressions are also available by the notation `\n`.

For C++ programmers, as special bonus there are some search templates available for typical patterns. These allow you to search for example all calls of member functions of a certain object.

Once you start the search by clicking on the Search button, it will be performed by an external, asynchronous process. All found items will appear in the view called Grep. You can then jump to the found items by clicking on them. Note that grep scans the files as they stored in the file system. If you have modified versions of them in your editor, you may get some mismatches in the line number, or some found items will be invalid. You can avoid this by saving all files beforehand.

### Code Completion

(... to be written ...)

### Creating New Files and Classes

(... to be written ...)

#### Editing the Templates

(... to be written ...)

## The File Browsers

On the left side of the main window, &kdevelop; can display various kinds of lists and trees for the selection of files:

- ## File Tree

  This shows a tree view of the file hierarchy below the project directory. If you click on a file, it is loaded into the editor. For files which do not contain text, KDevelop starts an application that can handle the respective MIME type.

  The file tree is regularly updated whenever something changes in the file system. For example, if you create new files or directories (even outside &kdevelop;), this is immediately reflected in the file list. On Linux, this feature makes use of the FAM library. On other operating systems or over NFS, the directories shown are polled in small intervals.

  The file tree hides files which are usually not interesting, like object files. In the Project options under File views, you can configure (as a comma separated list of wildcards) which patterns are used to filter out irrelevant files.

  Furthermore, you can decide to restrict the file tree to show only files which belong to the currently loaded project. This can be toggled by clicking with the right mouse button on the root item of the tree.

  ### A Screenshot of the File Tree

- ## File Groups

  This shows the files belonging to the project, grouped by their file name extension. As in the file tree, you can edit a file by clicking on it with the left mouse button.

  The groups shown in this view can be configured under File views in the Project options dialog. In order to customize the view to your needs, it is helpful to understand how files are distributed on the groups. For each file, &kdevelop; goes through all groups from top to bottom. In each group, it looks whether the file name matches one of the patterns. If there is a match, the file is shown in this group and the iteration is aborted. This makes it clear that more general patterns should be put below more specific ones. For example, an asterisk for the Other group should be the last pattern.

## The Class Browsers

When working on a project in an object-oriented language, your emphasis when working on a project is not on the source files and their names, but on the classes and their relationships. In order to help you navigating in the space of defined classes and symbols, &kdevelop; includes various class browsers that visualize the class structure in different ways.

### Class View

This view is shown on the left side of the main window and contains a linear list of all classes, variables and functions in your project. It is designed as a tree view. If you open a class node by clicking on it, a list with all methods and attributes of the respective class is shown.

#### A Screenshot of the Class View

The class view works in two different modes. By default, all symbols are grouped into Classes, Structs, Functions, Variables and Namespaces. In the context menu of the view, you can choose List by Namespaces. In this mode, the namespace hierarchy is shown and the symbols grouped into the respective namespace where they are defined. This may be more useful in projects which make heavy use of (nested) namespaces. It is less useful in projects without namespaces.

You can also change the way in which class names are displayed. Normally, the names of the classes are shown, without the namespace in which they are defined. This means, you cannot immediately distinguish classes with the same name in different namespaces. If you rest for a while with the mouse over an item, the full scoped name is shown as a tooltip though. You can decide to always display the fully scoped class name by choosing Full Identifier scopes from the context menu.

Clicking on a class or method in the class view brings you to its definition. You can also jump to the declaration of a method by choosing Go to declaration from the context menu. In the context menu for classes are also the items Add method.. and Add attribute.... This opens dialogs where you can generate new method and variable declaration in the respective class, together with an empty implementation.

### Class Tools

The class tool dialog is activated by right clicking on a class in the class view and choosing Class tool....

### Class Hierarchy

(... to be written ...)

## Documentation

Documention unfortunately belongs to the most-overlooked programming issues. Yet, once properly set up and maintained internal and external documentation provides most valuable help.

Documentation has multiple facets. There is

- project internal documentation, mainly consisting of

  - comments in header/source files

  - internal API documentation of your project generated from the program file by special tools, e.g. &doxygen;

- project external documentation, comprising among others

  - external API documentation of e.g. common system libraries (KDE, Qt, etc.)

  - any other documentation (programming language manuals, general system information, HowTo articles and the like)

All this documentation should be easily maintainable and ready at hand whenever you need it. &kdevelop; has provisions for just this.

### The Documentation Browser

#### A Screenshot of the Documentation Tree

## Building and Project Management

This chapter deals only with compiled projects, such as C++, Java or Fortran projects. Projects for scripting languages like Python and PHP work very differently.

You will find here information on:

- Summary of &automanag; containing an initial overall view of &automanag;,

- Automake Manager Operation describing the basics of how to work with &automanag;,

### Summary of &automanag;

In the Build systems chapter we have given a rough survey of the build systems commonly in use on UNIX systems. In the following sections we will look at this in more detail.

There is some confusion about how to name such things. GNU calls them build systems when it describes Automake, Autoconf and Libtool. QMake calls itself a tool to write Makefiles for different compilers and platforms. In KDE often the term project management systems is used. We will use this term in a broader sense to describe the built-in environments in &kdevelop; which are used to organize and build your projects. In the context of this section, however, we will mostly talk about automated build systems.

#### The Need for an Automated Build System

If you have a simple Hello World program, written in C, you can compile and link it using `gcc` `-o hello hello.c` and execute it using the command `./hello`, so you do not even need a `Makefile`.

If you have a C application with several modules and header files and you are only going to run it on your own machine (i.e. it is an in-house application), you will only need a simple `Makefile`, which is fairly easy to write by hand (use `info Make` to find out more).

The complications begin when:

- Your source-code, documentation, graphics, sounds, translations, data files, etc. are located in more than one directory,

- You have a hierarchy of directories and sub-directories,

- You are using libraries that are not part of the traditional &UNIX; set, such as the &Qt; Object Library or the &kde; Desktop libraries,

- You are using a pre-processor to generate some of your source-code, such as Qt's MOC pre-compiler,

- You aim to distribute your application worldwide, to people who may not have the same &UNIX;/&Linux; system, software and hardware as you,

- You require an automated Install and Uninstall facility,

- You aim to make your application part of the &kde; Desktop set.

If you have some or all of the above situations, you probably need a build system. In the example above we used `gcc` to compile and build the Hello World program, but not all C compilers are called `gcc`. So if you distribute your application to someone who is using some other C compiler, your Makefile must somehow use the name of that person's compiler, otherwise your application will fail to compile—and that is just simple example of what can go wrong.

A build system will iron out these differences for you.

- It will check that the libraries you need are present on each receiving machine,

- will automatically scan all your application directories for files to pre-process, compile or install and

- will install the components of your application in the correct receiving directories, making sure that

- the directories are created in the receiving machine as required.

In brief, a build system offers safe and secure methods for your application to be compiled and installed correctly on any receiving machine. As we have shown before in the Project Management Systems survey, &kdevelop; offers three automated build systems and the option of creating your own Makefile, in short (click on the project names to get more information):

- Automake projects which use the &gnu; standard development tools.

- QMake projects which use the trolltech QMake project manager.

- ANT projects which use the Apache ANT project manager for Java development.

- Custom projects which require you to maintain your own `Makefiles`.

One of these four alternatives must be chosen when you create a project and the choice is difficult to change later, so you should give it some thought before you start.

#### Tutorials on Autoconf/Automake/Libtool

There are several tutorials available on the &GNU; Build System (`Autoconf`, `Automake` and `Libtool`) of which the &automanag; makes use.

- A short autoconf tutorial written by Christopher W. Curtis available on the KDevelop home page. It concentrates on some basic steps to modify a `Makefile`.

- A more detailed tutorial can be found in a greater set of tutorials on Developing software with GNU.

- And there is the famous Goat Book, titled Autoconf, Automake, and Libtool. This is an easily readable, yet concise, introduction in all main aspects of the &GNU; Autotools.

#### What does &automanag; Do?

The &appwizard; will have set up some initial `Makefile.am` files when you created a New Project of a type that uses the &GNU; Build System, such as C++ KDE Application framework. During development &automanag; creates any other `Makefile.am` files for projects that use the &GNU; Build System and maintains them all, &appwizard; and &automanag; created alike.

There will be one `Makefile.am` file in each directory of your project that contains files to be compiled or installed. It will contain your specifications for compiling, building and installing files and a reference to any subdirectories that also have a `Makefile.am` file and possibly some files to compile, build and install.

Your project's directories and source files may be structured to any depth, or you may prefer a flat project-structure with all subdirectories at the top level.

The aim of the &GNU; Build System is to produce source-code file structures that can be compiled, built and installed on any &UNIX; or &Linux; system by using the simple commands:

    ./configure
    make
    make install    # Usually as "root".

and can be uninstalled by the command `make uninstall` (usually as root).

How does this work? Well `configure` is a script that

- works out the details of whatever system it is in, such as what compiler and libraries to use and where they are located, and then

- creates recursive `Makefile` files by filling in the substitutions in the corresponding `Makefile.in` files.

The `Makefile.in` are input files—templates which provide basic information for the `Makefile`s to be produced from them by filling in some system dependent information. They are generated by the `Automake` utility from the `Makefile.am` files.

The process of going from `Makefile.am` (`.am` denotes Automake template files) to `Makefile` files is handled automatically by the KDevelop &promanag;, using the `Autoconf` utility, `M4` macros and other arcana we need not go into here.

So when `make` runs, it automatically picks up the correct pieces from the current environment, such as compilers and libraries. Similarly, `make install` puts your application components, such as executables, documentation and data files in the correct places for that environment.

If you distribute your application as a tarball (a single compressed file that KDevelop can create for you), it will include the `Makefile.in` files and the `configure` script file, so the recipient can compile, build and install your application without having `Automake`, `Autoconf` or KDevelop on their machine. The `Makefile.am` files are also included, just in case the receiver needs to do any source-code modifications.

The rules are rather different if you distribute via a web-based source-code repository such as KDE CVS.

#### Summary of What Automake Manager Does

- Generates `Makefile.am` files in subdirectories it knows as subprojects.

- Updates `Makefile.am` files as the project structure changes.

- Updates `Makefile.am` files as files are added to or removed from the project.

- Accepts definitions of how the various files are to be built or installed and modifies the `Makefile.am` accordingly.

- Accepts parameters used in building or installing (e.g. library names) and ensures that they are used in the required compilation and build steps.

#### Contents of Automake Files

A `Makefile.am` file has lines containing variable-names followed by an equals sign and a list of files or parameter values. The variables have two-part names, such as `bin_PROGRAMS`, `myapp_SOURCES` or `kdelnk_DATA`. The second part is called the primary and represents something from which to build or install. The first part is called the prefix and represents:

- A directory in which to do installation (e.g. `bin`),

- A qualifier for the primary (e.g. `myapp` for `SOURCES`, indicating that the source files listed after `myapp_SOURCES` go into building `myapp`),

- A special prefix `noinst` (short for no installation), usually used to list program header files (`.h`),

- Or the special prefix `EXTRA`, for configuration-dependent stuff.

For more information on `Automake` and `Makefile.am` files, look up `info Automake`.

Basically, &automanag; creates and updates the variable-names and lists of files or parameters. See the following example of a `Makefile.am` for a typical application, called `myapp`.

    ## Makefile.am for myapp

    # this is the program that gets installed.  it's name is used for all
    # of the other Makefile.am variables
    bin_PROGRAMS = myapp

    # set the include path for X, qt and KDE
    INCLUDES = $(all_includes)

    # the library search path.
    myapp_LDFLAGS = $(KDE_RPATH) $(all_libraries)

    # the libraries to link against.
    myapp_LDADD   = $(LIB_KFILE) $(LIB_KDEPRINT)

    # which sources should be compiled for myapp
    myapp_SOURCES = main.cpp myapp.cpp myappview.cpp

    # these are the headers for your project
    noinst_HEADERS = myapp.h myappview.h

    # let automoc handle all of the meta source files (moc)
    METASOURCES = AUTO

    KDE_ICON = myapp

    # this is where the kdelnk file will go
    kdelnkdir = $(kde_appsdir)/Utilities
    kdelnk_DATA = myapp.desktop

    # this is where the XML-GUI resource file goes
    rcdir = $(kde_datadir)/myapp
    rc_DATA = myappui.rc

    AM_CXXFLAGS = -DMY_C++_PREPROCESSOR_OPTION

As you can see, many of the items on the right hand side are symbols of the form `$(xxx)`. These are environment variables which are defined in the actual &kde; environment and are substituted with real values when `./configure` generates the final `Makefile` files in the receiving machine.

Also, sometime after you have started with KDevelop, it is a good idea to run the command `./configure --help`, which will show you the range of things you can change at build and installation time, such as for a test environment. In particular, the command:

    ./configure --prefix=/where/you/wish

will re-direct the entire installation to a directory structure of your choice, by changing the internal variable `$(prefix)` to value `/where/you/wish`.

### Automake Manager Operation

In this chapter you will find a basic description of the &automanag; elements and how to use them. This covers:

- The &automanag; Window describes the basic structure of the &automanag; main window.

- The Overall View Window describes the elements of the upper subwindow.

- The Detail View Window describes the elements of the lower subwindow.

- Navigating in the &automanag; lists some basic operations you can perform in the &automanag;.

- Popup Menus in the &automanag; describes the windows which will pop up when you select an action in the &automanag;.

#### The &automanag; Window

| &automanag; runs in a split window. The top part is called the Overall View and the bottom part is called the Detail View. Between them is a narrow bar that can be dragged with the mouse to adjust the sizes of the views. In IDEAl mode you can also drag the side of the split window to change the width. On top of each view there is a toolbar, the buttons in which will become activated when an element in this view is selected. This provides one way you can access the actions provided for that view element. The other are context menus which pop up on right mouse button click as will be discussed below. In IDEAl mode there are two additional small buttons in the &automanag; window titlebar left hand side – a triangular shaped right arrow, and a dot button. The arrow button is used to close the window. The dot button on the other hand will keep the window open even if another &kdevelop; window has been selected. (Otherwise the &automanag; window will automatically close whenever another window gets the input focus.)

#### The Overall View Window

The overall view window contains a tree-list of all the directories in your project that contain program files, documentation or data. Each such directory contains a `Makefile.am` file and is known in &automanag; as a subproject. There are three typical subprojects in a &kde;-based project as shown in the above illustration:

- `src` – source-code files for your application,

- `doc` – your user manual or Handbook,

- `po` – extracts of strings in your source-code files that require translation into other human languages (e.g. window titles, menu names, button labels, dialog box text and messages of various kinds).

Note that the `doc` subproject always has an `en` subproject, which you can see if you click on the + symbol next to the word `doc`. That is because the base language of all documentation in KDE is English (en). If your application becomes part of KDE, the KDE translation teams may translate your documentation from English into other languages and the translations will go into other subprojects, such as `de` (German) or `fr` (French). The strings in the `po` subproject may also be translated and stored in other files in `po`, thus allowing your application to be operated by people who do not know English.

The `doc` and `po` subprojects serve different purposes. `doc` contains documentation like a user manual, `po` contains translatable text strings of the user interface which is integrated in the source code of this application.

The overall view window serves—amongst other things—as a navigation tool. If you select a subproject in the overall view window, the corresponding details will be shown in the detail view window.

#### The Detail View Window

The detail view contains a tree-list of all the files in the subproject currently selected in the overall view as well as the compilation, build and installation rules for this subproject. Thus the two views together can give you access to all the components of your application and all the information on how to compile, build and install it.

#### Targets

The tree-list in the detail view has two levels. The top level consists of so-called &automanag; targets and the next level contains lists of files that go to make up each target.

This concept of an &automanag; target differs somewhat from what a `Makefile` target usually is. In short:

- The definition of how a set of files is to be compiled, built or installed is known as a target in &automanag;, but as a variable in `Automake` itself.

- A target in `make` is often something quite different, being the parameter of a `make` command (e.g. `make install`, `make clean`).

  However some `Makefile.am` variables do represent an underlying sub-target in `make`.

#### Navigating in the &automanag;

In both the overall and the detail view you can left-click on the + or - next to a subproject or target name to expand or contract the tree view. If you do that with a subproject in the overall view, it shows or hides the subprojects at the next level down (if any). If you do it with a target in the detail view, it shows or hides the list of files that go into that target.

#### Opening a File for Edit

If you left-click on a file name in the detail view, the corresponding file opens up in KDevelop's editing window.

#### Activating the &automanag; Toolbar Buttons

If you left-click on the name of a subproject in the overall view or target in the detail view, the name is highlighted and some toolbar buttons become active in the top part of that view.

It is recommended that you use the right mouse-button and popup menus, rather than the toolbar buttons, because it is then much easier to see and understand what you are doing.

Operations on subprojects and targets have far-reaching effects on the structure, compilation, building and installation of your application.

#### Selecting Actions/Popup Menus

If you right-click on the name of a subproject, target or file, a menu pops up and you can then select actions to perform on the subproject, target or file, such as add a target to the subproject, add a file to a target or logically remove the selected file from its target.

#### Popup Menus in the &automanag;

The following sections explain in short terms which operations the menus make available which will pop up on right mouse button clicks in the &automanag; window. They are meant for overall view only. You will find detailed descriptions of most operations in a later chapter.

##### The Popup Menu for a File

When you right-click on a file name in the detail view the following menu will pop up allowing you to select one of several operations to be performed on that file. In the illustration below the `hi-16app-myapp.png` icon file was selected from the Icon data in myapp target of the myapp/src subproject.

| The main popup-menu item for a file is to Remove the file from its target (i.e. it will no longer be used to compile, build or install that target). The CVS item offers a variety of CVS operations on the file. The Open With item allows you to open the file with a variety of editors or with any application at all (e.g. you can open the icon file in our example with KIcon). The Perforce item is used for similar operations as in CVS using the commercial Perforce version control system.

##### The Popup Menu for a Target

When you right-click on a target in the detail view the following menu will pop up allowing you to select one of several operations to be performed on it. In the illustration below the myapp (Program in bin) target of the myapp/src subproject was selected.

| The Options item for a target only applies to source code files. In the corresponding dialog box you can specify linker flags and paths on which to locate libraries and you can give a list of actual libraries to be linked in to your application. The Create New File item brings up a dialog in which you can set the file name and the type of file to be generated (from a drop-down list). The Add Existing Files item brings up a dialog box in which you can add an already existing file to this target. The Remove item for a target allows you to logically remove the target and all its files from the project structure. The Make Target Active item only applies to targets containing source code files. New files will always be added to such an active target. The Build Target item calls all necessary compile and make operations to build the code for this target only.

##### The Popup Menu for a Subproject

When you right-click on a subproject in the overall view window the following menu will pop up which allows you to make major changes to the structure of your project and the way it is compiled, built and installed. You can use it to expand or modify the basic project structure that the &appwizard; has created.

| The Options item for a subproject controls the way that the subproject will be compiled, built and installed. The dialog box that pops up has tabs for Compiler, Includes, Prefixes and Build Order. The Add Subproject item creates a new directory and skeleton Makefile.am file. The Add Target item pops up a dialog in which you can set the rules for compiling, building or installing a group of files within your subproject. Add Service (... to be written ...) Add Application (... to be written ...) Add Existing Subprojects (... to be written ...) The Remove Subproject item in the popup menu for a subproject is the proper way to remove a subproject. It will adjust the `Makefile.am` files accordingly. You will also be offered the option to delete all the files (or links) in the corresponding subdirectory. Obviously, this feature should be used with caution. The Build item calls all necessary compile and make operations to build the code for this subproject only. Force Reedit (... to be written ...) Clean (... to be written ...) Install (... to be written ...) Install (as root user) (... to be written ...)

### Automake Projects

(... to be written ...)

#### Autoconf

##### Effect of the Configure Script

`Makefile.in` into `Makefile`

    prefix = @prefix@
    INSTALL = @INSTALL@
    build_triplet = @build@
    CXX = @CXX@

    prefix = /home/bernd/kde3
    INSTALL = /usr/bin/ginstall -c -p
    build_triplet = i686-pc-linux-gnu
    CXX = g++

`config.h.in` into `config.h`

    /* Define if you have libz */
    #undef HAVE_LIBZ
    /* The size of a `int', as computed by sizeof. */
    #undef SIZEOF_INT

    /* Define if you have libz */
    #define HAVE_LIBZ 1
    /* The size of a `int', as computed by sizeof. */
    #define SIZEOF_INT 4

#### Automake

(... to be written ...)

#### KDevelop's &automanag;

##### A screenshot of the automake manager

#### Building and Installing Libraries

- -rpath

- PIC

- static

- plugins: no-undefined

### Custom Makefiles and Build Scripts

(... to be written ...)

### Compiler Options

(... to be written ...)

### Make Options

(... to be written ...)

## Advanced Project Management

### Multiple Build Configurations

(... to be written ...)

### Cross-Compiling

When you have suitable cross compilers available, you can cross compile your programs for processors and operating systems different from the system where &kdevelop; and the compiler is running. The &gnu; compiler collection GCC can be configured and compiled as a cross compiler if you compile it yourself. Consult the GCC info pages for more information. Some Linux distributions also provide binary packages.

An automake based package can easily be cross-compiled by specifying the `--host` option to the configure script and setting the `CC` and `CXX` environment variables to the respective cross compiler binaries. Often you want to switch between a the cross-compiled version of your application and one compiled for your development system. For this, it is advantageous to use &kdevelop; capability of creating multiple build configurations, as explained in buildconfigurations. Once you have created a new build configuration for cross-compiling in the Project Project Options... dialog, add the option

    --host=platform

to the configure options. The `platform` name is a tuple of the form

    cpu-vendor-os

or

    cpu-vendor-kernel-os

For many combinations, you can use a short form, for instance i386-linux or arm-elf.

### Qt/Embedded

&qte; is a version of the &qt; library that does not use the X window system, but draws directly to the framebuffer on Linux systems. It is therefore interesting for embedded systems which have tight restrictions on the memory usage of the whole system. Its API is fully compatible with the one of the X11 version.

Developing an application for &qte; with &kdevelop; is not very different from developing a program for the X11 version of &qt;. In fact, you can use the same codebase for both versions. If you use the autoproject project management, you switch to the embedded version by passing the argument `--enable-embedded` to the configure script. You can set this in the Project Project Options... dialog under Configure Options. With the option `--with-qt-dir=DIR` you set the directory in which &qte; is installed.

After configuring and compiling your application with these options, it will link with the `libqpe.so` library. This version of your application will not normally run when you use X11. In order to test it, run it under the control of the program qvfb (Qt Virtual Frame Buffer). This is done by starting qvfb and then starting your application with

    app -qws -display QVFb:0

Naturally, when you have a working version of your application, you will want to use it on the target processor. For this, it will probably be convenient to create multiple build configurations, as explained above, so that you can quickly switch between the version running on your development system and the version running on the target system.

Applications for &qte; normally run as single applications on the device they are designed for. Trolltech also supports Qtopia, which is a collection of applications for PIM, web browsing and various other areas that work together in a consistent manner. It is the standard environment for instance on the Sharp Zaurus. You can write applications that integrate into this environment by using the Qtopia SDK. This implies making your application class a subclass of `QPEApplication` and linking to the library `libqpe.so`. If you develop your application with the autoproject project management, you have to add `--enable-qtopia` to the configure options.

## The Debugger Interface

For C and C++, &kdevelop; contains an internal debugger that is directly integrated with the editor. Technically, it is implemented as a frontend that uses the portable &gnu; debugger gdb through a pipe. The debugger can be started in several ways:

- With Debug Start, the main program of your project is loaded into the debugger.

- Using Debug Start (other) Examine core file you load a core file into memory, which is generated by the operating system kernel when the program has crashed (The generation of core files may be switched off on your system, see ulimit(1)). This is useful for a post-mortem analysis of a program.

- With Debug Start (other) Attach to process you invoke the debugger on an already running program. You will be shown a process list where you can select the process which the debugger should take over.

- Note that debugging is only possible if your project has been compiled with debugging information enabled. It can be activated in the Compiler options dialog. When this option is switched on, the compiler generates additional data which allows the debugger to associate file names and line numbers with addresses in the executable.

The debugger frontend offers several views into the process:

- ## Variables

  This window lists the values of all local variables at the current execution point of the program. It covers the variables in the complete call stack, i.e. the function where the process was interrupted, the function that called this function, and so on up to `main()` function.

  Another branch in the variables contains watch variables. You can configure yourself which variables are shown here. Both local and global variables can be watched. You can add variables either by clicking on the Add button or pressing RETURN while the Watch item is selected. They can be removed again via the context menu.

- ## Breakpoints

  (... to be written ...)

- ## Frame Stack

  (... to be written ...)

- ## Disassemble

  (... to be written ...)

### Setting Breakpoints

(... to be written ...)

### Options

### Display Mangled Names

In C++, function names in the executable are mangled, i.e. the function names include information about the argument types. This is necessary in order to support overloading of functions. The mangling algorithm is not standardized and differs even between different versions of the &gnu; C++ compiler.

In the disassembling window, normally unmangled names are displayed, so function signatures appear in the similar way as in the source code, so they are easily readable. Alternatively, you can decide to see mangled names.

### Try Setting BPs on Lib Load

The debugger backend gdb does not allow to set breakpoints within code that is not currently loaded. In a highly modular application, where often code is only loaded on demand as a plugin (using the libc function `dlopen(3)`), this can be inconvenient. Therefore, &kdevelop; rolls its own support for breakpoints in shared libraries. If you set this option, it allows you to set breakpoints in libraries which are not loaded. Then, whenever gdb notifies that a library is loaded, &kdevelop; tries to set the pending breakpoints.

### Enable Floating Toolbar

(... to be written ...)

## Using CVS

### &CVS; Basics

&CVS; is the revision control system which many open source projects - including &kde;—are using. It stores all sources codes in a central place, called the repository. From the repository, developers can check out a current version of the project or snapshots of it at arbitrary points of time. In contrast to some other revision control systems, it is not necessary to lock files one wants to work on. So development can be highly parallelized.

Whenever a developer has finished a task, he commits his code (accompanied by a log message). &CVS; takes the job to merge the changes made by several developers. It can of course happen that developers work on the same piece of code, resulting in a conflicting set of changes (in practice this occurs seldom, and is often a sign of a lack of communication). In this case &CVS; rejects a commit; only after all conflicts are resolved, a file can be committed.

So far, this has been a description of the basic features of &CVS; one usually has to cope with. But &CVS; can provide a lot more: One can maintain several branches of a project (e. g. &kde; 1.1.2 and &kde; 2 were branches in &kde;'s development tree), merge changes from one branch to another, ask for differences between revisions, the revision history of files etc.

&CVS; is implemented as a client-server system. As a user, all communication with the repository goes through the command line program &cvs;. A higher level user interface is available through frontends like Cervisia () or TkCVS (). In &kdevelop;, only a small part of the &cvs; functionality which is important for your daily work can be used directly.

Basic knowledge of &CVS; usage is assumed. In particular, you should know how to checkout a given project from the repository. We recommend the book Open Source Development With CVS by Karl Fogel which is freely distributed (except for the non-technical chapters). See .

### &CVS; Commands in &kdevelop;

In the file views, the following context menu items are available:

- ### Add to Repository

  Prepares the marked file for addition to the repository. The file is transferred to the repository when you commit it (or the containing directory) the next time.

- ### Remove from Repository

  Prepares a file for removal from the repository. This also deletes the file on the local file system, so use this feature with care!

- ### Update

  Runs `cvs update` to merge any changes from other users into your working directory. When you use this menu item over a directory, the update normally happens recursively, except if you have disabled this in the configuration file `.cvsrc`.

- ### Commit

  Runs `cvs commit` to upload any locally made changes to the repository. Note that you should update before doing this. Otherwise, when another user has committed his own changes before, &CVS; may give you an error message.

All these commands are invoked as subprocesses by &kdevelop; without any further command line options or environment variables. This may be a problem when the connection with the &CVS; server goes through a &ssh; connection and requires that you enter your password each time you commit or update. This is for instance necessary when your project is hosted on `sourceforge.net`. Workarounds for this problem are described on the CVS/SSH FAQ which you can find in the SourceForge documentation.

### Behind the Scenes

#### What &CVS; Records in the Working Directory

(... to be written ...)

## Leveraging External Programs

Although &kdevelop; is a so-called Integrated development environment, it will never contain all features that you may want to use, and the capabilities of its editor will never suffice to perform often-used text processing tasks. As a genuine UNIX program, &kdevelop; contains several possibilities to start external programs, plugin external programs to work on files, or use external filters to process the content of the editor.

The most general and simple feature of this kind is the tool menu, which you can freely configure. This is done in the Settings Configure KDevelop.... dialog under External tools.

Other tools will be discussed in the chapter plugin-tools.

## Credits

### Contributions

- The initial contents of this manual were witten by Bernd Gehrmann bernd@kdevelop.org and Caleb Tennis caleb@aei-tech.com.

- The Summary of &automanag; and Automake Manager Operation chapters were written by Ian Wadham, ianw@netspace.net.au).

## Menus and Toolbars Survey

(... to be written ...)

## Shortcut Keys

(... to be written ...)

## Plugin Tools

&kdevelop; contains a large number of little tools that help you to perform certain task. Most of them are realized as plugins. This means, if you do not like one of them, you can simply disable it in the Project options dialog under Plugins (for project-wide plugins) or under Settings Configure KDevelop.... Plugins which are switched off do not clutter your menus and are not loaded into memory.

- ## The `abbrev` Plugin

  This plugin expands abbreviations into frequently used code snippets. It is activated by pressing Ctrl Space. For example, when you enter `"ife"` into a C++ in the editor and press Ctrl Space, you obtain an `if-else` code template and save some key strokes. The set of supported abbreviations depends on the programming language of the edited file. For example, for PHP you will obviously be interested in other code templates than for Java.

  The set of code templates is configurable. You can see which ones are available in the Settings Configure KDevelop... dialog under Abbreviations

- ## The `filter` Plugin

  This offers two features. If you select Tools Execute command, you can enter a shell command. The output of this command is inserted into the editor buffer when you hit the Start button.

  A related feature is available under Tools Filter selection through command.... In order to use this, you must select a text area in the editor. If you now enter a shell command and hit the Start button, the command is started and the selection used as the standard input for it. The standard output of the command is then inserted into the editor.

- ## The &doxygen; Plugin

  This one helps you to use the &doxygen; API documentation tool (). You can select Project Run Doxygen to generate API documentation for your current project, based on the configuration given by the file `Doxyfile` in your project directory.

  Furthermore, you can configure &doxygen; in the Project Project options... dialog. This dialog is very similar to the &doxywizard; tool.

- ## The &ctags; Plugin

  Although the class browser gives you extensive insight into the symbols and classes of your project, you may also want to use the ctags tool. In particular, this one supports a lot more language than the class browser.

  You activate this plugin under Tools CTags.... When you start it the first time, you will be asked to generate a search database first. When you accept this, the &ctags; program will be started and will create a file named `tags` in your project directory. This is a text file containing all symbols of your source files.

  You can search in the symbol database in two ways: when the Regular expression match box is checked, the text you enter will be interpreted as a regular expression (POSIX flavor) and matched with the existing symbols. For example, the text `.*Widget` will search for all symbols ending with `Widget`. If the box is not checked, the search will be verbatim.

  When searching, you will get a list of the matched symbols, accompanied with the line numbers where they are defined. You jump to the respective point by clicking on the list.

  For some languages, &ctags; distinguishes different kinds of symbols. For example, Python has classes and functions. You can selectively search only for classes by checking the respecting kinds in the dialog.

  The symbol database is normally not updated when your sources change. Consequently, after a while the line numbers will not be correct anymore and newly added classes and functions will be missing. Therefore you should update the `tags` file in regular intervals by pressing the button Regenerate.

- ## The `astyle` Plugin

  (... to be written ...)

- ## The `regexptest` Plugin

  Designing with regular expressions can be hard work. Often the first try at an expression matches too many strings. In particular, when working with a compiled language, the turnaround times when debugging a regular expression can be awkward. The regexptest plugin allows you to directly explore the changes in a regular expression. It is activated by choosing Tools Debug Regular Expression....

  In the flavor group box, you can choose the flavor of the regular expression engine used. Currently supported is the flavor defined in the POSIX standard, which is used by the &grep; program, and the extended POSIX syntax used by the program &egrep;.

  When you enter an expression, you get immediate feedback about any syntax errors in it. By entering a text under Test string, you can see whether the expression matches this string. In particular, if your regular expression includes groups, such as `([a-z])`, the content of the matched subgroups will be shown in a list box.

- ## The `konsole` Plugin

  (... to be written ...)

### Survey

&kdevelop; offers extensible modules, or parts, to be loaded at runtime and on demand. This allows developers to only turn on features that they need or want for their development.

Some of the parts are considered global—that is, they effect the entire operation of &kdevelop;. For example, the uimode part allows a developer to select which user interface they wish to use.

Other parts are project specific, and are only utilized when a project of that type is loaded. The Automake Manager, for example, only needs to be active when an Automake based project is currently loaded. Otherwise, this part will not be active.

Active parts can have many effects on &kdevelop;. Depending on their function, they may add extra menus, extra menu items, extra tool buttons, etc.

### Project Management Parts in &kdevelop;

antproject | ANT Project Manager (Java applications)
autoproject | Automake Project Manager
customproject | Custom Project Manager
trollproject | QMake based Project Manager

### Global Parts in &kdevelop;

Part Name | Description
appwizard | New Project Wizard
history |
konsole | Embedded Konsole
editor-chooser | Chooses an internal text editor
doctreeview | Documentation Viewer
openwith |
fileselector | A file selection widget
uimode | Customize the UI mode
texttools | Additional text tools
tipofday | A tip of the day
grepview | A graphical grep utility
cvs | CVS Support
tools |
regexptest | A regular expression tester
abbrev | Abbreviation Expansion
filter |
valgrind | A graphical valgrind frontend

### Language Support Parts in &kdevelop;

cppsupport | Support for C/C++
fortransupport | Support for Fortran
javasupport | Support for Java
perlsupport | Support for Perl
phpsupport | Support for PHP
pythonsupport | Support for Python

### Project Specific Parts in &kdevelop;

astyle |
buglist |
classview | Classview Manager
ctags |
debugger | &gnu; Debugger Manager
diff |
distpart |
doxygen |
fileview |
javadebugger |
manager |
nedit |
outputviews |
perforce |
qeditor |
scripting |
scriptproject |
sourcenav |
svn |
visualboyadvance |
windowmenu |

## &kdevelop; User Interface Mode Examples

### IDEAl Mode

Click here to return to the modes survey.

Screenshot

&kdevelop; IDEAl mode

Click here to return to the modes survey.

Screenshot

&kdevelop; IDEAl mode, closed tabs

This example screenshot demonstrates one of the main virtues of IDEAl mode. There is a maximum workspace available. Yet any tool view is readily available by clicking on the according tab.

You will most probably need some time to get accustomed to the icons in the tab bar. If you got lost, just position the mouse over a tab and wait a few seconds. A short tool tip description will pop up. In this screenshot the Automake Manager tool tip is shown as an example. It describes the lower tab in the right tab bar.

Click here to return to the modes survey.

### Child Frame Windows Mode

Click here to return to the modes survey.

Screenshot

&kdevelop; child frame windows mode

Click here to return to the modes survey.

### Tabbed Pages Mode

Click here to return to the modes survey.

Screenshot

&kdevelop; tabbed pages mode

Click here to return to the modes survey.

### Toplevel Windows Mode

Click here to return to the modes survey.

Screenshot

&kdevelop; toplevel windows mode

Click here to return to the modes survey.

## Further Information

### Getting Information

(... to be written ...)

### Reporting Bugs

(... to be written ...)

### Licensing

&underFDL; &underGPL;

## Changes

### Changes to This Document

- 2003-01-03—Started this Changelog

## Bibliography

(... to be written ...)