]>

# The User Manual to KDevelop

The Reference Guide to the KDevelop Integrated Development Environment for Unix Systems, Version 1.2
Ralf
Nolden
The KDevelop Team

    Ralf.Nolden@post.rwth-aachen.de

The Kdevelop Team
Lauri
Watts
Reviewer

    vampyr@atconnex.net

1998
1999
2000
Ralf Nolden
21/03/2000
1.02.00
KDE
Kdevelop

This handbook is part of the KDevelop Integrated Development Environment, for KDE 1.x and KDE 2.0

## Introduction

Just as everything on earth has its fashions, todays computer world seems to be tending to the use of free software, even for commercial purposes. The most popular free software project is Linux. It is now generally agreed that Linux, (as well as other projects such as the Apache web server, the Perl language and the GNU suite of tools), proves that free software can be of as high a quality as commercial software. But despite the quality, end users must still suffer from the often cryptic commands of any Unix System. For Linux to thrive, it needs applications, both free and commercial, and it needs ease of use.

The KDE
project tries to close the gap with commercial software, by providing an easy to use desktop, and the companion libraries to extend the variety of available GUI
-based software. As free software is often made in the author's free time, the question for many programmers is how much they like their current code development environment. kdevelop; wants to take a major step towards making the programmer's life easier and more efficient. Products created with kdevelop; can reach a higher level of reliability and functionality in the same development period.

To fulfill this goal, the KDevelop Integrated Development Environment provides many features that developers need, at the same time as it wraps the functionality of third party projects such as make and the GNU C++ Compiler
, and makes them an invisible, integrated part of the development process.

kdevelop; manages:

- All development tools needed for C++ programming including the Compiler
  , the Linker
  , automake
  , and autoconf

- kappwiz;
  , which generates complete, ready-to-go sample applications

- 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

- The creation of User Handbooks written in SGML
  and the automatic generation of HTML
  -output
  with the KDE look and feel

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

- Internationalization support for your application, allowing translators to easily add their target language to a project

- WYSIWYG (What you see is what you get) creation of user interfaces, with a built-in dialog editor

- Managing your project via CVS, by providing an easy-to-use front end for the most needed functions

- Debugging your application, by integrating kdbg;

- Editing of project-specific pixmaps
  with KIconEdit

- The inclusion of any other program you need for development by adding it to the "Tools
  " menu, according to your individual needs

kdevelop; makes it a joy to work with all the necessary programs in one place, and saves time by automating standard development processes, while giving you direct and transparent access to all the information you need. The integrated browsing mechanisms are designed to support the documentation
requirements that developers have in conjunction with their project.

The class viewer
and error finder bring you anywhere in the project code with a mouse click, without needing to search for files. File trees give direct access to the project files,
and the integrated help system offers superb access to online-documentation from anywhere within the IDE.

### Changes

Version 1.2 of kdevelop; contains the most needed facilities for C/C++ development. During the development phase of kdevelop;, the project has made great improvements since the 1.0 final release, followed by the release of version 1.1. The current version is to be expected to be the final release for the KDE 1.x series, giving developers the environment they want to use.

Improvements were made in the following sections:

- fast class-parser and -browser with graphical class-tree view and dialog-based adding of members and classes

- CVS support for the most needed functions such as adding, removing, updating, and committing files and directories

- updated and extended documentation, now comprising five handbooks shipping with kdevelop;

- bug-fixed dialog-editor and error-finder

- updated documentation tree which lets you access the class documentation, up to any method of classes directly

Any comments about the IDE, its documentation, or feature requests are welcome.

### About this Handbook

This user manual gives the user a complete overview of the kdevelop; IDE and describes the basic development process in brief. For more information about specific programming issues, we suggest reading the KDevelop Programming Handbook included with kdevelop;, which covers themes such as understanding generated application framework
s, and how to create full-featured KDE
applications, using example projects.

The design of this handbook is therefore separated into the following parts:

- Chapter Installation, covers the system requirements, installation and setting up of the kdevelop; IDE.

- Chapter Programs, tells you how programs are created with standard GNU development tools and how they are built.

- Chapter Development with kdevelop;, takes you on a short tour, describing the main functionality of the environment.

- Chapter Overview, explains the menus and dialogs, as well as keyboard shortcuts
  .

- Chapter The Help System, shows how to use the built-in documentation browser
  and additional help functions.

- Chapter Working with the Editor, explains the features for file management and editing.

- Chapter Projects, describes the creation and maintaining of software projects.

- Chapter Build Settings, contains a reference on how to set Compiler
  and linker flags, as well as project options.

- Chapter The Class Browser, tells you how to make use of kdevelop;'s powerful Class Browser.

- Chapter The Dialog Editor, features the integrated visual GUI
  constructor and how it generates C++ output
  .

- ChapterThe Internal Debugger,gives an overview of the debugging setup and use of the internal debugger

- ChapterCVS Integration, tells you how to use the revision control system CVS, and RCS with your kdevelop; project.

- Chapter General Configuration shows how you can set overall preferences for using kdevelop;.

- Chapter Questions and Answers, covers questions regarding the usage of kdevelop; under different flavors of Unix systems, and problem solutions in general.

For programming beginners, and new users of this product, we recommend you read entirely through this manual before starting to actually work with the IDE, as it covers the usage in depth. The understanding of how things are done the quickest way will save you a lot of time searching for functions and features, as it will enable you to make full use of first-class development tools.

### About the kdevelop; Project

The kdevelop; project was started in summer of 1998 (after KDE 1.0 was available on Linux/Unix,) as an attempt to create an easy to use C/C++ IDE for programmers, especially targeting the KDE desktop. Since then the project has found a lot of helpers and supporters, as well as sponsors who want to help the team continue their work on this now widely recognized programming environment. Within one and a half years, the IDE developed to a full-featured KDE application with the most possible functionality and stability, as the creators started to develop the IDE within the IDE itself once enough usability was established. Bugs were mostly found by the authors themselves, and could be fixed very quickly, as well as needed extensions for programming KDE applications.

The first official stable release was made with version 1.0 on December 6, 1999. Thereafter, the kdevelop; Team introduced more features and stability into the IDE by new code or code that was unstable before, which lead to the second release, as version 1.1 on February 28, 2000.

Since then, the project has continued to integrate more functionality and has been simplifying the current code-base. Many translators are transferring kdevelop; to as many languages as possible, to provide the international developer community the IDE in their own language, including the handbooks that ship with it. Many users have contributed their experience and knowledge to the project as one of the most promising products for Linux/Unix developers, helping to make it even more stable and portable to other Unices.

### Printed Versions

A printed version of the complete kdevelop; Documentation is available as the book titled Developing Applications for Linux: KDE Edition, which can be ordered either online from the kdevelop; web site at http://www.kdevelop.org or at http://www.opendocs.org. A share of the Gross Profits from the sales of this book goes back to the kdevelop; project, to support continuing the further development of kdevelop;.

Printable versions of the kdevelop; Documentation can also be obtained from the kdevelop; web site at http://www.kdevelop.org in DVI, Postscript and PDF format, both in A4 and in Letter size.

## Installation

### How to obtain kdevelop

kdevelop; can be found either on the KDE
Applications page at http://www.kde.org/current.html, or on the kdevelop; home page at http://www.kdevelop.org.

kdevelop is also available on Linux distributions, such as SuSE 6.1.

We're also offering snapshots of the kdevelop CVS repository on our home page, for those who want to stay up to date with kdevelop. Usually, the snapshots are not intended to be used for production, but as a test for new features, and to give an insight into development progress of the KDevelop team. We also offer various third party software needed by KDevelop directly such as KDoc
and kdbg;
.

If you are experiencing problems with compiling or using KDevelop, please read the Questions and Answers section of this handbook or the FAQ file included with the KDevelop package. If your problem is not addressed, please subscribe to the KDevelop mailing list at kdevelop-request@barney.cs.uni-potsdam.de by sending an email with an empty header and `"subscribe youremailaddress"` as contents.

Requests and problem reports should only target the usage of the KDevelop IDE, and not questions that regard any implementation
problems you may have while coding your own application. All email sent to the mailing list should be written in English, so that all participants can take part in discussions and are able to provide better help. The mailing list is also intended for those users willing to contribute and who have found solutions for any problems they experienced. This enables us to fix errors
and include that knowledge to give beginners even more qualified first-hand help.

A good way to report problems is to send the output
you get from starting `kdevelop` from the console or to copy and paste the contents of KDevelop's internal Messages-window
.

### Requirements

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

Required:

- g++ 2.7.2/g++ 2.8.1/egcs 1.1 (or compatible), available at http://www.gnu.org/

- GNU make (or compatible), available at http://www.gnu.org/

- Perl 5.004, available at http://www.perl.com/

- autoconf
  2.12, available at http://www.gnu.org/

- automake
  1.2, available at http://www.gnu.org/

- flex 2.5.4

- GNU gettext, available at http://www.gnu.org/

- Qt 1.42, available at http://www.troll.no/

- KDE
  1.1.x, available at http://www.kde.org/

Optional:

- enscript
  for printing
  support

- ghostview or kghostview for printing
  preview

- glimpse
  4.0 for the search index
  , available at http://glimpse.cs.arizona.edu/

- sgmltools 1.0, available at http://www.sgmltools.org/

- KDE-SDK
  (KDE Software Development Kit), which includes KDoc
  , KSgml2Html
  , KTranslator
  (available at http://developer.kde.org/)

- kdbg;
  , available at http://members.telecom.at/~johsixt/kdbg.html

- KIconEdit
  available at http://www.kde.org/

KDevelop was tested on an AMD K6 200, 64MB RAM with SuSE Linux 5.2 and with Free-BSD 3.0-Release, and also SuSE Linux 6.0 on an Intel 200 MMX, 128MB RAM.

As far as known to the authors, SuSE Linux and Free-BSD contain all necessary packages, including enscript
as packages or rpms, so you should have no problem installing the required third-party software.

Documentation:

For creating the KDE
library documentation, you need the kdelibs package in source available on your system as provided by the KDE project or included with the source packages of your distribution, and KDoc
(included in the KDE-SDK
).

We are also offering a C/C++ Reference
on our home-page at http://www.kdevelop.org that is integrated into the documentation browser
after it's installation. Download the package and copy the source file as root into your KDE
directory, and untar it with `tar zxvf c_c++_reference.tar.gz`, then the reference is available in the documentation tree; otherwise selecting the reference book in the browser shows an error page with the KDevelop home-page URL offering a download and describing the installation process.

### Compilation and Installation

In order to compile and install kdevelop on your system, type the following in the base directory of the KDevelop distribution:

    bash$ ./configure
    bash$ make

    and as root

    bash# make install

Since KDevelop uses autoconf
you should have no trouble compiling it.

In order to compile the KDevelop CVS snapshot, type the following :

    bash$ make -f Makefile.cvs
    bash$ ./configure
    bash$ make

    change to `root` and type:

    bash# make install

If your system's `make` command
is `gmake`, type `gmake` instead of `make`.

### Starting KDevelop

If you use KDE
as your window manager, KDevelop can be started by choosing "K"->"Development"->"KDevelop 1.2"". As KDevelop supports KDE
-Mime-types, you can also start by selecting a KDevelop project file ("`*.kdevprj`", displayed with the KDevelop project icon) in the KDE
File Manager, which will start KDevelop and load the project. Under other window managers, open a console and type:

    bash$ kdevelop

To start KDevelop with an existing project, change into the project-directory and type:

    bash$ kdevelop  <yourProject>.kdevprj

Under each user account KDevelop will invoke the automatic installation process on the first start, allowing a quick configuration of the most needed options. If your installation is messed up, you can reconfigure KDevelop any time either by entering

    bash$ kdevelop --setup

or, when using KDE, by choosing "K""Development""KDevelop Setup".

### The Installation Program

KDevelop includes an automatic installation program module, which is invoked whenever KDevelop is started and the configuration file `kdeveloprc` does not exist. We suggest you follow the installation steps by choosing "Proceed" to automatically check your system and to set up your KDevelop environment.

The Installation dialog's buttons execute the following actions:

Help: Will open the KDEHelp program.

Proceed: This starts the installation process and executes the following actions:

1. Checking for make/gmake, autoconf
   , autoheader, automake
   and perl for the creation and compilation of new applications generated by KDevelop. If gmake is installed, the make command
   will be set automatically to use gmake. Other command-line options to your make program can be set in the setup
   dialog accessed by the "Options" menu later. An introduction into development under Unix is explained in section Programs.

2. Checking for KDoc
   and glimpse
   . These will allow the creation of new KDE-Library
   documentation, and a search index
   to be created automatically in a later setup
   step, if found.

3. Checking for enscript
   to ensure that printing
   is available. This program must be installed to allow correct printing
   . If it isn't installed, you can optionally do this at any time later on, without having to run the setup
   again.

4. Checking for kdbg;
   , KIconEdit
   , and KTranslator
   . We encourage you to install those programs, as they are helpful for creating complete KDE
   applications. kdbg;
   is used directly for debugging
   your current project within KDevelop; KIconEdit
   is used to display and edit pixmaps
   selected in the file-viewer trees. The programs kdbg;
   , KIconEdit
   , and KTranslator
   are then configured to be available in the Tools
   menu of the KDevelop menu bar, if they are found. Other tools can be added to the "Tools"
   -menu by selecting "Tools
   ..." in the "Options" menu later.

5. Summary of detected programs: the installer lists those programs it found and those it didn't. Additional hints are given, if a needed program is not found.

6. Detection of your Qt Documentation
   path. This checks for several standard paths in your system for the documentation, and sets the path automatically. If your Qt Documentation
   could not be found, either because it is not installed, or your system keeps it at a different location, a message will appear that asks you to either set the correct path manually or to continue. Choosing the button to set the path will return to the main installation window, and shows an editing field with a button on the right of it to choose the path. Usually this is in the `qt/html` directory. After doing so, the installation can continue with the selection of "Proceed" again.

7. If KDoc
   was detected, you are asked to create/update your KDE
   library documentation. For that, you need to have the kde-libraries in source form.

   For Linux users who have installed KDE
   from a distribution, we suggest copying and extracting the source of the `kdelibs-package` to your system. Free BSD users who installed the kdelibs as a package should look for their appropriate distfile package in the ports-collection.

   If none of these cases match your situation, you should download the sources from http://www.kde.org and untar the sources on your system. If you wish to use the documentation package provided by http://developer.kde.org/, cancel the creation and continue on with creating the search index
   .

   After the installer finished and KDevelop has been started, set the path to the extracted documentation package in the KDevelop Setup dialog, and run the search index
   setup
   again, which can be found at the same setup
   page of the dialog.

   The "Update KDE
   -Library documentation" dialog is set up to use a default path for the location of the documentation, in `$(HOME)/.kde/share/apps/kdevelop/KDE-Documentation`. The only thing you have to do is choosing the path to your library sources you extracted on the system with the selection button on top of the dialog, and press "OK". As an example, if you got the `kdelibs.tar.gz` package from http://www.kde.org/ and downloaded it to your home directory, you should open a console or terminal, and enter `tar zxvf kdelibs.tar.gz` This will untar the sources into a directory `$HOME/kdelibs`, which then contains the sources for each library in a subdirectory, e.g. for `kdecore`, this would be on my computer in `/home/rnolden/kdelibs/kdecore`. Now, the path you have to enter in the KDE-Library documentation dialog would be the path to all libraries, in the example `/home/rnolden/kdelibs`. After pressing the "OK" button, a message in the installation window shows that the documentation generation is in progress and you should wait for the next message.

   On a multi-user system
   or systems with disk-quotas
   for user accounts, the installation of a complete HTML
   documentation for each user would be a waste of disk space. In this case, ask your system administrator to run KDevelop under the root account, to allow write access to the system's root directory. Then install the documentation within the KDE
   directory, under `$KDEDIR/share/apps/kdevelop/KDE-Documentation`. The correct path can then be set up later in the KDevelop setup
   dialog, available in the "Options" menu
   .

8. If the system check found the glimpse
   program on your system, you are offered to create a search database. The search database can be created with the options of including both the KDE Documentation
   and the Qt Documentation
   (the default). Additionally the KDevelop documentation is included and will be indexed. If you have other documentation that you want indexed you can select the directories, and add them to the indexing process as well.

9. During the creation of the search index
   , the installation window will show a message that this is in progress.

10. If all installation steps were done correctly, a final message states that KDevelop will be started after pressing "OK". Mind that you can set up additional options like auto saving in the KDevelop Setup dialog that can be accessed through the "Options" menu.

Cancel: Will show a warning message that the installation process is going to be canceled. This warning message allows you to return to the installation ("Back") or to start KDevelop with the default values ("Continue"). Mind that in this case you will have to set all options manually with the configuration dialog
s provided in the "Options" menu.

## Programs

Now that KDevelop installed successfully and the most commonly used options are set, you are probably wondering if it keeps its promises. This chapter gives you a guideline to how programs are created using the GNU tools in general, and especially what part KDevelop plays in this game.

### The Compiler

The Compiler
is actually the program on your system that has to be installed as a minimum to create running programs; he is the one that compiles the source code into object files and creates the program.

Normally, you would start like this: Open an editor of your choice - don't use a word-processor! Type in something like this to create the source for your first program:

    #include <iostream.h>

    int main(){

    cout << "Hello World" << endl;

    }

Well, actually all the program will do is to print out the string "Hello World" to your standard output
. But this is just the source code for the program to be built, not the program itself. Therefore, we need a Compiler
, in this case a C++-Compiler
like g++. Then we can save the file with the source code, as, let's say, `myprogram.cpp` and invoke the Compiler
with the filename (on a console):

    g++ -o myprogram myprogram.cpp

Now we can start our program: just type `myprogram` on the console, and the program prints out the string, then exits.

### Make and Makefile
s

I have everything I need: an editor, a Compiler
and I can execute my own C++ program. But it isn't all that easy. What happens if you have more than one source file? Do you have to compile all sources over and over again if you only changed one file?

Compiling will become more and more complicated and time-consuming, because you have to type in all the commands and options yourself. You could write a so-called "`Makefile`
" (You could also call it some other name, except the name of the program to build.) Then, you should have the tool `make` or `gmake` installed, or any other tool that is capable of keeping track of a project's compilation. Insert all your Compiler
commands in the correct syntax into that `Makefile`
and save it, and then you will only have to type `make` or `gmake` on the console in the directory where your `Makefile`
is located, and then make takes over, leading the Compiler
to create your application. The make utility has many other advantages and can be used to a lot of purposes.

To get a complete overview, open a console and type:

`man make`

or search for "GNU Make" in KDEHelp, under "System GNU Info contents".

Now you have some insight why a developer needs the make utility for making it easier to compile his application.

Writing a `Makefile`
s is not only hard work up, but you also have to dig yourself into the whole syntax and options. Here is the good news about KDevelop and any Make utility: You just have to set the Make Command in the KDevelop Setup dialog, and then you're done. All projects generated with KDevelop will use that Make command to build the target application, and no more typing at all. Just hit the buttons on the toolbar of KDevelop, beginning with the one after the second separator line, or choose the desired function for Make in the "Build" menu.

The toolbar and the "Build" menu offer the most common functions that you need to let `make` do the dirty work:

Build Compile File

  Invokes the `make` command with the correct parameters to compile only the current source. Only active if you're working on a source file.

Build Make

  Calls `make` and creates your target.

Build Rebuild All

  Rebuilds the whole project

Build Clean/Rebuild All

  Cleans the project directory first and then runs `make` again

Build Stop Build

  Cancels the current process.

  This is mostly used if you watch make working and staring at your sources. Then -ahh- I forgot about this line... and you have to correct your code. Just hit "Stop", correct the error you found by yourself and run `Make` again.

But this is not the only way KDevelop works together with `make` for KDE
applications. There are some special extras, like creating the message files for internationalization. These functions are included, so no need to worry about them anymore.

Now, you know about sources, the Compiler
and why make is needed. In the next section, we'll discuss how projects created with KDevelop can automatically be compiled on most other Unix-platforms using the `configure` script.

### Configure

The title of this section probably has you asking: Configure? What has to be configured? Or who?

Well, assume you have written a program, including a `Makefile`
. Then you would like to distribute it, but the compiled binary only runs on your system or on systems that are compatible with yours.

To support other platforms, like different Unix-systems or machines like Alphas or RISCs, you have to recompile the program. The easiest way would be to copy the source package to the target machine and run `make` again. But what if the target machine uses another Compiler
command or has some other problem to build your binary? Not to mention more difficult issues like installation paths for your program and documentation e.g., KDE
can be installed in `opt/kde/` on one machine, while it is installed under `/usr/local/kde/` on another. In this case, you would have to rewrite the `Makefile`
each time to ensure a correct compilation and installation of your product.

Fortunately, GNU tools have even more to offer than that mighty `make` - the commonly used `automake`
and `autoconf`
packages. It sounds good to hear something with "auto" in the name, seems like something about application design can be done quick and easy, which exactly is the point.

Automake's purpose is generally to create a so-called `Makefile.in`
from a file `Makefile.am`
which you have to write for your project. This `Makefile.am`
consists of macros which are interpreted, and reduce the complexity that `make` offers. A `Makefile.am`
is written more safely and more quickly than creating the final `Makefile`
by hand.

Having this said, you may wonder, who is finally creating me my `Makefile`
? Here comes autoconf
. Autoconf requires several macro files for the project. These are in `Makefile.in`
's generated by automake
and a file called `configure.in`, also containing macros.

The `Makefile.am`
and `Makefile.in` files contain macros that are responsible for how to build the software, in terms of which sources have to be compiled, which files belong to the package, and what name the final binary or library will have after a build. `Configure.in` on the other hand contains macros for what the final `configure` shell script will check for on the system at the time `configure` is executed. These could be e.g., the Compiler
command, required libraries against which the final binary will be linked, include-files the project needs, and their locations.

For example: you want to write a KDE
application. After writing your sources, you want to distribute the program to the user community, and each user has to compile the binary on his own. Then you would write a `configure.in` file that contains the macros for a KDE
compliant application. That single macro eventually expands. to a check on the system whether the Qt-library is installed, checks for the Qt header files, the KDE libraries
and headers etc.

Summary: To create a GNU-compliant application that is portable to different Unix OS's and machines other than yours, you will need to do the following:

1. write the sources for your project

2. write a `Makefile.am
   ` for each subdirectory, including the main project directory of your project

3. write a `configure.in` file, placed in the main project directory, containing the macros for system requirements.

4. run `automake`

5. run `autoconf`

Then the main work is done. Automake creates the `Makefile.in`
files, then autoconf
processes the `configure.in` and generates an executable shell script called `configure`. All you then have to do is to execute it with `/.configure` and the script will run the checks of your choice. Finally `Makefile`
files will be generated, that allow a final execution of `make` (or `gmake`) that will process all `Makefile`
files and then you're done.

This seems to be a lot of stuff, for simply writing a small application, and much to learn, especially how to write correct macros. But even the fact that you provide a compilation on almost all Unix systems will be worth this work sooner or later. Finally, you only have to do this work once for your project, and if your project's files increase in number, you only have to add the filenames to the macros.

Now, how far does KDevelop support this kind of application development and how complicated does it get for the programmer? The good news is, that you don't even have to know anything about macros and scripts. All details are hidden behind an easy to use graphical interface doing the work for you. An application is therefore created with GNU tools in a very user friendly way.

Just generate your application with kappwiz;
, by choosing your application's needs: may it be a pure C++ terminal application, or a kind of GUI
program using Qt, or the Qt/KDE
libraries. All work is done automatically and your project already contains the `Makefile`
s that are created by an auto execution of the GNU tools and the `configure` script.

This is it - you're ready to extend the source of your project, may it be by adding classes
, dialogs, translations or documentation, which is also completely automated. Just concentrate on the real work of the developer, which is providing functionality for the final application that you want to create. In most cases, you probably won't come in touch with `Makefile`
files at all when using KDevelop.

### Debugging

The following section covers a term that is widely used by developers: Debugging. It means that, although your Compiler
produces the final application, your application may not run or crash during execution due to a so-called "bug" in the code. A program error described by the name of an insect, comes from the history of computing; one of the first errors
that caused a machine to crash was not obviously a malfunction - real bugs were inside the computer, which were responsible for the crashes. Therefore, an error not detectable on the first look is called a "bug", so "debugging
" means to throw out bugs where they shouldn't be.

Nowadays, you don't have to hunt them for real, assuming that todays computers are designed to keep them out by some kind of outer protection. They are to be found inside the code instead, mostly ending the execution of a program with the message "Segmentation fault".

GNU provides another tool called gdb, the GNU debugger. This terminal program allows you to watch the internal values of an application, and the execution, step by step, by setting "breakpoints" in the code. Gdb stops the execution every time the program comes to a breakpoint while executing. But like most other tools, the debugger is handled by another program providing a front-end to it, making it easy to watch values, and set breakpoints in the code.

For this purpose, your project's application is by default created with a Compiler
option for debugging
, storing additional data in the executable to allow the localization of values and lines in the code. As a third-party front end to gdb, KDevelop makes use of kdbg;
, the KDebugger.

To debug your program, you just have to select "Debug" in the "Build" menu or press the corresponding tool-bar button, displayed by a wheel with glasses over it, signaling that you want to watch the execution.

KDevelop then opens the Tools
-window and starts your application with kdbg;
. The kdbg;
interface appears inside the Tools
window, and allows usage just as if you started it from outside.

In general, the above steps show the required steps that a developer must complete when starting to write his own application, and cover issues that are common to all projects. Also, we explained what part KDevelop does for a developer and how it supports the idea of providing an easy way to Unix programming. To get further information about the role and purpose of GNU tools, you should read the documentation provided with them, commonly accessed via the `man` command or by the "System GNU Info contents" section in KDEHelp.

## Development with KDevelop

In this chapter you will get a general overview of how you can use KDevelop and the internal dialog editor
to create your own applications.

All tools are described by their use during the development process. If you are a beginner in C++/GUI
design and programming, you should read The KDevelop Programming Handbook, which describes some basics for program design and shows a more detailed use of KDevelop through sample projects which you can follow step-by-step, to get used with the way applications are created using KDevelop. Also you should have read chapter Programs to gain a general understanding why Unix applications should make use of provided development tools. This will make things easier when you hit references to what a `Makefile`
is, etc.

### What are KDevelop Project Applications?

Projects created with KDevelop make it very easy for developers to use the GNU standard development tools. Instead of the self-creation of `Makefile`
files, which have to be written anyway because of the project's complexity, the GNU tools provide not only a better method of `Makefile`
generation, but also a good and safe way to provide fast adaption towards different systems through autoconf
-generated `configure` scripts.

The distribution of your applications does not require the end-user to have anything different installed than a C++ Compiler
and the development libraries, which is most often the case anyway, but you can also distribute binary packages of your application. Either way, the end-user of your product does not have to have KDevelop installed. For giving away your sources, we advise to include the project file of KDevelop as well, as this makes it very easy for other developers to work with your sources if they use KDevelop as well. For projects where several developers, maybe working on different places, are involved, this should the case anyway, to ensure consistency of the `Makefile`
files so you don't run into trouble. Especially on multi-language applications, translators won't actually work with the source code, except in cases that require corrections to enable translation support. Even in those cases, translators will be thankful as KDevelop reduces their work to a minimum by adding their language and reducing the work to concentrating on the translation.

When using KDevelop for your own projects, you would start creating a new application with the kappwiz;
. There, you can set the project type according the goals of your program. Then, you would start developing the user interface by adding widgets
that are already constructed in the libraries and only have to be called by your application, or by self-constructions that can be made with the dialog editor. Next comes the extension of the user interface by changing and extending those parts that are already created by KDevelop like the status-bar, menu-bar and tool-bars. As resources are collected in a resource file, this can be extended simply by adding new values to the already existing ones. The given resources can also be used as a guideline for adding your specific ones. After implementing the functionality to methods that are either generated empty by the dialog editor
, or already containing code for standard user actions, you should extend the User Manual by simply editing the provided SGML
index file to describing your applications capabilities. The last step would be to generate translation files and to distribute your project to translators working to enhance internationalization.

But even for non-GUI
application designers the IDE offers an easy way to create new projects: the editor and Class Browser in conjunction with KDevelop's powerful project management will reduce the time for development to the minimum that is required for implementation
of functionality.

### Short Description of KDevelop's Tools

With KDevelop you have chosen a package, that, in conjunction with the use of other tools, will provide you a prefect and flexible environment for object-oriented application development under Unix-Systems. Generally, KDevelop consists of the programming environment, and the dialog editor
. Besides these, all needed programs that can be helpful for designing applications are embedded in one or the other way.

#### Programming Environment and Dialog Editor

##### The Programming Environment

The Programming Environment is the user interface that KDevelop provides for creating and maintaining projects, using many other tools while simplifying their use. It's built-in Editor and Help-browser
as well as the Class Browser reduce the amount of work that development processes usually burden on the programmer. The ease of use features make writing applications for Unix an enjoyment on it's own and will probably result in shorter release cycles and better development improvements. From here, you're managing your project throughout all its details, keep the overview over your classes
and don't have to use additional consoles for your work. The integration of all user interfaces results in the fact that you only have to work with one window under X and don't have to watch for several windows spread all over your desktop.

##### The Dialog Editor

KDevelop's built-in dialog editor
offers a simple way of designing user interfaces with the Qt and KDE
libraries. Its simple way to do almost everything with the mouse allows a rapid construction of dialogs and main views for applications and their direct transformation into C++ code, which is directly added to the project. As the dialog editor
is embedded into the rest of KDevelop's user interface, you have these same commands available when working in Programming mode. This allows e.g., construction of a dialog, generation of the code output,
and it's direct testing, all within the program, by the availability of the `make` command
. You can also still control the Compiler
output
without having to switch back to the programming view. For a detailed description, see The Dialog Editor.

#### kappwiz;
and the Class-tools

The kappwiz;
and the Class-tools provided for project generation and automatic code extension are intended to make the creation of applications as easy and safe as possible. It offers a good way for beginners in Qt/KDE
programming to start actually working themselves into the details of GUI
application design, as results can be achieved very quickly.

##### kappwiz;

kappwiz;
is intended to create full-functional application projects that are ready-to-run by using GNU standard tools and, for GUI
-programs, taking advantage of the KDE
and Qt libraries. By specifying only the information that is required as a minimum, users are able to start working on a new project within seconds. Calling kappwiz;
should be the first step to be to creating a new application with KDevelop.

kappwiz;
provides you a so called application skeleton, with all needed C++ source code files for a running application. After you have specified a project-name and set the needed preferences, your new project will be generated and you have a complete application that already contains a lot of functionality (for KDE and Qt projects), without you even having to type one line of C++ code yourself.

When specifying the complete set of options the program generator offers, your application already contains:

- an SDI-Interface (for working with one document per application window), based on the document-view-controller model

- Menus and dialogs for opening and saving files, as well as printing
  dialogs

- a tool-bar and status-bar already providing complete functionality

- a help-system, containing an SGML
  -based user manual and status-bar help

- a complete HTML
  based API
  (application programming interface) documentation for the current state of the project

- an installation routine though make

The kappwiz;
is available under the "Project" menu entry "New...".

##### Class-tools

The term "Class-tools" describes a variety of functions that are available for the developer to work on a project not only by an object-oriented language, but using the sources in an object-oriented way. Working with classes
instead of having to watch for files offers a very flexible way to extend a project and lets the user concentrate on the objects the project contains.

The tools that KDevelop offers are a Class-generator and a Class Browser, each one providing a lot of automated functionality.

###### Creating a new class with the Class-generator

After generating a project with the kappwiz;,
your work as a developer would be to add a set of classes
that match the design of the application. The typical process without using KDevelop, would be to create a new header and source file, add them manually to the appropriate `Makefile.am`,
and to start writing the new class
declaration
and implementation
.

To simplify the whole process, the Class-generator lets you do this by only specifying the new class by its name, inherited class, and inheritance attribute, and any further information such as class documentation by it's purpose for the project. Additionally, you can change the filenames that are preset by the generator, and if the class should be Qt-signal/slot enabled by default.

The rest of the work is done automatically. You don't have to take care of `Makefile.am`
files and the class itself. A new make invocation is enough to include the new class in the compilation process.

As the Class Browser updates itself after the addition of a class, the declaration
and implementation
are available at once, and you can start working on the extension of the class. The Class-generator is invoked by the "Project" menu, entry "New Class
".

###### The Class Browser

The Class Browser displays all types of objects and functions of your project, in a tree left of the editing windows. A class parser scans all files for methods and classes,
and makes them available as graphical symbols. Further, context-menus offer a specialized functionality to work with the sources, by focusing on the classes
and functions.

Selecting a class will result in opening the file that contains the declaration
; on methods and functions this will show you the implementation
. For a full description, see The Class Browser

### The Development Process

The development of a new application with KDevelop can generally be divided into two major steps: first, you have to generate a program skeleton with kappwiz;
, then the "rest" of the development has to be done using KDevelop's features, which only requires your abilities as a programmer. To describe the development process, we assume you want to create a Qt/KDE
application, which implies using most of KDevelop's features for working with these types of project, so you have a general "HOW-TO".

#### Creating a Program Skeleton

To start creating your application, you normally would call the kappwiz;
, enter the project name, and generate the program. The wizard automatically creates a project file for the application and inserts the KDevelop areas into the Makefile.a
's, which will be used later when extending the application. The project file is the file you load to open the project in later sessions.

You call kappwiz;
with the "Project" menu entry "New...". When the wizard appears, you first specify the project type on the first page. Selecting "Next >>" brings you to the next page, where you insert the project name, version, directory, and your personal information. Page 3 offers more detailed options. Pages 4 and 5 allow the editing of file headers for header and implementation
files that are inserted automatically according to your selection. If you already have file headers you want to use, you can choose those files as well. The last page contains an output
window and an error message window.

When selecting "Create", your application will be generated and the actions that are executed can be seen in the output
window. If "READY" appears in the output
window, the kappwiz;
is finished, and you can select "Exit" to return to the Programming Environment. To build the binary, choose "Make" from the "Build" menu, or choose the corresponding button in the tool-bar. You can also test the functions already present, by choosing "Execute" from the "Build" menu.

#### Developing an Application

This section describes the development phase of applications with KDevelop and the dialog editor
, and all work can be done within the IDE.

The development steps are generally to edit the source files, the compilation of the project sources, followed by the Linker
process binding all object files to the final binary. Then errors
have to be located which either prevented a compilation or linking, or are semantical bugs that can be found by a debugging
session. Finally, the documentation has to be extended and translations have to be added. But as all those steps can mix which each other, it is not that easy to describe a general way how to develop your own application.

Typically, the procedure would be to first create all visible parts of the project such as the main view, and the dialogs for configuring options, then generate the source code and implement all needed connections that remain, like changing the menu-bar and tool-bars, adding status-bar help for new menu entries and filling the new member functions with the objects that display your dialogs. Then you would compile your application and test it's capabilities, fix errors
and test it again.

The following sections describe how this would be done; for your particular application you may choose another way. KDevelop leaves you enough flexibility to decide what to do at what time.

##### User Interfaces

The User Interface of an application is what the user sees, and what he uses to interact with the program. A program generally has a menu-bar, tool-bars, and a status-bar, as well as a main view which could be for example a text input window for an editor.

kappwiz;
generated applications already contain a complex functionality in graphical interfaces; the frame structure takes care of standard elements such as bars and buttons. When developing your application, you have to extend the given structure to give the program the user interaction capability you want to provide.

One part of the work is the design of dialogs e.g., for changing values like the brush width in a paint application. This can be done easily with the dialog editor
inside KDevelop. Now, how do you create those good-looking dialogs? As the Qt-library
is a GUI
toolkit, it provides a base set of so-called "widgets
" such as labels displaying plain text, line-edits for text input, and buttons for navigation and selection commands. Besides these "low-level" parts of user interfaces, standard dialogs are provided, and are ready to use, such as printing
dialogs.

The KDE-libraries
are based on the Qt-library and contain replacements for certain dialogs as well as additional widgets
that can be used in your application.

So, when you start designing your application's behavior towards the user, you should make yourself comfortable with the widgets
provided with Qt and KDE
. The online-documentation of Qt offers screen-shots for most of them, so you should have a look there first. Then we advise to have a closer look at the KDE-UI library, offering other widgets
. Libraries like the KHTML
library contains very specialized widgets
that a lot of programs make use of. It just simplifies application design, using the predefined dialogs provided with Qt.

For your own dialogs, those low-level widgets
are the one you need. A dialog merely consists of a collection of different widgets
, combined together to build the interface, and is technically programmed by C++ code, in a class that is derived from
`QWidget`, or a more specialized dialog class that inherits
`QWidget`. The program using the widget, therefore needs an object of the widget's class. This is almost all you have to understand how dialogs or views are used.

The dialog editor
of KDevelop now offers a nice, simple way to construct dialogs and user interfaces visually, instead of you having to combine dialogs with pure C++ code, the hard way to create interfaces. Switch to the dialog editor
by choosing the appropriate entry in the "View" menu (or by using the tool-bar button). You will see that KDevelop's face has changed but the menubar and the toolbar are very similar. This makes it very easy to switch back and forth between the two working modes, and you will feel comfortable in both after some time.

In the dialog editor you can construct your views and dialogs as you like, and set all available preferences for the items the view will contain. When you're finished, select "Generate Sources" from the "Build" menu. The dialog editor
and project management will take care of the rest. You can test if everything went OK by selecting Make or Execute from the "Build" menu. This will build your application, including your new sources. Don't expect that dialogs are immediately usable, this is a matter of implementation
, as is the usual way a developer works. Don't worry, implementation isn't too difficult either.

For more information about creating dialogs, see The Dialog Editor. Examples and guidelines can also be found in The KDevelop Programming Handbook.

##### Binding New Elements

After you have created your user interfaces and generated the sources, you are ready to make your application use them as objects. As described above, a usual GUI
-based program contains among other things tool-bars and the main view. In addition, the main view interacts with the bars, which are part of the main application class, and it interacts with the document object it is connected to.

In terms of object-oriented design, you would describe the given architecture as the "Document-View-Controller" model. This model describes the basic functions for objects in an application, regarding their role within the program. The Controller represents the one coordinating the main application, and provides user interaction through a menubar, toolbars, and a statusbar. The Document class takes the task of representing a document the user works with. Therefore, a document class should do all actions like loading files, and saving them again.

The view now is in the center of the application window, showing the user a part of the document visually, and providing all functions to manipulate the data by the user. As the bars and toolbars are already present, your task is to create the main view and additional dialogs, through which the user can change settings, and access additional functions.

To build your main-view, the generated source code for your application already contains a class in the form of `<YourApplication>View` which inherits the
`QWidget` class. This is the minimal class that handles visual interfaces in Qt and therefore in KDE
as well.

In general, there are three ways to extend the given class:

- Remove the document-view structure and use one of the predefined "big" widgets
  already containing a lot of functionality; just remove the View-class and replace the view-object by another.

- Change the inheritance of the View-class. Change the inheritance to e.g. `QMultiLineEdit` and your application would be an editor.

- If your main view will consist of several separated parts, create the widgets
  and the classes
  you need with the dialog editor,
  and create objects of these classes
  in the view-class constructors, that in combination, will build the main view.

For dialogs, things are a bit different. The usual way to call a dialog is through a menu-bar entry or a tool-bar icon. After you have constructed your dialog, and generated the sources, the class is available for creating an object that will be the dialog. So you first have to look for a suitable place in the menu-bar to add an entry which will open the dialog when selected by the user. If the already given menus do not match your needs, create a new pop-up menu just like the others, and insert in it your entry and the slot you want to call when the menu-item is selected. Then implement the slot by creating an instance of the dialog class, and call the dialog with the member functions
given by the base class.

You must also specify an ID for the menu-entry. The frame applications have all the IDs already issued collected in a file called `resource.h`, so you have only to add the ID and give it a new number, then you're done. Additionally you could construct another tool-bar icon and add the status-help message. Your application now offers a new functionality which is visible to the user.

Now you must add the implementation
of methods that your dialog will be operating with to manipulate any values. Finally, call your make-tool or "Execute" and the changed files will be recompiled; the result of your changes can then be tested immediately.

##### The Complete Development Process

Above, we discussed the usual way to start working on a new application using KDevelop and how to extend the user interface. These are the standard steps where the IDE helps you, but KDevelop does more than providing tools for creating applications and their visual components. The following gives a short description of the main functionality that is offered for enhancing application development.

###### Sourcecode Management

The KDevelop IDE provides a lot of methods for programmers to achieve their goals within the shortest time. As described above, the kappwiz;
and the dialog editor
shorten the time you would usually need to get to the same result manually. But this didn't cover the further work a programmer has to do usually: working on the implementation
of his application to provide a proper execution for the end-user.

Why is KDevelop the IDE you would want to use as a coding environment, including using it to create even non-GUI
applications?

The IDE keeps track of your project in general; that means you don't have to take care of saving changes, the `Makefile`
generation and so on. This is full project-management, and KDevelop plays out all it's power here, in any case of C++ application development. It is easy to understand, after taking away the management from the programmer, he is able to concentrate more on working out the sourcecode.

On the other hand, the code is usually spread over many different files across the project, so you can separate certain parts. This could mean working the hard way: being the developer, you still would have to struggle with creating these files and writing standard contents, like file headers containing the date and the author's name, or things like license terms for the code. This requires that you remember where your functions, class declaration
s, and implementation
s are in the project.

KDevelop contains the "Class-tools," a variety of actions that allow fast work and move the developer's focus from files, to objects: classes,
structures, and methods.

The class-generator lets you easily create a new class, including inheritance, attributes,
and documentation.

For object-oriented work, the Class Browser brings you to the location of your objects. It doesn't matter any more where the code actually is. The Browser scans all sources automatically and rebuilds itself after additions to keep up with your work and enables you to access the new code directly. Through context-menus, the browser offers even more functionality, such as bringing you to the implementation,
or to the declaration
of member functions
. The addition of members are done graphically, in dialogs. No need to search for the file, and then the place you would have to add your entries.

Finally, you can get an even more specialized view of your project's classes
through the Class-tool dialog, which provides trees that show the usage, contents, and inheritance of classes
and their objects. For more detailed information, see The Class Browser.

###### Building and Executing your Application

The KDevelop IDE is specially designed to take away all those tasks that you have to do periodically like building and executing your program as well as locating errors
in the sourcecode.

You start the build-process by:

- clicking on the symbols "Build" or "Rebuild All" in the tool-bar

- or selecting Build Rebuild All from the menu.

To execute your application, choose

- the symbol "Execute" or "Debug" (starting kdbg;
  with your program) from the tool-bar

- Build Execute or Build Debug from the menu.

- Build Execute with Arguments to start your application with additional arguments

For more information about the build-process, see Projects.

###### Searching For Program Errors

Errors may
occur either during the build-process (which are detected by the Compiler
and are called syntactical errors
because they result from a wrong syntax of the sources), or during the execution of the application. Those errors have to be found and removed by the programmer. To locate errors
, the developer needs the information as to what exactly caused its occurrence.

As mentioned, the Compiler
is able to detect syntax errors
itself, resulting in an error message that the executable can't be built. Note that this can also happen from the Linker
when it detects "unresolved symbols"; see Linker Options).

As the compiler gives as detailed as possible a description of the error, the error can be found and removed. During the build-process, you will see the output
window pop up showing you what your make-tool and the Compiler
has to say. In case of errors
or warnings
, just press the mouse button over the error line and the editor will open the affected file and sets the cursor to the error line. This can also be done by the entries in the "View"menu, "Next Error" and "Previous Error" or by the appropriate keyboard shortcuts
. You will find that this is very functional and saves a lot of time to get to the error, although to remove the cause, your knowledge as a programmer is asked.

Runtime Errors, which occur during execution and will mostly result in a segmentation fault, are sometimes hard to find. Therefore, you can enable the Compiler
to add information within the binary to watch the execution by the sourcecode. A debugger is a program that lets you do this by starting the application and letting you set breakpoints in the code, where the execution stops, so you can control critical implementation
s and by this detect at least the line that caused the error. Finding the real cause is another task, it depends on the programmer to locate this.

The `gdb` is a debugger that is provided with the GNU Compiler
and programs like ddd or kdbg;
are front-ends that allow easier use. KDevelop uses kdbg;
and lets you invoke the debugging
process by the commands "Debug" in the "Build"menu or by the "Debug" icon in the tool-bar. For more information about debugging
applications, see Projects and The KDevelop Programming Handbook.

### Additional Information

The topics addressed within this chapter are described in more detail within the documentation provided with the KDevelop IDE and in the following other documentation:

- The KDevelop Programming Handbook, covering a complete introduction into GUI
  application design and programming with the Qt and KDE
  libraries.

- This handbook, sections Overview to Projects, describing all available functions within KDevelop.

- This handbook, section The Dialog Editor, addressing the use of the dialog editor
  to create your own widgets.

- The Online-Reference
  Documentation to the Qt-library
  , which covers examples of using the Qt GUI
  -toolkit, as well as a class reference and screenshots for the most important ready-to-use widgets
  included.

- The KDE-Library Class-Reference
  , generated automatically by KDevelop from the KDE-Library sources, containing descriptions for all classes
  and widgets
  including example code for their use,

- And on the Internet, see:

  - http://www.troll.no/ for information about Qt and additional third-party widgets

  - http://www.kde.org/ for information about the KDE project and developer guidelines

  - http://developer.kde.org/ for additional references to KDE application development

  - on the KDevelop home page http://www.kdevelop.org/

## Overview

Looking at KDevelop, the user interface can be described by it's logical separation: the main window, the treeview and the output
window, surrounded by the menubar, toolbars and the statusbar. This section describes the purpose of each part of the interface, starting with the windows, followed by the bars and the functions they provide.

### Main Window

The main window consists of four tabs, of which the left two are for editing purposes. First comes the Header/Resource window for headers and any other text files, e.g., the documentation SGML
's. Next is the C/C++ window for sourcecodes. These are followed by the Documentation window displaying documentation in HTML
format. Finally there is the Tools
window for external programs like KIconEdit
and kdbg;,
which are embedded into the IDE.

Any Tool that is registered, can be accessed via the "Tools"
menu. The registration of third-party programs can easily be done in a configuration dialog
(see General Configuration).

For a description of the Editor windows functionality, see chapter Working with the Editor, and for the Helpbrowser
, you should look at section Using the Documentation Browser.

### The Class Browser and File-viewers

#### The Class Viewer

The Class Viewer
(CV
) shows the classes
of your project, as well as global functions and variables
.

Opening the tree will show all member functions
and members, with symbols for attributes
(private, protected and public, signals, and slots,) so you can see the properties of members visually without switching to the header file.

Selecting the class name will open the headerfile containing the class, and set the cursor to the class declaration
beginning.

Selecting member functions
will open the implementation
file, and place the cursor at the function header. For elements, KDevelop will look for the header file and place the cursor at the line the element is declared.

The class-viewer
also provides pop-up-menus that offer more specified options. See The Class Browser for more detailed information.

#### The Logical File Viewer

The Logical File Viewer (LFV
) allows sorting files, by filters and in groups.

Individual groups can be added by the properties entry of the "Project" menu or by a right click on the tree items. This allows a more specialized search for files that you want to access quickly, in the first place only showing project-included files. According to their Mime-type, the files will be opened when selected. You will like the LFV
for things like selecting pixmaps.
This will start KIconEdit
(if installed on the system,) in the Tools
window, and open the chosen picture.

#### The Real File Viewer

The Real File Viewer (RFV
) shows the project directory tree with all files, so you can edit non-project files,
or files hidden by the LFV
e.g.,`configure.in` and `Makefile`
s. Pop-up menus also provide functions like adding or removing files to the current project.

#### The Documentation Tree

The Documentation Tree (DOC
) displays all available HTML
based documentation that is configured, as books. Selecting a book will open the first page in the Browser window. Also, a pop-up menu provides personal configuration for additional HTML
based documentation packages.

### Output window

The Output window is separated further into a messages window, a stdin/stdout window and a stderr window, for the following necessities:

Messages Window

  Displays all output
  of the Compiler
  . Clicking on error messages will change the edit widget to set the cursor to the line where the Compiler
  found an error.

stdout Window

  Display for terminal based applications that send messages to the standard output
  of the computer. Note that Terminal applications are now started in an external console window.

stderr window

  Displays all the error messages your program produces. This is useful for testing purposes. The Output window is programmed to show up each time an external process is called, such as make or a terminal application.

### Menu-bar
Commands

#### File Management and Printing

This section covers the functions that KDevelop provides about files, accessed via the File menu in the menu-bar or by the corresponding icons in the toolbar:

Ctrl N File New

  Opens the "New File
  " dialog, allowing the creation of a new file. The file can be created using different templates and the filename must be given, as well as the path where the file will be created.

Ctrl O File Open

  displays the "Open File..." dialog and lets you choose a file to be opened.

Ctrl W File Close

  Closes the file in the top editing window

Ctrl S File Save

  Saves the file open in the top editing window. If the file has never been saved, the "Save File As..." dialog will be opened, to let you choose a path and filename for the file.

Ctrl A File Save As...

  Opens the "Save File As..." dialog to let you save the current file under a new filename

Ctrl l File Save All

  Saves all changed files.

Ctrl P File Print...

  Opens the "Print File" dialog where you can set various options for printing, using either enscript or lpr.

Ctrl Q File Quit

  Exits KDevelop. If files have been changed, you will be asked if you want to save these files.

#### Editing Files

Here, the "Edit" menu and the corresponding icons in the tool-bar are covered. The editing functions are also available via a context-menu in the editor
.

Ctrl Z Edit Undo

  Reverts the last editing operation

Ctrl X Edit Redo

  Lets you do the last undone step again.

Ctrl X Edit Cut

  Cuts out the selection and copies it to the system clipboard.

Ctrl C Edit Copy

  copies a selection to the system clipboard. This also includes selections made in the documentation browser

Ctrl V Edit Paste

  Inserts the clipboard contents at the current cursor position

Ctrl I Edit Indent

  Moves a selection to the right

Ctrl U Edit UnIndent

  Moves a selection to the left.

Ctrl Insert Edit Insert File..

  Lets you select a file and the inserts that files contents at the current cursor position.

Ctrl F Edit Search...

  Opens the Search dialog that looks for an expression in the current file. To search across several files, "Search in Files..." should be used.

F3 Edit Repeat Search

  Repeats the last search for an expression. This also works for searches made across documentation, where more than one hit was found in the same page. The next hit will be displayed by choosing Repeat Search or pressing F3.

Ctrl R Edit Replace...

  Opens the "Search and Replace" dialog, which allows the search for an expression, and replaces the found text with a new expression.

Ctrl Alt F Edit Search in Files...

  Displays the "Search in files..." dialog, that works grep
  on whole directories with wildcards. Search results are displayed with a list of the filenames, line and expression. Choosing an entry will open that file and the cursor is set to the line of the search result.

Ctrl A Edit Select All

  Selects the whole text of the file currently open in the editing window

Edit Deselect All

  Deselects the whole text of the current file. This is often used for multiple selections so you don't have to find and deselect each one separately.

Edit Invert Selection

  Inverts the selection. Text previously selected becomes deselected, and text which was not selected becomes selected.

#### View Configuration

The View-Menu covers closing and opening functions for windows, and commands to enable/disable the tool- and status-bar, as well as to jump to errors
in the code.

Ctrl G View Goto Line

  Opens a "Go to Line..." dialog that lets you insert a line-number to show in the actual file. The last line-number is remembered and marked, so you can either jump to that line again directly, or enter a new line number that you want to see.

F4 View Next Error

  Jumps to the next error KDevelop detects from the output
  . The output
  message of Make or other tools should give you a description of the problem is, so you can correct the error.

Shift F4 View Previous Error

  Jumps to the previous reported error

Ctrl D View Dialog Editor

  Switches to the dialog editor.

Ctrl T View Tree-View

  Enables or disables the Tree window on the left side of the main view containing the Class Browser, LFV
  , RFV
  and DOC
  -tree.

Ctrl B View Output-View

  Enables or disables the Output window on the bottom of the main view.

View Tool-bar

  Enables or disables the tool-bar.

View Browser-Tool-bar

  Enables or disables the browser tool-bar, containing the back, forward, and search buttons for the browser.

View Refresh

  Rescans all files to rebuild the Class Browser. The scanning progress is shown in the status-bar progress display.

#### Creating and Maintaining Projects

This section describes functions that are available in the "Project" menu and cover the creation and maintenance of projects.

Project New...

  Starts the kappwiz;, and allows you to create a new project by choosing application type, name, version, and other options.

Project Open

  Shows the "Open Project" dialog, where you can choose a KDevelop project file to be opened. After selection, the project will be loaded.

Project Open Recent Project

  Contains a sub-menu with the last 5 opened projects. You can open a project more easily using the recent project menu.

Project Close

  Closes the current project. This is mostly done automatically when you quit KDevelop, invoke the kappwiz;
  or open another project.

Project New Class

  Starts the class generator to create a new class that will be added to the current project. The class generator lets you specify classname, inheritance and filenames for the new class.

Project Add Existing File(s)

  Opens a selection dialog where you can choose the files that you want to add to the current project, and the path where they will be copied to. If you choose a destination that was currently not included in the project, for example, creating a new subdirectory, KDevelop will copy the files to add to the new subdirectory, and create a new `Makefile.am`
  . After the copy process, your project will be rebuilt by automake
  and autoconf
  to include the new subdirectory into the make-process.

Project Add new translation file

  Opens a language selection dialog that lets you choose the translation file language that will be added to the project. This is mostly used by translators, who can easily add their language to the project and work on the translation without having to care about the `Makefile.am
  's`.

Shift F7 Project File Properties

  Opens the File Properties dialog showing a copy of the LFV
  and the project file options. Here, the properties for your files have to be set, like installation path, and file type.

Project Make messages and merge

  This is intended to create the messages file for your project. The message file is the one containing all strings that are set up in the sources for internationalization, and is used by translators to create the .po file for their target language.

Project Make API
-Doc

  Calls KDoc
  on your header files, and generates a HTML
  output
  with the documentation of your project classes
  .

Project Make User Manual

  Runs KSgml2Html
  on your manual SGML
  file, creating an HTML
  user manual. If KSgml2Html
  is not installed, sgml2html will be used to do this.

Project Make Distribution tar.gz

  Creates a distribution file of your current project in the project directory that is ready to ship to the end-users containing the sources of your project. The end-user has to run `tar zxvf yourproject.tar.gz` to unpack it to a source directory, and then use the standard commands `./configure`,`make` and `make install`.

F7 Project Options

  Opens the Project Options dialog that lets you change various settings for your project. This could be a new version number, or perhaps to set the compiler options
  to `-02` for a release with optimization.

#### Building Projects

This section describes the Build menu that contains all actions to be done with `make` or actions like rebuilding the project's online help or API
documentation.

Ctrl F8 Build Compile file...

  Active, if the top editing window is the C++ Window. This only compiles the current implementation
  file, and lets you save time in case you suspect errors
  .

F8 Build Make

  Invokes the make-command
  on your project, and builds the target.

Build Clean Rebuild All

  Cleans the project directory from all make-created files and rebuilds the target.

F10 Build Stop Build

  Stops the current process.

F9 Build Execute

  Executes your target, after building the program with make.

Alt F9 Build Execute with Arguments

  Executes your target with arguments. First, a dialog appears to let you specify the execution arguments (which are saved in the project for the next session), then your application uses the entered commandline. Note that your application program is started from the project directory directly.

Build Debug...

  Opens kdbg;
  in the Tools
  -Window to debug your application. In this case, kdbg;
  automatically opens the file containing the main() function and executes your application.

Build DistClean

  Removes all files that are generated by the project like object files etc. Distclean has to be done before distributing your project, so the distribution file doesn't contain any platform-specific files like those that were generated by your Compiler
  .

Build Autoconf and automake

  Calls `Make` on the file `Makefile.dist`
  , located in your main project directory. Makefile.dist
  contains all the commands for automake
  , autoconf
  etc., to build your project. If you added files manually or changed macros yourself, you should run `Autoconf` afterwards, followed by `Configure` to recreate all `Makefile
  s`.

Build Configure

  Executes the configure-script generated by `autoconf`
  . If this command cannot be executed, run `Autoconf` and then run `Configure` again.

#### Calling Tools

The "Tools"
menu contains by default the entries for the following programs if installed: kdbg;
, KIconEdit
and KTranslator
. These are checked by the KDevelop installation program and inserted in the given order into the menu. Invoking a tool will open the "Tools" window and start the selected program inside this window. The "Tools"
menu can be edited by the "Tools"
-entry in the "Options" menu; see Configuring the Tools Menu.

#### Changing KDevelop's settings

The "Options" menu contains all entries for invoking configuration dialogs,
s with which you can change KDevelop's default settings.

Major settings like those for the editor
or printing
have their own entries; general setting of KDevelop's behavior can be made with the KDevelop Setup dialog.

Options Editor

  Allows the configuration of the editors behavior such as word-breaking, selections, etc.

Options Editor Colors...

  Here, you can set the color-configuration of the editor
  e.g. the background and text colors.

Options Editor Defaults...

  This sets the default display, e.g., the default font and font size for the editor

Options Syntax-Highlighting

  This dialog lets you configure the fonts and colors for the highlighting of several programming languages, including HTML
  .

Options Documentation Browser

  In this tab-dialog, you can set the fonts, sizes and colors for the internal Helpbrowser
  .

Options Configure Printer...

  Contains the entries for the printer configuration dialog
  s.

Options Configure Printer...enscript

  Configures the printer for use with enscript
  . See Printing for more information.

Options Tools

  Opens the Configure Tools
  dialog. Here, you can configure the "Tools
  " menu by adding or removing programs that will be started in the Tools
  -window.

Options KDevelop Setup

  Opens the KDevelop Setup dialog. The first tab configures general settings, followed by the key-configuration and the Documentation settings. The Documentation settings also include the generation of a new set of HTML
  -library documentation, and the rebuilding of the search index
  for the Helpbrowser
  .

#### The Window Menu

The Window menu contains a list with all currently open files. This allows a quick switch between files you're currently working on.

#### Managing Bookmarks

The Bookmarks menu is intended for adding and removing bookmarks
you want to set in the current editing file. As KDevelop uses two editing windows, each one configures it's bookmarks
separately.

Bookmarks Set Bookmark

  Opens a context-menu with up to nine configurable bookmarks
  . This allows setting a bookmark to a certain entry in the bookmarks
  menu by logical reasons.

Ctrl Alt A Bookmarks Add Bookmark

  Adds the line of the current cursor position to the bookmarks
  menu as a bookmark. Mind that this could overwrite a bookmark set with the Set Bookmark-option. If the browser is opened, a bookmark will be added to the Browser-Window bookmarks
  menu.

Ctrl Alt C Bookmarks Clear Bookmarks

  Clears the bookmark-entries for the top editing window or the browser, e.g., if the Header-Window is visible and you call Clear Bookmarks, the entries for the Header-Window are deleted.

Bookmarks Header-Window

  Contains the bookmark-list for the Header-Window. Selecting a bookmark will set the cursor to the selected bookmarks
  ' line. Mind that bookmarks
  are specifically assigned to the file they are set in, so if you change to another file, the bookmarks
  are not deleted, but choosing a bookmark won't automatically change to the file they are assigned to as well.

Bookmarks C/C++ Window

  Contains the bookmark-list for the C/C++-Window. The preferences are the same as for the Header-Window.

Bookmarks Browser Window

  Contains the browser bookmarks
  . Selecting a bookmark will open the browser with the selected page.

#### Online Help

The Help menu contains entries for navigating in the Helpbrowser,
as well as most recently used entries for library and online-documentation. Accessing additional online-documentation can be achieved with the DOC
-tree in the treeview, which is automatically opened (if Autoswitch is enabled) when changing to the Documentation Browser window.

Alt Left Arrow Help Back

  Opens the page opened before the currently displayed one.

Alt Right Arrow Help Forward

  Opens the next page of the browser-history, available after a "Back" action.

F2 Help Search Marked Text

  Scans the search-index for text currently marked in the editing windows or the browser-window. After the search, a result page is shown which lets you select the help-page to switch to. After choosing a page, the browser will highlight the found entry for the expression the search was invoked for. With the F3 key the next search result
  on the same page will be displayed, if more than one hit was reported for the search on one page.

Help Search for Help on...

  Opens the "Search for Help on..." dialog that lets you search for a specific expression you want help on.

F1 Help The User Manual to KDevelop

  Opens the User's Manual to KDevelop index page (this handbook).

Help The KDevelop Programming Handbook

  Opens the KDevelop Programming Handbook index page. This handbook contains a complete programming guide to KDE development.

Help KDE Application Tutorials

  Changes to the index page of the KDE Application Tutorials handbook. This handbook explains how to build the Qt tutorial applications and introduces you to KDE programming by developing an example application.

Help The KDE Library Reference Guide

  Changes to the index page of the KDE Library Reference Guide. This handbook contains detailed information about using the KDE/Qt libraries, separated on topics such as event handling.

Help The KDE 2 Developer´s Guide

  Changes to the index page of the KDE 2 Developer´s Guide. This Handbook contains information about the most recent KDE development and how to prepare your application to be KDE 2-ready.

Help C/C++ Reference

  Displays the language reference index page. If the reference is not installed, an error page shows you how to get the reference and how to install it correctly.

Help Tip of the Day

  Opens the Tip of the Day dialog to inform you about KDevelop's features.

Help KDevelop Home page

  Opens the KDevelop Home page in the browser window if Internet access is provided.

Help Bug Report

  Opens the KDevelop Bug Report dialog, where you can send a bug-report directly to the KDevelop Team by email. See Bug Reporting

Help Project-API-Doc

  Changes to the project's class-documentation index file.

Help Project-User-Manual

  Opens the User manual's index file of your current project. This can be used to review the HTML
  -output
  generated by KSgml2Html

Help About KDevelop

  Shows the about box of KDevelop containing the version number, the authors' names and email-addresses, as well as reference to the licensing of KDevelop.

### Toolbar
Items

KDevelop provides quick access to a various set of commands through it's toolbars. These are the standard and the browser toolbar. In dialog editor
mode, only the standard toolbar is visible. Both can be en-/disabled through the according menu entries in the "View" menu, and can also be dragged out of the main window and placed on each side of the working area.

#### The Standard Toolbar

The standard toolbar provides quick access to the most recently used functions for file processing and editing, as well as those for building your application.

The buttons execute the following commands from left to right:

Open Project

  Shows the open project dialog

Open File

  Shows the open file dialog and contains a delayed pop-up to fast select the current project header and source files.

Save File

  Saves the currently opened file to disk

Print File

  Opens the printer dialog

(Separator)

Undo

  Reverts the last action

Redo

  Executes a reverted action again

Cut

  Cuts out the current selection

Copy

  Copies the current selection to the system clipboard

Paste

  Pastes the current clipboard contents to the actual cursor position

(Separator)

Compile File

  Compiles the file currently visible in the source file window. In Dialog-editor mode this is replaced by the Generate Files button.

Make

  Invokes `make` on the project

Rebuild All

  Rebuilds the project

Debug

  Opens kdbg;
  with the application binary for debugging
  in the Tools
  window

Execute

  Runs the application target binary

Stop

  Cancels the current process

(Separator)

Dialog-editor

  Switches to Dialog-editor mode. There, the button is replaced by a Sourcecode editor
  button

Tree-View

  En/disables the treeview and works as a toggle button to display the current state

Output-View

  En/disables the output
  view and works as a toggle button to display the current state

(Separator)

What's this..?

  Help button - changes the cursor to a question arrow and lets you get information about GUI
  components of KDevelop

#### The Browser Toolbar

The browser
toolbar is another toolbar that provides a lot of useful commands for browsing files and the documentation
.

The toolbar contains:

The Class Combo-box

  Lets you select a class of the current project to browse to

the Method Combo-box

  Lets you select a method of the current class, and browses to the implementation of that method

the Class Assistant button

  On a single click, this will bring you to the declaration of the method currently selected. Also contains a delayed pop-up menu to access the Classtools, for adding Classes, Methods and Attributes, as well as the browsing commands

Back

  Browses back in the documentation browser
  history; contains a delayed pop-up to select a certain page of the back history.

Forward

  Browses forward in the documentation browser
  history; contains a delayed pop-up to select a certain page of the forward history.

Stop

  Stops the browser from loading a documentation file request

Reload

  Reloads the currently displayed page

Home

  Opens the KDevelop User Manual index page in the browser

Search Marked Text

  Searches the documentation index for the selected text; works with the browser and the editor
  windows

Search for Help on...

  Opens the "Search for Help on..." dialog, to let you enter a keyword to search for in the documentation

### Keyboard Shortcuts

This section handles the predefined as well as the standard values for configurable keyboard commands used in the KDevelop IDE. You should see section Changing Keyboard Shortcuts for a detailed explanation how to change assigned values to commands.

#### Shortcuts for Text Processing

##### Cursor Movements

One letter to the left | Left Arrow
One letter to the right | Right Arrow
One word to the left | Ctrl Left Arrow
One word to the right | Ctrl Right Arrow
One line upwards | Up Arrow
One line downwards | Down Arrow
To beginning of the line | Home
To end of line | End
One page up | Page Up
One page down | Page Down
To the beginning of the current file | Ctrl Page Up
To the end of the current file | Ctrl Page Down

##### Text Selections

One letter to the left | Shift Left Arrow
One letter to the right | Shift Right Arrow
One word to the left | Ctrl Shift Left Arrow
One word to the right | Ctrl Shift Right Arrow
One line upwards | Ctrl Up
One line downwards | Ctrl Down
To the beginning of the line | Ctrl Home
One page up | Shift Page Up
One page down | Shift Page Down
To the beginning of the current file | Ctrl Shift Page Down
To the end of the current file | Ctrl Shift Page Up

##### Inserting and Copying Text, Tabulators

En/Disable insert mode | Insert
Copy selection to the clipboard | Ctrl C or Ctrl Insert
Insert text from the clipboard | Ctrl V or Shift Insert
Delete current line | Ctrl K
Insert line after current line | End then Enter
Insert line before current line | Home then Enter
Undo editing step | Ctrl Z
Redo an undo step | Ctrl Y
Tabulator | Tab

##### Deleting Text

Delete letter left of cursor position | Backspace
Delete letter right of cursor position | Delete
Delete selected text | Select text, then Backspace

##### Searching Text within the Editor

open "Goto Line..." dialog | Ctrl G
Open "Find text" dialog | Ctrl F
Repeat last search | F3
Open Search and Replace dialog | Ctrl R
Open Search in Files dialog (grep) | Ctrl Alt F
Search marked text with grep | Shift F2
Locate next error | F4
Locate previous error | Shift F4

##### Searching Text with the Documentation Browser

search selected editor text in documentation | F2
search selected browser text in documentation | F2
display next search hit on the same page | F3
search selected browser text within project | Shift F2

##### Browser Shortcuts

previous page | Alt Left Arrow
next page | Alt Right Arrow

##### Managing Bookmarks

Add bookmark | Ctrl Alt A
Clear bookmark list | Ctrl Alt C

#### Shortcuts for Toolbar
Symbols

Icon "Open File" | Ctrl O
Icon "Save File" | Ctrl S
Icon "Print File" | Ctrl P
Icon "Undo | Ctrl Z
Icon "Redo" | Ctrl Y
Icon "Cut" | Ctrl X
Icon "Copy" | Ctrl C
Icon "Paste" | Ctrl V
Icon "Compile File" | Ctrl F8
Icon "Make" | F8
Icon "Execute" | F9
Icon "Execute with Arguments" | Alt F9
Icon "Dialog Editor" | Ctrl D
Icon "Back" | Alt Left Arrow if browser is open
Icon "Forward" | Alt Right Arrow if browser is open
Icon "Search marked text" | F2

#### Window Management

To switch to a certain window, press Altplus the underlined letter in the window title, e.g. Tools
would be Alt T

#### Shortcuts to Compilation Processes

Compile current source file | Ctrl F8
Build current project target | F8
Execute target after Build process | Ctrl F9
Execute target with Arguments | Alt F9
Stop the current process | F10

## The Help System

Most of KDevelop's strength is accumulated in the Help System. It is also an example of how to extend your own KDE application with a complete set of help functionality. This is, in part, already realized in the template applications, so KDE/Qt application frameworks
generated with the kappwiz;
already contain the basic functionality for status-bar help, and for documentation, which needs only to be extended by the programmer.

This section introduces the usage of the general help provided within the IDE, as well as showing the usage of the Helpbrowser
, which, with some intelligent use, will make it very easy to get the information you need for development.

### The "What's this ?"-Button and Quickhelp

Looking at KDevelop's top toolbar, you will see the "What's this?" button on the far right end. After selecting this button, the cursor will change to a pointer with a question mark on the right, the same as the button in the toolbar. You can now select any visible part of the KDevelop user interface and click on it. This will display a help-window giving you a short description of the function the item you clicked gives you, or what it can do for you. Included are the main view, the tree-views and the tool-bars, for which help is provided for very button.

After another mouse click or a keyboard input, the What's this? help window disappears and your cursor is set to the last active position. Note, if you place the mouse pointer over a button, it becomes raised, and after a short time, you will get a QuickTip window, describing the function the button represents in the menubar; this will disappear when you move the mouse pointer away.

For user interaction dialogs, Quickhelp
provides your help windows with a short description of the selected item for which help was requested. These are accessed by a right button mouse click to the item, which pops up a context-menu that allows the selection of "Quick-Help". Selecting this will pop up the help window. This is always useful for dialogs where you can't see the action's purpose for as long, especially if you are not yet familiar with KDevelop. Note that most dialogs offer a Help-button which will show you the detailed context-help for that dialog's options, within the provided online-manual in the help-browser.

### The Statusbar
Help

The statusbar of KDevelop offers many functions to inform you about the current activity state, as well as "status messages" offering a short description of commands.

#### Statusbar
Entries

The Statusbar
contains:

1. a general message field, most left. This is used for help messages and displays the current activity.

2. the progress-bar, indicating the progress for actions that require a comparatively long time to complete, such as saving files, and the scan-progress of the Class Browser. The progress-bar only appears when such processes are executed.

3. an Insert/Overwrite indicator. It shows the editor
   mode for insert actions by INS for Insert mode and OVR for Overwrite mode. The mode can be changed by the Insert key on the keyboard.

4. a line counter, displaying the current line in which the cursor is placed.

5. a column counter, indicating the current column position of the cursor in a line.

#### Help Messages

The statusbar informs you about the action of menu entries, if you select a menu within the menu-bar and select an action, without executing it. If you press on a toolbar icon, without releasing the mouse-button, the help message for the button is displayed in the same way as for the menu entries. You can prevent the execution of the selected icon by moving the mouse-pointer away from the icon, still holding the mouse button pressed. When the cursor is off the icon, release the mouse button.

For actions that are currently executing, KDevelop displays the action. This includes processes running in the background such as saving files, as well as for dialogs. If the process has exited, such as a make invocation, the status-bar display changes back to "Ready" state.

When using the documentation browser
, the status-bar displays link urls for as long as the cursor is placed over an URL link in the browser window. In this manner, you can easily find out if the file is a local or a remote file which can only accessed by network connection.

The caption of the KDevelop Project Editor shows you the currently opened filename in the top window. This would be a HTML
file for the documentation browser,
or a text file for the editing windows. Further, the Project name is displayed, so you have constant control where you are and what you're currently working at.

### Configuring the HTML
Browser

The browser included in KDevelop is completely HTML
based. You can specify the usual options, such as background and the like. You can set all preferences by the "Documentation Browser" entry of the "Options" menu. This configuration dialog
shows you two tabs; the first for setting the font preferences, the second for color selection.

#### Font Preferences

The first option for the font display is the size. Available are small, medium and large. The best display for normal use is set to small by default. For the font selection you must specify a standard font for normal text as it appears in HTML
documents; the fixed font is the one used for displaying e.g., code within the HTML
file.

#### Color Preferences

The color preferences dialog allows configuration of background, normal text, URL Link and followed link color. The colored buttons on the right display the current settings and selecting a button will result in opening the "Select Color" dialog. There, you can specify the color either by choosing a System Color, a custom color, selecting the color in the multi-colored window, or by setting the values directly. The center contains a preview for the color selected.

You may also specify if the browser should underline links, to easier detect them visually, and if you would like to use your own colors always independent of the page's preset ones. "Apply" will execute all changes, while "OK" will apply changes and close the dialog. "Cancel" leaves all settings untouched, and exits the configuration dialog.

### Using the Documentation Browser

The documentation browser
allows quick and easy access to all manuals and documentations that are provided with KDevelop or are generated automatically, including online-documentation for the KDE-libraries,
and your project documentation. Plus, the Documentation Tree in the tree-view lets you customize a special "Others" folder that contains all individually added documentation.

#### Requirements

To make use of all features of the Helpbrowser
, you should have KDoc
and glimpse
installed. KDoc
will generate all kind of online class-documentation for the KDE-libraries
during the setup
process, but can also invoked by option in the KDevelop Setup.

For the generation of an API
(Application Programming Interface) Documentation for your project's classes
, KDoc
is also used and called by the Project menu, entry "Make API Doc"
Doc". This will process all current header files of the project plus the addition of a cross-reference to the Qt and KDE-libraries
if those are available in the Helpbrowser
.

For the generation of the project handbooks, you should have KSgml2Html
(provided with the KDE-SDK
) and, as a minimum, SGML
tools installed on your system. To extend and change your project's online-documentation, you have to edit the documentation file for your project by selecting it in the RFV
. After saving your changes, call "Make User-Manual" from the Projectmenu. In case SGML
tools detect formatting errors
, these will be displayed in the output
window, to allow you to find the error line directly.

The program "glimpse
" is used to create a personal search-index for your documentation automatically. The index is generally built during the installation process, but can also be built with the KDevelop Setup dialog. For a description of the provided search functions see Using the Searchindex.

#### Provided Documentation

The KDevelop IDE comes with two sets of online-documentation, which can be accessed either via the "Help" menu or in the Doc-tree, in the Tree-View, in the KDevelop folder.

The first book provided is this online-handbook, containing all information you need regarding installation, configuration, available functionality, and introduction to application development.

The second book is The KDevelop Programming Handbook in it's first edition. The programming handbook covers most questions related to the creation and extension of projects that work with KDevelop. Through tutorials, the user gets an introduction to the rich facilities that applications created with the Qt- and/or KDE-libraries
have to offer, as well as given a guideline for ensuring KDE
compliance. These tutorials cover the same instructions given on the Internet site at http://developer.kde.org/. However, the programming handbook cannot replace any additional documentation available in printed or electronic form about the C++ programming language, nor documentation about the usage of the Qt-library.

The C/C++-Reference
used with KDevelop is currently only available on the KDevelop home-page at http://www.kdevelop.org/. In certain Linux distributions the reference may be included, see your distribution installation program index for more information. It can be installed easily by downloading and copying the sourcefile to the main KDE-directory (`$KDEDIR`). There, you must untar it as root with `tar zxvf c_c++_reference.tar.gz`. The reference will then be copied the documentation directory of KDevelop. To uninstall the reference documentation, you just have to delete the `reference` folder under `($KDEDIR)/share/doc/HTML/default/kdevelop/reference`.

The Qt/KDE-libraries
documentation folder, allows direct access to the HTML
online documentation of your copy of the Qt-library. The path to the library documentation is usually automatically detected by the KDevelop installation program, but can be set manually in the KDevelop Setup dialog. All available documentation for the KDE-libraries
are listed in order of the library name, so if you would use classes
of a certain library it is easy to determine the library type to be added to the Linker
settings in the project. Note that the whole KDE-Library documentation is only accessible when generated by KDoc,
so this program, included in the KDE-SDK
, has to be installed before the documentation can be generated. As the installation program of KDevelop does this automatically, it should be installed before running the KDevelop Setup. If this is not the case, and the documentation cannot be built, you are able to create it afterwards at any time with the KDevelop Setup dialog.

The documentation tree also contains the "Others" folder, which is intended to contain all personally customized documentation as described below. Finally, the Doc-Tree allows access to the API
and the Manual for your current project.

#### Adding Documentation to the Helpbrowser

To customize your Helpbrowser
, open the Tree-View and select the "DOC
" Tab. You will see an opened tree containing four folders. The "Others" folder is, by default, empty. On a right mouse-button click over this folder, a context menu opens that has an entry "Add Entry". Select this to open the Add Entry dialog where you must enter two values: the upper one for the name that will be displayed for the documentation within the Doc-tree, and, below that, a file-entry line. Here, you enter the path and filename to the start page that will be opened by the selection of the entry later. You can enter the path and filename directly, or by selection of the pushbutton on the right to open a file chooser dialog. This allows a quick browsing on your system to the path for your start page. Mind that only HTML
documentation can be selected, so only HTML
files are available to choose. Selecting "OK" will add the entry to the Doc-tree and it is then available directly.

#### Using the Searchindex

KDevelop includes a set of functions to help you search information within HTML
documentation. To use these features, your system needs to have the program "glimpse
" installed. Glimpse is a free database generator, which creates the search index
and executes searches within the documentation. To set up the index, see KDevelop Setup. The index is also automatically generated during the installation program.

The search functions are available through several ways which you can choose from:

1. in the editor
   , select the text you want to have help on, or place the cursor in the word that you want to look for. Then press the right mouse button and select look up: "expression" This can also be done by selecting "Search Marked Text" from the Help menu, the shortcut key F2or by selecting the Search icon from the toolbar.

2. in the Documentation browser, select the text you want to look up and press the right mouse button, select look up:"expression" or select "Search Marked Text" or the search icon as above.

3. if you want to search for a specific keyword, select "Search for Help on..." in the Help menu or select the "Search for Help on..." icon from the toolbar, in all cases opening a search dialog where you can enter the expression you want to get information for.

Direct access to specific documentation is given by selecting the according icon in the "DOC
" tree-view or through the "Help" menu entries.

The Helpbrowser
also offers support for grep
to search for a selection within your current project. For example, you have opened the documentation page for the `KTMainWindow` class (KDEUI library,) and you want to know where in your code `KTMainWindow` appears. Mark `KTMainWindow` and either select "Grep: KTMainWindow" or press Shift F2. The "Search in Files" dialog opens with the results from grep
search directly. Then you can choose a result line, to jump to the according sourcecode.

## Working with the Editor

An important part of the integrated development environment is the editor
. You will be using it for:

- creating, opening, and saving source and project files

- editing source and project files

- writing your SGML
  documentation

- printing
  your project files

Generally, the editor
itself won't be much different in comparison to other editors, especially as it is a built-in version of the popular KWrite, also known as the "Extended Editor". If you're familiar with that, you won't have any problems using it for managing your projects. In addition to normal editors, KDevelop contains a new printing
system, that is specialized for use with sourcecode, and you can choose which printing
program you want to use.

This section gives you more information about how to handle your project's files
, and to make you more familiar with the editor
's functionality. A lot of Unix hard-liners would prefer using Emacs or XEmacs they're fine with that. But Emacs isn't necessary for easy programming, and especially for beginners, to work themselves into powerful editors, which in the end, only allow you to enter your code.

### Managing Project Files

The following sections describe how to create, save, open, and close your project files
. Note this section doesn't apply to translation files or pixmaps
. Those are recognized automatically, and the appropriate editing program such as KTranslator
opens those files for you.

To give you an easy access to your files, KDevelop contains two easy-to-handle tree-views, similar to a file manager, that recognize if you have selected a file, and open it in the appropriate editor
window.

The main view contains two windows that are used independently, but are connected via the Project Editor, so all menu-bar actions operate the same way. The intention behind this is to allows you to handle two windows at the same time, although only one is visible. The C/C++ window has another task, to allow you to easily compile your sources one by one, so you can check the implementations without having to run a complete build process over your project.

File by file compilation can be done while the C/C++ window is on top. Select "Compile File"
from the Build menu, or press the corresponding button in the toolbar. Your file is saved and compiled, and you can control any errors
by the Compiler
output
in the output
window.

Within the IDE you can open as many text files as you like. All currently open files are listed in the Window menu, so you can switch between them by selecting the filename from the menu. Further, the actual opened file is displayed with its name in the window title-bar of KDevelop.

#### Creating and Saving Files

To create a new file, choose "New" from the "File" menu. This opens the "New File
" dialog, where you can specify the filename and it's type. Additionally, you set the destination directory, and if the file is added to the project or not. Finally, you can also select here to use your header template for the project, in case you want to add a new sourcefile without generating a new class through the Class-Generator.

After the file has been created, you can edit the new file as usual. If you have to switch between different files, you can always turn back to the file either via the file-trees or by the Window-menu.

For saving any changes, KDevelop offers a whole variety of options. The standard way would be to save the file by selecting "Save" or "Save As" from the "File" menu or by the "Save" button on the toolbar. For saving all changed files at once, there is also "Save all" from the "File" menu.

When working on a project, it is very annoying if something critical happens after you have done a lot of changes on your files; sometimes you will kick yourself that you have forgotten to save the changes. KDevelop takes care of this by offering "Autosaving", which is by default enabled, and set to save all files in intervals of 5 minutes. To select another Autosave period, or to disable this, see KDevelop Setup, where the setup
options are described.

KDevelop takes care of all changes if you open another project, or exit KDevelop. You will be asked if you wish to save the changed files, and you also have the option to specify which one to save,e and which you want to stay unsaved. Further, when invoking any build-processes, your files get saved automatically, so you won't ever wonder why your application doesn't run the way you expected it to do after your changes to the source files. The only exception is the "Compile File"
command, which only saves the currently opened source file visible in the source editor
window.

#### Opening and Closing Files

To open a source file, you have a lot of options. One way could be, as is standard for editors, to select "Open" from the "File" menu. You will be presented an "Open File" dialog, which allows you to choose the file you want to edit. Another, probably more frequently used way, is to select the file from the LFV,
the Logical File Viewer, or the RFV
, the Real File Viewer (see Overview). The advantage of the file trees is that they provide a quick visual access to your files, especially the LFV
,which only displays your project files, sorted
by their type, and collected into folders. You can also configure the LFV
to sort your files in another manner by a right mouse click on the tree. Select "New Group" from the pop-up menu, and you can configure a new group. Select "Edit Group" to install new file filters by specifying the group's file extensions, separated by commas.

The standard file groups for a project generated by kappwiz;
are the Headers, Sources, GNU, and Others. Additionally, after adding a translation file, KDevelop adds a folder "Translations", containing your `*.po` files.

To close files, select the file to close from the Window menu, which loads the opened file into the front editor
. Then select "Close" from the "File" menu. If your file has been changed, you will be asked to save it. When closing a project, all currently opened files will be checked for changes and you will be asked about saving as well.

### Navigating within Files

The following gives you a general guideline how to locate certain positions within your files for a quicker access.

#### How to find a certain line in a file

1. Select "Goto Line" in the "View" menu or press CTRL G. The dialog "Goto Line" appears.

2. Insert the linenumber you want to go to.

3. Press "OK".

#### How to set a bookmark

1. Set the cursor to the line you want to access via a bookmark

2. Select "Set Bookmark" from the "Bookmarks"-menu.

3. A pop-up-menu opens that allows you to select the bookmark number you want to set for the new bookmark.

4. Select the bookmark number.

Another way to set bookmarks
would be to select "Add Bookmark" from the "Bookmarks" menu. This sets a bookmark to the current line, and appends it to the bookmarks
-list. The documentation browser
also offers setting a bookmark to the current page by a context menu entry "Add Bookmark".

#### How to delete bookmarks

1. To delete all bookmarks, select "Delete Bookmarks" from the "Bookmarks" menu. This deletes the bookmarks
   for the window actually on top, either the Header window, the C++ window or the browser window.

The bookmarks
are set for each editing window separately. Be aware that your bookmarks
aren't connected to the certain file you set the bookmark for.

#### How to go to a bookmarked line

1. Select the "Bookmarks" menu and open the appropriate popup menu containing the bookmarks
   you want to view; either the C++-Window or the Header-Window entry.

2. Select the bookmarked line.

Selecting a bookmark for the browser window will open the browser and load the page.

### Working with Keyboard Shortcuts

For using the editor
, you should make yourself comfortable with some keyboard shortcuts
that make it easier to position the cursor and edit the file. The complete shortcut reference is also listed in section Overview.

One letter to the left | Left Arrow
One letter to the right | Right Arrow
One word to the left | Ctrl Left Arrow
One word to the right | Ctrl Right Arrow
One line upwards | Up Arrow
One line downwards | Down Arrow
To beginning of the line | Home
To end of line | End
One page up | Page Up
One page down | Page Down
To the beginning of the current file | Ctrl Page Up
To the end of the current file | Ctrl Page Down

### Edit Windows Settings

The editor
inside KDevelop can be configured for special editing needs with a global effect on all editing windows. You can set the color modes, highlighting colors, (also configurable in reference to the programming language of the file,) and automatic text settings like tab-with and selection modes. The following describes how to set these options in the configuration dialogs provided in the "Options" menu.

#### General Settings

The editor
's general settings can be configured with the "Editor" entry in the "Options" menu. Select the appropriate values and press "OK" after you have finished your configuration.

##### Edit Options

Auto Indent:

  this sets the editor to place the cursor below the first literal when a new line is entered.

Backspace Indent:

  this option sets the cursor below the first literal of the line above when backspace is pressed.

Word Wrap:

  words are taken into the next line after the column set in "Wrap Words At:"

Replace Tabs:

  tabs in the current text are replaced with tabs of the "Tab Width:" value

Remove Trailing Spaces:

  removes trailing spaces

Wrap Cursor:

  sets the cursor to the end of the last line when backspace enters the beginning of a line

Auto Brackets:

  creates a closing bracket in front of the cursor when a bracket (any kind) is opened.

##### Select Options

Persistent Selections:

  selections made stay marked after setting the cursor to a different place

Multiple Selections:

  allows multiple independent selections within the text

Vertical Selections:

  allows vertical selections of text

Delete On Input:

  deletes a selection when writing in the selection.

Toggle Old:

  allows only one selection. A selection made gets deselected when another selection is made.

Wrap Words At:

  sets the maximum columns that a line can have. The word that contains a letter that reaches over this value will be automatically broken into the next line.

#### Colors

To change the editor
's general appearance, you can define a set of colors that the editor uses by selecting "Editor Colors" from the "Options" menu.

You can configure colors for:

background

  the editor's background

selected

  the color of selected text

found

  the color of text found by a search via the menu "Edit" - e.g., with "Search","Repeat Search", and "Replace"

selected + found

  the color of text selected to search for, and then found

#### Syntax Highlighting

The syntax-highlighting mode of KDevelop's editor
can be configured by two dialogs.

First you can set default colors for syntax-highlighting by the "Editor Defaults" entry in the "Options" menu. There, you can set colors and fonts as well as the font size for e.g. keywords. Select the default item, and set all needed options.

The second configuration dialog
is accessed by the "Syntax-Highlighting" entry in the "Options" menu. This allows you to set the file filters for the programming language, e.g. `*.cpp`, and `*.h` for C++. Then select the item that you want to configure. If you wish to use the default values you've set in the "Editor Defaults" dialog, select the "default" check-boxes in the Item-style and Item-Font sections. This reads the default settings for the selected item. After pressing "OK", your new values will be enabled and used by the editor
.

### Searching and Replacing

#### Single File Search

##### How to find one or more characters in the current editing window

1. Select "Search" from the "Edit" menu. This opens the search dialog.

2. Specify the expression to search for in the edit field. The drop-down menu offers selecting a previous search expression.

3. Select additional options like "Whole Words only", as required

4. Press "OK".

To repeat searching for an expression entered in the search dialog, press F3.

#### Searching over Several Files

The search function is limited to referencing the single file that is currently visible, but often you want to search for the same expression all over your project. KDevelop contains a `grep
` dialog, which lets you search in all files that you specify, either by setting the directory to start the search from, and/or by mime-type. Specifying the exact directory and the mime-type will reduce the time that KDevelop needs to read your files and display the results. To start a search over several files, select "Search in files..." from the "Edit" menu.

The search dialog opens and lets you enter:

- The expression to search for (the pattern)

- The template used for the search

- The mime-type of files to search in

- The directory to start from

- If the search is recursive over all included subdirectories

By default, the grep
-dialog is set to start at your project directory, and works recursively over implementation
and header files.

You can even extend your search pattern by using the following options:

1. `.` Match any character

2. `^` Match the beginning of a line

3. `$` Match the end of a line

4. `\<` Match the beginning of a word

5. `\>` Match the end of a word

For a repeating search, you can also use these available operators:

1. `?` The preceding item matches less than once

2. `*` The preceding item is matched zero or more times

3. `+` The preceding item is matched once or more times

4. `{ n }` The preceding item is matched exactly n times

5. `{ n,}` The preceding item is matched n or more times

6. `{,n }` The preceding item matches less than n times

7. `{n,}` The preceding item matches at least n times but less than m times

Back-references to bracketed subexpressions are also available by the notation `\n`.

After specifying your search parameters, press "Search". The results are then displayed in the result window. To jump to a file and line number, select the result line and press Enter or double click the result. The editor will automatically open the corresponding file and place the cursor to the line of the result.

KDevelop offers more specialized functionality to use grep
within the editor
s, and the browser. Select the expression you want to search for in either of the windows, and press Shift F2 or select "grep
:<your_expression>" from the right button pop-up menu. This will ask grep
to search for the selected text in your project directory's files, and will show the results immediately. Switching to the result works as described above. From within the editor window, simply place the cursor over a word and start searching; the word under the cursor will be the search pattern.

#### Searching within Documentation

While working on a project, you often need to have information about the parameters of member functions
you want to use. Most often you remember the function name that matches your needs, but the parameters are a very hard thing to keep in mind. KDevelop contains a search functionality that allows searching for expressions that appear in your files in the documentation browser
.

To make use of this search functionality, you must have set up the documentation browser
correctly and created the search database.

To invoke a search through the documentation, do the following:

1. place your cursor at the word you want to search, or mark an expression

2. select "Search Marked Text" from the Help menu
   or press the right mouse button to open the context menu; then select "Look Up: "expression".

3. after the search result
   page is displayed in the documentation browser
   , select the page that you think could contain the information you need.

4. the selected documentation page is displayed and your search result
   is marked. To display the next result within the same documentation page, press F3.

This functionality allows you to easily find the information you need. To aid in using the results, the documentation browser
allows marking a selection and copying it to the clipboard. Then return to the file you're editing and select "Paste" from the "Edit" menu.

For a full description of how to use the Documentation, see Using the Searchindex.

#### Replacing Text

To replace an expression, select "Search and Replace" from the "Edit" menu. The "Search and Replace" dialog lets you specify the expression to be replaced, as well as the replacement expression. Then press OK. The first expression which is found will be marked, so you can see where the expression is and in which context. Then you can specify in a dialog if the expression should be replaced or not. When the search is finished by reaching the end of the current file, you will be asked if you want to start the search again from the beginning. If you're finished, select "Cancel".

### Printing

As KDevelop is designed to give developers the best access to files and information, to reduce development cycles, it also contains a new printing utility which makes use of enscript, a common printing program available for Unix Systems. Besides this, you can also print by directly using lpr (the line-printer device).

As using enscript offers the most options for printing, you should install it on your system; it is usually shipped with distributions, so you shouldn't have any problem finding it.

Before printing, you should have a look at the configuration dialog, to prepare the output according to your needs. The following section describes how to configure KDevelop for printing files.

#### Configuring the Printer

The printing
program can be configured by selecting "Print" from the "File" menu
. In the printing
dialog, select the preferred program in the drop-down-menu in the left upper corner. Then press the "Options" button on the right. This opens the configuration for the selected program. Another way to configure the program is selecting "Printer Configuration..." from the "Options" menu, then select "enscript
".

##### The enscript
Configuration Options

###### Header

Fancy Header

  Adds a fancy header

Header Text

  Enables adding a header text

  Text

    Sets the text contents

  Position

    Sets the text position to left, center, or right

Login

  Add the User-ID to the header

  login

    Enables adding the User-ID

  position

    Sets the position for the User-ID to left, center, or right

Filename

  Add the filename to the header

  Size of filename

    Add filename as full (i.e., with full path) or short (i.e., filename only

  Position

    Sets the position for the filename

Hostname

  Add the hostname to the header

  hostname

    Enables adding the hostname

  size of hostname

    Sets the size for the hostname

  Position

    Sets the position for the hostname

###### Date & Time

Current Date

  Include the current date

  current date

    Enables adding the current date

  position

    Sets the position for the date entry

  format

    Sets the date format

Modification Date

  Include the last modification date

  modification date

    Enables modification date adding

  position

    Sets the position for modification date entry

  format

    sets the date format

Current Time

  Include the current time

  current time

    Enables adding the current time

  AM/PM

    Use AM/PM or 24 hour format

  Position

    Sets the position for the time entry

  Format

    Sets the time format

Modification Time

  Include the modificaiton time

  current time

    Enables adding the current time

  AM/PM

    Use AM/PM or 24 hour format

  Position

    Sets the position for the time entry

  Format

    Sets the time format

###### Layout

Numbering & Border

  numbering lines

    Adds the line numbers to the printed document

  borders

    Adds a border to the printed pages

  numbering pages

    Number printed pages

  align files

    Appends files, for page numbering

  lines per page

    The maximum value for lines per page

Format and Tab

  set TAB size

    Sets the TAB size for interpreting TABs

  Font for header

    Sets the font used for the header text

  Font for body

    Sets the font for the body text (the file contents)

Textprinting

  Cut lines

    Cuts the lines if too long. If left unchecked, lines are broken (wrapped)

  replace non-printing characters by space

    Replaces characters that the printing charset doesn't support with space characters

Other Options

  Table of Contents

    Adds a table of contents page that contains information about printed files, page numbers, etc.

  Highlight bars

    highlight bars

      Highlights rows for printing

    Cycle to change

      Sets the number of rows to change the highlight style

  Wrapped link

    mark wrapped lines

      Mark lines that have been broken for printing

    value for wrapped lines

      The preset value for the newline the line is broken into

###### Underlay

Text

  Sets the text to underlay

Position

  Sets the position of the underlay text

Font

  Set the font used for the underlay

Angle

  Sets the angle for the underlay text

Gray scaling

  Sets the gray scaling value for the underlay text

Style

  Sets the underlay text to be printed as outlined or as filled

#### The Printing Dialog

##### Direct Printing Options

Program

  Sets the printing
  program to be used for printing:
  enscript
  or lpr

Printer

  Sets the printer to be used for printing

Output location

  for printing into a file, select the output
  location

Orientation

  Sets the orientation for printing

Copy

  Sets the number of copies to be made of each page

Paper Size

  Sets the paper size to be used

Output Format

  When using enscript
  as printing
  program, you can choose between postscript or html printing

Default Printsettings

  Sets the default settings to use for printing

Outprinting

  Page Printing

    Sets on or two pages, per sheet of paper

  Pages

    Select all, odd, or even (when using enscript

  Pretty Print

    pretty-print

      Enables pretty-print mode for enscript

    Color

      Use color printing

    Pretty Print Mode

      Sets the mode, dependent on your file format

##### File Selection

The file selection dialog is accessed through the "Files" button on the printing
dialog. The file selection allows you to specify which files to print out by certain criteria:

File Selection
  Current

    The currently opened file, visible in the editing window

  All in project

    All files included in the project currently open

  Self chosen files

    Allows you to choose the files to be printed

  all cpp files

    Prints out all source files of the project

  all headers

    prints out all the header files of the project

  Changed files

    Allows specifying the printing of files changed within a certain timespan

    Between

      Specifies all files changed after:

      Date

        The Date files were changed

      Time

        The time the files were changed

    And

      specifies all files changed before:

      Date

        The Date files were changed

      Time

        The time the files were changed

  Self Chosen Files

    Available only if "self chosen files" is selected (see above)

    Add

      Press this to add a file selected for printing
      in the lineedit field to the left

    Delete

      Deletes a selected file from the printing
      list

    Clear

      Clears the printing
      list

##### Print Preview

Print Preview is available for you to control what the output
will look like. Therefore, KDevelop uses the program ghostview or kghostview. When the preview button is pressed on either printing
dialog, you will be presented a templated output
that shows you the effect of the currently set options.

## Projects

### Project types

#### Programs

KDevelop creates a projectfile with the `.kdevprj` ending. This file contains all your project information, so be careful not to delete it. It is stored in the project's base directory, and is opened to load the project. The projectfile keeps all information for your files, like the file properties, install path, distribution status, and compiler options
(`CXXFLAGS`). Setting file properties allows you to keep track of where the files should go.

With kappwiz;
, you can create a new application project according to your choice of application type. For now, kappwiz;
generates five kinds of frame applications, as follows:

- a single document interface (SDI) KDE
  application, including a menubar, a toolbar, and a statusbar. It contains basic control resource management, to allow extending the frame application into a unique KDE
  application. The application frame also contains statusbar help messages, as seen from commercial products, and just like KDevelop itself.

  From the programmer's point of view, it is based on three application-specific classes
  leaning on the MVC-concept (Model-View-Controller). Technically, the base classes
  may not be viewed that way, but it's construction is at least created most logical to create applications with a GUI
  .

- a KDE
  based application frame window. This application type offers the most flexibility to those wanting to develop their program from scratch, but can also be used as a basis for developing wizard applications or modules.

- a Qt-only based program framework. For those programmers who want to use only the Qt-library
  as the GUI
  interface, we have tried to offer you a smart framework to support your application development. As Qt programming is fully supported, you should have no problems to create a full-functional application by using Qt only.

- a C++ program framework. This application type is intended for those wanting to write a terminal based C++ program. Just remove the "Hello World" line in `main()` and construct your classes
  the same way with KDevelop as you would for KDE
  applications.

- a C program framework for C programmers. This is also a terminal based application but only uses the C compiler.

Further, KDevelop allows you to create projects for KDE 2 and Qt 2.x. These projects require installing the required libraries as well as setting the according installation path in the KDevelop Setup dialog, (see General Configuration) before generating a project, to ensure everything will work automatically. The KDevelop 1.2 Appwizard adds a GNOME-template so that developers wanting to use KDevelop to create GTK+-based applications can do so as well.

Additionally, KDevelop enables you to work with already existing projects. Those can have any options set by the programmer himself in `configure` and Makefiles. As far as the execution and the build-process is concerned, the current state only allows the same structure as for the other base classes. Create a custom project with the application wizard and add your files to the project to allow scanning by the class-browser.

To ensure the build process, your custom project has to have all sources in a subdirectory matching the lowercase name of your project. The execution of the binary is also restricted to this lowercase project name.

KDevelop does not write any information into your custom `Makefile` or configuration files. You are responsible for any project behavior and build settings yourself in this case.

#### Libraries

A general project-type for creating libraries is not available at the moment. Still, building libraries is not impossible with KDevelop.

Here are a few guidelines and workarounds:

- Whenever your project subdirectory gets another subdirectory that contains source files, KDevelop will build a static library of these. That means static libraries are already supported by automatic creation, in order to sort project sourcefiles. Mind that the static library is part of the binary later, and won't be installed.

- To create a shared library KDevelop offers an easy way to turn a such created static library into a shared library: Open the RFV on the left of KDevelop's main window, and browse to the created subdirectory. There, use the right mouse button over the subdirectory. The pop-up menu offers the following options:

  - update Makefile.am

  - change to static lib

  - change to shared lib

  Use "change to shared lib" to convert the default generated static library into a shared one. You can reverse your decision later if you decide that using it as a static library will work as well for your project. Simply repeat the same steps again and select "change to static lib".

#### Multiple Targets

For some projects, the facilities of KDevelop in it's current state are not be sufficient. Those are projects that include multiple targets, such as packages containing several applications. As commands like "Execute" require that only one target is built by the developer, multiple target projects are only supported to a point. You will have to write your own entries to the `Makefile.am
` files, and create your directories for the additional libraries or binaries to build. Nevertheless, a build-process always invokes your make-program independent from what actually the targets are; so these functions still can be used (with the restriction that the build is invoked from the main project subdirectory).

Another way to work with multiple target projects, and to still have access to the binaries themselves, is to create empty projects and move the appropriate subdirectories, in conjunction with the project files,
back to the directory containing all sources later. Then you could load each target independently by its project file. This also allows executing and debugging
the target on it's own.

Multiple binaries or libraries within the main project subdirectory are possible by following the rules explained in sectionProject Hacking, and the following guidelines for editing the main project's subdirectory `Makefile.am` (all modifications outside the KDevelop write area):

- add your target to the `bin_PROGRAMS` if it is an executable

- add your library declaration line if it is a shared library

- add the same declarations as those of the original project binary:

  - `newtarget_METASOURCES`

  - `newtarget_LD_FLAGS`

  - `DISTCLEANFILES`

  - copy the messages: entry for the original binary and replace `target_SOURCES` with `newtarget_SOURCES`, and `target.pot` with `newtarget.pot`

- add the sources for your binary or library the same as the KDevelop write area contains, but outside the write area.

- to install static libraries, create the library with KDevelop's auto-creation inside subdirectories. Then modify the `Makefile.am` outside the write area according to the needed settings

### New Project
s

The KDevelop Application Wizard allows the creation of different types of projects, constructing a framework for each. All projects use the GNU standard development tools as described in the requirements section of this handbook.

For KDE
applications, there are six different frameworks:

Mini

  Creates a KDE application, with an empty main widget

Normal

  Creates a KDE application with session management, menubar, toolbar, statusbar, and support for a document-view codeframe model

Normal-OpenGL

  >Creates a KDE application with session management, menubar, toolbar, statusbar, and support for a document-view codeframe model. OpenGL(tm) (Mesa3D) support is added.

KDE 2 Normal

  Creates a KDE-2 application with session management, menubar, toolbar, status-bar, and support for a document-view codeframe model.

KDE 2 Mini

  KDE 2 Mini: Creates a KDE-2 application with an empty main widget.

KDE 2 MDI

  KDE 2 MDI: Creates a KDE-2 MDI (Multiple Document Interface) application with menubar, toolbar, statusbar, and support for a document-view codeframe model.

If you wish to build an application with no dependencies on the KDE-libraries
for end-users, you can choose from four Qt-only types:

Normal

  Creates a Qt-Application with a main window containing a menubar, toolbar and statusbar, and including support for a generic document-view model.

QT 2.x SDI

  Creates a Qt-2.x Application with a main window containing a menubar, toolbar and statusbar, and including support for a single document-view interface (SDI) model.

QT 2.1 MDI

  Creates a Qt-2.1 Application with a main window containing a menubar, toolbar and statusbar, and including support for a multiple document interface (MDI) model.

QextMDI

  QextMDI: Creates an MDI framework based on the QextMDI library and Qt2.0x. Allows switching between two modes, Toplevel and Childframe. Requires the QextMDI library, see http://www.geocities.com/gigafalk/qextmdi.htm for more information.

Further, the Application Wizard offers a template for creating GNOME compliant applications with the GTK+ C-library, with a ready-to-run main window containing a menubar, toolbar, and statusbar.

The two C and C++ -Application types offer a framework for creating commandline applications.

Last but not least, you can create an empty project, e.g., to work with pre-existing projects.

The wizard asks for your project name, version, and the location where the project directory will be built. Your Name and Email address are asked for, so they may be inserted header and cpp templates on top of your source files, as well as for entries in the `*.lsm` file.

For adding revision control to your project, see CVS Integration.

### Opening and Closing of Projects

KDevelop is by default configured to open the last project loaded when starting. This allows a fast start, but you may want to change that to just start the IDE without any project. To prevent the default behavior, disable the "Load last project" option in the KDevelop Setup dialog.

To open another project, select "Open" from the "Project" menu or press the "Open Project" button on the toolbar. If you have another project currently open, this will be closed. If your currently open project contains files that aren't saved, you are asked to save all changed files. You can select which file to save and which you want to close without saving, or to save all at once.

You will then get an "Open Project" dialog, where you can change to the directory containing the project file to be loaded. KDevelop project files
have the `*.kdevprj` extension, which is also displayed with a project icon. Select the project file and press "Open". When loading a project, the Class Browser scans all files and builds the initial classtree, so you can start working on the project by using the Class Browser directly.

Another way to open a project is to select the project file in the KFM, the KDE
File Manager. This will start KDevelop, loading the selected project file. You could also open a project on the commandline, entering `kdevelop projectname.kdevprj`.

When closing KDevelop, your project file will be saved automatically, and the IDE detects if you have changed any project files. Then you will be asked to save any changes before exiting. The available options for closing are the same as for closing a project before loading another.

### Editing a Project

After you created a new project with the kappwiz;
, the usual next task is to extend the project by editing the already created sources, and adding classes
, pixmaps
, pictures, and whatever else your project needs. Editing a project means that you can change the default project after its generation, through menus and dialogs, according to your needs. The next section describes how you can add existing files and classes
to your project, as well as creating new files. This is necessary for building your project, but won't help you for the installation process by the end-user. Therefore, section Setting Project File Options describes how to set File Properties, especially for additional files that you want make to install, like documentation or pixmaps
. Another part in project maintenance is adding translations, for applications that support internationalization, which is described in Adding Translations.

Extending the Project Documentation covers questions on how to create a good set of documentation for online help, enabling the end-user to help himself in case of trouble, as well as telling the user how to use your product.

Finally, Project Hacking describes how you can work around the KDevelop project management for special cases.

#### Adding and Removing Files and Classes

Adding a new file is often used when you think that you should separate your class implementation
file into several files. Then you need to create an new file, which will contain the part of the class implementation
you want to move. You can do this by choosing "New" from the "File" menu
, opening the "New File
" dialog.

This dialog enables you to specify the file-type, name, and the location. When entering the filename, KDevelop automatically enters the extension for you, but you can change the extensions towards your own preferences.You can include the header template for sourcefiles, so you don't have to copy this into your new file yourself. Also, you can decide, if the file is included in the project or not. This doesn't cover the installation destination, which has to be configured later by setting the file preferences.

After the new file has been created, the project file will be updated as well as the according `Makefile.am
`.

To add a complete class to your project, you can construct a new class with the Classgenerator, which is invoked by "New Class"
from the "Project" menu.

If you have an existing project, and you have certain classes
that you want to re-use in your current project, select "Add File(s) to Project..." from the "Project" menu
. Select "Add existing files", which will open a dialog to let you specify which files will be added to the project and the destination directory. Mind that the files will be copied into the specified directory and added to the project. You should call "Make" after adding sources; then your added files will be included in the build-process. If you want to add e.g., pixmaps
to be installed by the end-user, you should update the File Properties for the added file, and specify the installation path (see Setting Project File Options.)

To add a file to the project that is already in the project directory, go to the RFV
, where all project-included files are displayed by their project status, with a red ! over the file icon. Select the file you want to add to the project (which will have a normal file icon) and press the right mouse button to get the popup-menu. Then select "Add".

Files can also be removed from your project. This could be for example, in cases where you don't want to use pre-generated files that are already given by the kappwiz;
. When removing a file, you have the option to remove a file from the project, or to delete it completely. To remove a file from the project, select the file in the LFV
or the RFV
, press the right mouse button and select "remove". To delete a file, select "delete physically".

#### Setting Project File Options

The file properties dialog can be accessed via the "Project" menu or within the LFV
by a right mouse click. It shows the project files in groups, as they are sorted in the LFV
, and displays the file properties such as file size, file type, and if the file is included in the project, as well as the installation path if the file is going to be installed by the end-user's `make install` command. It is important for documentation files, as well as pixmaps
, to specify the location where the files should go when the project is built and installed by end users, so you must set up those locations. For standard KDE
location macros you should look in your `Makefile.am`
, where the location macros are specified.

#### Adding Translations

As KDE
allows configuring your desktop and the behavior of your applications, you also have the option to choose the language that your application uses, in online-documentation as well as the application's GUI. For documentation files, this seems a trivial task. You would add a subdirectory labeled by the desired language, e.g. `de` for German, to the `docs` directory of your project and copy the English documentation into that directory. Next you would generate the documentation, and set all project file options for the installation directories. Then you could start translating the SGML
file to your desired language, and regenerate the documentation, then you're done. Now we will explain how to enable internationalization support for your application, and how to add the languages you want to support.

First, you must enclose all visible strings in your application, those that appear in bars, or dialogs, with the `i18n
()` macro. This macro is a replacement for the function `klocale->translate()` of the `KLocale` class and much easier to use. As this macro is declared in the `kapp.h` include file, you have to add `&num;include <kapp.h>` to the source file, or the class declaration
file of the class that makes use of the macro.

Although `i18n
()` is a macro and therefore you could think about using the original function, this won't work because the strings that are set up for translation have to be read out of the sources, and are stored in the application's translation file (`<YourApp>.pot` in the `/po` subdirectory). This task is handled by the program xgettext, and to do this, you would enter `make messages`
in your project directory containing the sources. As xgettext depends on the `i18n
()` macro, the original function won't do the job.

For translations themselves, you first have to create the message file containing all strings that are used in your sources, with the `i18n
()` macro. This can be done by choosing "Make messages
and merge" from the "Build" menu.

Then you have to add the languages that you want your application to support. To do this, select "Add Translation File" from the "Project" menu. This opens a language selection dialog. Select the language and press OK. This will build the ASCII file containing entries for the filename of the string, and the line where the original string is placed. Then you will see a msgid line containing the string to translate, followed by msgstr. The msgstr line is mostly empty, except for the translations already provided by the KDE-libraries
. They are to be filled with the appropriate translations of your language.

You could think about writing the translations by hand. But the KDE-SDK
offers the use of the program KTranslator
. KTranslator reads the already existing files, from other applications installed on the system, so you can reuse already translated strings to support your language.

To access KTranslator
, the easiest way is selecting a `<language>.po` file in the `/po` directory either in the LFV
or in the RFV
. This opens KTranslator
and lets you do the translation easily. Mind that you have to set up KTranslator
's properties yourself to include the author name and the language, as well as the destination file. KTranslator
by default only opens your translation file.

For all translation files, `make
` uses the program msgfmt to format your message files to use with the binary, but you don't have to take care of that, nor of specifying the destination directory for installing the translation files. These are all done by KDevelop automatically.

For more information about internationalization support, see http://www.kde.org/; a lot of people are involved in doing translations for you to support their language. You will find a list of email-addresses of the translators you could write to, and who will help you with this. Also read The Dialog Editor and The KDevelop Programming Handbook where questions about internationalization are covered again.

#### Extending the Project Documentation

All projects created with KDevelop contain a pre-configured documentation set, which already contains standard chapters for installation, project name and version, as well as the author name and email-address. As KDevelop uses SGML
templates, it's very easy to extend the documentation to a fully descriptive help system. The only thing you have to do is edit the SGML
file, at `docs/en/index.sgml`.

The reference documentation included with your sgml-tools package can be added to the Helpbrowser,
and will allow you direct access to special tags, as well as a short description of how to extend the documentation. SGML
has a lot of advantages.

KDE
makes wide use by this documentation type with the additional KSgml2Html
tool. This creates the typical KDE
style documentation, and makes it look nice. The sgmltools alone are enough to produce an HTML output
that is already included in your application. To create the documents using KSgml2Html
, install the tool and run "Make User-Manual" from the "Build" menu.

The Documentation Browser allows a direct controlling of the output
by selecting "Project User-Manual" from the "Help" menu or the corresponding icon in the DOC
tree. Then you can browse the documentation online in KDevelop and have a better overview of the output
errors
that result from missing tags.

While extending the documentation, you can't avoid that additional files may be produced that have to be included into the project as each sect tag creates a new HTML
file. The output
generated by the kappwiz;
is already included in the project, so you don't have to worry about their installation path. What you have to watch out for is any `index-xx.html` file, where xx is higher than 6 (as the first six pages are already included in the project). After generating the documentation, switch to the RFV
and browse to your documentation directory. Press the right mouse button over the files to add, and select "Add".

KSgml2Html
adds the KDE
logo to the documentation directory. This file, `logotp3.gif`, has to be added to the project as well. Select the "File Properties" either from the "Project" menu or in the popup menu in the file-viewers.

The easiest way to set the installation path is to select a documentation file that is already set up for installation such as `index.html`. You see that Install is checked and the Installdir + filename already contains the destination. Mark the "Installdir" and enter Ctrl C to copy the installation path to the clipboard. Then select the file you want to specify for installation. Enable "Install", and this will enable the installdir-entry field, already containing the filename. Place the cursor in front of the filename and enter Ctrl V to insert the clipboard contents (the installation path copied before.) This is the fastest way to specify the installation path.

For more options about specifying installation destinations, see The KDevelop Programming Handbook.

#### Project Hacking

When working with a project, you should never edit the project file by hand. This will prevent KDevelop from loading your project correctly under certain circumstances. It could mean that changes will not result in updating the `Makefile
s`.

To change any settings for your project, you have to use the given menu entries For experts that are not comfortable with certain options for e.g. the Linker,
or need additional project configuration, you should work yourself into the `Makefile.am`
macros and add all changes in the `Makefile.am
's` after the section separated with the entry "KDevelop write area".

As the GNU-tools are using the commands at the end of all macro files, you can overwrite KDevelop's settings with this.

Doing this will prevent using KDevelop for any further changes related to project configuration.

### Compiler and Linker
Flags for Projects

Each new project contains all necessary options for the Compiler
and Linker
as well as general settings.

By default, your project is set to use debugging
by the `-g` flag, and warnings
are set to the standard, `-Wall`. This ensures you can debug your application and detect constructions that may cause program errors
. For some applications, you would need additional Compiler
or Linker
flags, especially if you're using libraries that are not currently included by the Linker
. Then you need to update the project by configuring the correct settings with the Project Options dialog. See Build Settings for more information how and where to set Compiler Options, Warnings and Linker
Options.

### External Projects

Existing projects can be converted to KDevelop projects by selecting "New" from the "Project" menu. The dialog creates an empty project file with your project name, version, and type information, as well as your name and email address. Next copy all your compilation and construction files to the new project directory, and choose "Add Files" from the "Project" menu. The files selected will be copied into your project directory and the `Makefile.am
` files are updated.

Be sure to change all `Makefile.am`
entries existing before the conversion, to the newly created entries placed by KDevelop in the KDevelop area.

After this procedure, test that your program can still be compiled and installed after the conversion to ensure the project's consistency.

## Build Settings

The Project Options dialog, accessed by the "Project" menu, lets you specify all needed parameters for your project. These will be used for the `Makefile.am`
files and the `configure
.in` script (e.g. version number change, or compiler warnings
) and will thereby set the compilation preferences as well. After changing the project options, you should invoke "make
clean" or "rebuild all" to compile your project with the new options.

Please note that debugging
is only available if the project options are set to create debugging
information, and the amount can be set with the debug level (0-3).

If you add functions that belong to a library that is not included in the Linker
flags, your program will not link correctly if those are not updated, so keep track of your library linking.

For a release build of your application or for distributing the sourcecode package, you should watch the following standard settings:

- disable debugging

- enable optimization and set optimization level to `-02`

- set the compiler warnings
  to `-Wall`

- for each new release, increase the version number and update the `project.lsm` file for version and requirements.

### General Options

The first page of the Project Options dialog sets the general options for your project. These are project name and number, the handbook sgml file which is used for generating a set of HTML
files that are included in the project, and specific information about the author. The short description field is for additional information that you want to include such as the program's purpose and the like.

### Compiler Options

The compiler options
page sets the compiler flags for your target, debugging
and additional options as described below.

#### Target

The target box contains two options that can be set:

Target Machine

  You have the choice to set the target machine option here, by choosing between your machine (default), and i386v, which is the option if you configure
  d your Compiler
  as a cross-compiler for an Intel 386 compatible machine running System V. This option sets the `-b` flag for the Compiler
  . Usually you would leave this to the default.

Optimize

  You can enable optimization for your build process by this option, by setting the `-O` flag. If not checked, the flag is set to `-O0`, so no optimization will be used. If you enable optimization by checking this option, you can also specify the optimization level below to a value between 1 and 3.

  For a release version of your application, enable optimization and set the level to 2.

#### Debugging

Right of the Target box, you can see the debugging
-section. This means that you can set your Compiler
to include information for debuggers within the final binary, so the programmer can follow the execution of the application with the debugger in direct context of the sourcecode.

Enable debugging

  Sets the `-g` flag; the debugging
  level specifies the amount of information to be included in the binary. Available are levels 1 to 3 to choose from. Mind that the binary execution will be slower by setting any debugging
  option, and that the binary size will increase by the debugging
  level.

Generate extra information for gprof

  Sets the `-pg` flag, causing the Compiler
  to include information for the gprof program that displays caller graphs of your program's function.

Store temporary intermediate files

  Sets the `-save-temps` flag. This will result in storing the (usually temporary) files produced by the preprocessor and the assembler. A compilation of a sourcefile will therefore produce three output
  files: an `*.o` file which is the final output
  of the Compiler
  , an `*.i` file produced by the preprocessor and an `*.s` file as the output
  of the assembler.

For a release of your project, disable any debugging
.

#### Additional Options

The text entry field on the bottom is intended for you to manually set any flags for the Compiler
by setting the `CXXFLAGS` environment variable
in the `Makefile
s`, so that make sets the flags before the build process, and resets them afterwards. For a complete description of all available Compiler
flags you should see your Compiler
documentation; for gcc and egcs this can be done by `man gcc`. `man g++` will show you information about the c++ script that is used to lead the Compiler
.

### Compiler Warnings

The following gives a description about the Compiler
warning options that can be set on page 3 of the project options dialog. The explanations are taken from the man page for GCC, egcs version 1.1.1. The warnings
themselves are diagnostic messages that indicate that constructions may cause errors
.

`-Wall`

  Standard ``-W`' options combined.

`-W`

  Compile with `-W`. This option sets options not included in `-Wall` which are very specific. Please read GCC-Info for more information.

`-Wtraditional`

  Warn about certain constructs that behave differently in traditional and ANSI C.

`-Wundef`

  Warn if an undefined identifier is evaluated in an `&num;if' directive.

`-Wshadow`

  Warn whenever a local variable
  shadows another local variable
  .

`-Wid-clash-LEN`

  Warn whenever two distinct identifiers match in the first len characters. This may help you prepare a program that will compile with certain obsolete, brain-damaged Compilers
  s.

`-Wlarger-then-LEN`

  Warn whenever an object of larger than LEN bytes is defined.

`-Wpointer-arith`

  Warn about anything that depends on the «size of» a function type or of void. GNU C assigns these types a size of 1, for convenience in calculations with `void *` pointers and pointers to functions.

`-Wbad-function-cast`

  Warn whenever a function call is cast to a non-matching type. For example, warn if `int malloc()` is cast to `anything *`.

`-Wcast-equal`

  Warn whenever a pointer is cast so as to remove a type qualifier from the target type. For example, warn if a const `char *` is cast to an ordinary `char *`.

`-Wcast-align`

  Warn whenever a pointer is cast such that the required alignment of the target is increased. For example, warn if a `char *` is cast to an `int *` on machines where integers can only be accessed at two- or four-byte boundaries.

`-Wwrite-strings`

  Give string constants the type `const char[length]` so that copying the address of one into a non-const `char * pointer` will get a warning. These warnings
  will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using const in declaration
  s and prototypes. Otherwise, it will just be a nuisance; this is why we did not make ``-Wall'` request these warnings
  .

`-Wconversion`

  Warn if a prototype causes a type conversion that is different from what would happen to the same argument in the absence of a prototype. This includes conversions of fixed point to floating and vice versa, and conversions changing the width or signedness of a fixed point argument except when the same as the default promotion.

`-Wsign-compare`

  Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned.

`-Waggregate-return`

  Warn if any functions that return structures or unions are defined or called. (In languages where you can return an array, this also elicits a warning.)

`-Wmissing-prototypes`

  Warn if a global function is defined without a previous prototype declaration
  . This warning is issued even if the definition itself provides a prototype. The aim is to detect global functions that fail to be declared in header files.

`-Wmissing-declaration`
s

  Warn if a global function is defined without a previous declaration
  . Do so even if the definition itself provides a prototype. Use this option to detect global functions that are not declared in header files.

`-Wredundant-decls`

  Warn if anything is declared more than once in the same scope, even in cases where multiple declaration
  is valid and changes nothing.

`-Wredundant-decls`

  Warn if anything is declared more than once in the same scope, even in cases where multiple declaration
  is valid and changes nothing.

`-Wnested-externs`

  Warn if an extern declaration
  is encountered within an function.

`-Winline`

  Warn if a function can not be inlined, and either it was declared as inline, or else the -fin*line-functions option was given.

`-Wold-style-cast`

  Warn if an old-style (C-style) cast is used within a program

`-Woverloaded-virtual`

  (C++ only.) In a derived class, the definitions of virtual functions must match the type signature of a virtual function declared in the base class. Use this option to request warnings
  when a derived class declares a function that may be an erroneous attempt to define a virtual function: that is, warn when a function with the same name as a virtual function in the base class, but with a type signature that doesn't match any virtual functions from the base class.

`-Wsynth`

  Warn when g++'s synthesis behavior does not match that of cfront.

`-Werror`

  Make all warnings
  into errors
  . Treat warnings
  as errors
  ; abort compilation after any warning.

For a release of your project, it is recommended to enable `-Wall`.

### Linker
Options

The Linker
Options for your current project can be set on the last page of the project options dialog. You have to enable those libraries that your application uses, to link them to your binary with the Linker
, e.g. your application uses the class
`KFileDialog`. As the class
`KFileDialog` is part of the KFile library, you have to enable kfile. For classes
or functions that are not listed as checkboxes, use the "additional libraries" field.

#### Linker
Flags

remove all symbol table and relocation information from the executable:

  This means that all redundant information will be removed from the object files and the binary, and that debugging
  will not be possible. For as long as your application is in a development stage, and not released as final, you should leave this option disabled.

prevent using shared libraries:

  This option disables the use of shared libraries on systems that support this. On systems using no shared libraries, this option will have no effect.

additional flags:

  Here, you can enter additional flags for the Linker
  , setting the `LDFLAGS` environment variable
  used by make
  . The available options can be taken from the man page for `ld` or your Compiler
  man page.

#### Libraries

The libraries section contains checkboxes for the most needed libraries in conjuction with Qt/KDE
application development. You have to enable those libraries that your application uses, otherwise the Linker
will complain about unresolved symbol tables.

X11

  The X11 library. Recommended for all X-Window programs.

Xext

  The X11 extension library. Also most X-Window programs depend on Xext.

qt

  The Qt-library
  . Recommended for Qt and KDE
  applications.

kdecore

  The KDE Core library; contains the classes
  for KDE Application frameworks.

kdeui

  The KDE User Interface library; contains KDE-specific widgets
  .

khtmlw

  The KHTML Widget library.

kfm

  The KFM library containing classes
  for KFM functions.

kfile

  The KFile library. Contains file dialogs etc.

kspell

  The KSpell library. Contains an interface for programs to use Ispell for spell-checking.

kab

  The KAdressBook library. Needed for access to the addressbook as well as providing addressbook widgets

additional libraries:

  Here you can enter additional libraries that your application needs, e.g. the KOM library. Set the libraries with the `-l` option; for the example `-lkom`.

### Make
Options

As GNU make
supports some useful options, the Project Options dialog contains a page called "Make-Options", where those can be en/disabled.

The available settings are:

Print debug information

  prints out all information about the project files
  and what make
  determines for rebuilding them.

Continue after errors

  tries to continue with the compilation after an error occurred (e.g. a file couldn't be compiled due to an error)

Print the data base

  prints out the make
  database for the current process, which contains the changes from the last build-run.

Environment variables

  give the current environment variables a higher priority than the currently used variables in the `Makefile
  `.

No built-in rules

  doesn't use built-in rules for make
  .

Touch files

  don't run the Compiler
  on changed files; instead only touches them. This sets them as already processed by make
  .

Ignore all errors

  Ignores all errors
  that occur

Silent operation

  doesn't print out any information about the build-process

Print working directory

  prints the current directory during the make
  process.

job number

  sets the amount of parallel processes for make
  . For a single-CPU system we recommend setting this to one or two.

set modified

  sets the selected file modified. Choose the file by clicking the folder button on the right. Setting a file modified means that the file will be processed by make
  and compiled if it is a source file.

additional options

  set additional options to make
  ; those can be found in your local man page for "GNU Make".

Rebuild behavior on run

  Sets the actions taken when you choose run. There are three options you can choose from:

  Always rebuild

    Always rebuild, without checking for modified files

  Warning on modification

    Warn if source files have been modified, and ask if the project should be rebuilt

  Only on modification

    Check if sources have changed, and rebuild if they have

  The default is to rebuild always.

## The Class Browser

### The Classviewer

The KDevelop Classviewer is one of the most useful and important tools that the IDE provides a developer for managing his project sources. When a project is loaded, a class parser reads all project sources for functions, classes
etc., then displays the results in the CV
treeview. This chapter shows you how to use the Classviewer and the provided functionality, and how it can improve your work.

Classes and their methods can also be accessed by the browser toolbar. There, the left combobox selects the class and the right lets you choose the methods of the selected class. When you select a method, the classbrowser will automatically bring you to the implementation
file, and sets the cursor to the method. Finally, the class-assistant button on the right of the method combo, will bring you to the declaration
of the method on one click and on a second click to the definition. The delayed popup menu, displayed by the down-arrow on the button, offers additional functionality that is also available in the classviewer's context menus, such as:

Goto Declaration

  browses to the declaration
  of the method

Goto Definition

  browses to the definition of the method

Goto Class Declaration

  Goto Class Declaration: browses to the class declaration

New Class

  Opens the New Class
  dialog to construct a new class

Add Method

  Adds a method to the selected class

Add Attribute

  Adds an attribute to the selected class

Show graphical classview

  Show graphical classview: Opens the graphical inheritance tree

#### Available Objects

C++ code can be seen as a collection of objects: classes
, their members, global functions, and more. The classtree displays these objects logically, and orders them by character, so they are easy to locate in the tree, as well by their icon.

The classtree contains a "Classes" and a "Globals" folder.

The "Classes" folder generally contains the project's classes
. If your project contains subfolders to manage your sourcefiles, these are also displayed by their original folder name and contain all classes
that are stored in the files located in the subfolder.

When popping up a class, the classtree displays the class contents by separating methods and attributes
. As these can have attributes
such as public, private, and protected, these are displayed by modified icons. You will see that a class displayed in the Class Browser contains all the objects that are present in the class declaration
.

Classes
are a very common thing when programming in C++ and will contain most of the code. But applications also contain objects that have a "Global" appearance to the program. These would be structs, functions etc. Especially the `main()` function, which appears in every application, and you sometimes need to modify it in one or another.

To access these objects, the Classviewer provides the "Globals" folder, containing sub-folders for the following object types:

- Structs

- Functions

- Variables

As the icons displaying these items are similar to those used in the class-viewer, their meaning is easy to guess, and to remember.

Finally, it can be said that the classviewer
displays your project graphically by their objects, related to their appearance in the code.

In the following section you will learn how to use the classviewer
and it's tools, in conjunction with your code.

#### Browsing Object Declarations and Implementations

The Classviewer's strength is providing a fast and easy access to his code and the code's contents, independent of the location within files. Selections by a mouse click will result in the following actions:

On a classname

  Switches to the class declaration

On a class method

  Switches to the method implementation

On a class attribute

  Switches to the attribute's declaration
  in the class declaration

On a struct

  Switches to the struct's declaration

On a global function

  Switches to the function's implementation

This provides you the most direct access to code objects.

Sometimes, it may be needed to change a method's header, with the result that you have to change it's declaration
in the class, as well as the implementation
. The classviewer
supports this by providing right button context menus over items.

On a method or function, this means that you can select where to go:

Go to definition

  Switches to the implementation
  - this is the default for a left click as described above

Go to declaration

  Switches to the declaration
  of the method or function.

By this behavior, the Class Browser offers you access to every place you need to go for coding your C++ application.

The following sections give you a description of the other tools that the Class Browser offers. You will find them very useful when working with large projects, as they enhance working object-oriented on C++ programs.

### The Classtools

The classtools are dialogs that makes it even easier for the developer to get more information about his project's classes
.

The classviewer
displays all objects by their occurrence in the code, but you sometimes want to get more information about classes
without having to look inside the code. Therefore, the classtool dialogs are specialized on displaying specific class attributes
.

The classtool dialog is invoked by the popup menu over a class in the classviewer
. Select "Classtool", and the dialog will appear. To get information about a class, select the class in the combo box on top. Then the buttons in the toolbar provide functions that give you specific trees for your class. These are:

Parents:

  The parents of the selected class, which means the class it inherits. This is useful for multiple inheritance, as well as to see why a class behaves in one or the other way. For example, for a dialog, your parent class could be `
  QWidget` or `
  QDialog`.

Children:

  Displays the child classes
  that inherit the current class.

Clients:

  Classes that make use of the selected class through an attribute in their class declaration

Suppliers:

  The suppliers that give attributes
  to the selected class.

Attributes:

  The attributes
  of the class by their name

Methods:

  The Methods of the selected class

Further, the selection of the attribute public, protected, private, or all, shows Attributes, Methods and Virtual Methods by their attribute value.

### Managing Classes

The Class Browser also allows adding methods and attributes
directly by dialogs. This means you don't have to type the classdeclaration
and the implementation
header yourself. After adding a method, you only have to set the formal parameters to the implementation
header, and, if the method requires an attribute, to the declaration
.

#### How to add a method to a class

1. select the class you want to add a method

2. press the right mouse button; the popup menu appears

3. select "Add member function".

4. the "Add member function" dialog appears.

5. insert the type, declaration
   and documentation for the method

6. specify the access and the modifiers for the method

7. press OK to exit the dialog

To add a variable
, is the same procedure, just select "Add member variable
" in the popup menu.

The difference between the actions of these dialogs, is that the adding of a variable
will add the variable
to the classdeclaration
, while the adding of a method will instead add the method's declaration
and the method's implementation
header to the sources.

As the classviewer
directly updates itself, you have immediate access to the new method implementation
, so you only have to fill out the code for the actual purpose of the method.

## The Dialog Editor

The KDevelop integrated dialog editor
allows the easy construction of the widgets
and dialogs your application uses, all by graphical means.

You see the direct appearance of your dialog as it will be presented to the user. Using the dialog editor
is usually the first step you would take after creating a new project with the kappwiz;
. Here you can create your main view, the user interaction dialogs and, after finishing the graphical work, the code generation. This way, your project will contain all the usually considered "difficult" parts that normally would take a long time to implement. Then, the "rest" of your work is implementing the functionality in the generated code.

This chapter deals with how to use the dialog editor
to create your project widgets
, as well as what to do in case you see your widgets
need corrections or additions during the further development process.

You can switch to the dialog editor
either by selecting "Dialog Editor" from the "View
" menu or by the corresponding toolbar icon.

To switch back to the Project Editor, select "KDevelop" from the dialog editor
's "View
" menu, or the icon in the toolbar.

What else does the dialog editor
's interface offer you? Mainly, that its appearance is almost the same as the project editor, in term of the main view separation as well as the menu and toolbars. This allows you to get accustomed to the dialog editor
very quickly, and, as it completely interacts with the project management, stay in the dialog editor
if you want to control your build-process. Actions that require to switch back to KDevelop will do that automatically for you, for example, accessing the documentation browser. Just select the menu commands, and KDevelop reacts to your will.

The following sections give you an overview of the dialog editor
interface, how to create a new dialog initially and how set up the properties of the child widgets
that your dialog contains.

### The Dialog Editor View

#### The Mainview

The dialog editor
's view is logically separated by:

- The Widgets Tab, containing the "Widgets", "Dialogs" and "Items" tabs. These are described in Adding Widgets.

- The Widget-Editor, representing the editing view for creating your dialog. See The Widget Editor

- The Properties window, containing a list of properties and their values, dependent on the currently selected widget in the widget editor. See Setting Properties for information how to specialize the widget's behavior and look.

#### Menubar
, Toolbar
and Statusbar
differences to KDevelop

In Dialogeditor mode, KDevelop changes the menubar, toolbar and statusbar slightly, to provide the functionality you need for creating widgets
.

The differences are:

##### Menubar

"File" Menu

  "Open" allows you to open a dialog definition file.

"View" Menu

  replaces "Tree-View" with "Widgets-View", en/disabling the Widgets-View tabs; adds "Properties-View" to en/disable the Properties-View and "Grid Size" to let you specify the grid size in pixels for horizontal and vertical values.

"Build" Menu

  replaces "Compile File
  " with "Generate Sources". This lets you actually generate the sources for yourdialog.

##### Toolbar

The toolbar contains a new icon for "New Dialog" as well as the replacement of "Compile File
" with "Generate Sources".

##### Statusbar

The statusbar now provides information about the currently selected widget, especially displaying the values for X and Y size in the coordinate system. For Statusbar
help, you are provided the same functionality as in Project-editing mode.

While changing widget size, the statusbar shows the current values for width and height of the selected widget.

### Creating a New Dialog

After creating your project skeleton, you are provided a ready-to-run application, according to your preferences. As KDevelop provides the project types KDE, and Qt application, the dialog editor
recognizes this and offers widget construction by the widgets
that are provided in the used libraries. To save time, you already should have a design in mind for the intended actions. For information about widget design, see The KDevelop Programming Handbook.

To create a new dialog, select "New" from the "File" menu
or select "New" from the context menu in the "Dialogs" tab. The New File Dialog appears where you can select the item Qt/KDE Dialog(`*.kdevdlg`). Enter the file name for your dialog to save the layout to. Then press OK and a new dialog will appear. When finished with the new dialog, select "Generate Complete Sources" from the "Build" Menu. The dialog to generate the widget´s source file will appear. There you have to give KDevelop the dialog-specific information about the base class, the source file names and destination.

#### Dialog Class

The dialog class you can select, is the class that is inherited by your new widget, which is technically represented by a class itself.

Therefore, you have the following options:

`QWidget`

  the base class for all user interaction widgets
  provided by Qt. Used for main views and top-level widgets
  .

`QFrame`

  inherits
  `QWidget` and is used by numerous widgets
  as a base class. This is useful for widgets
  that want to have a `
  QFrame` functionality in addition to `
  QWidget` methods.

Custom

  inherits a custom class that has to be set in the "Custom Properties". This could be an already designed class provided by your project or the libraries.

`QDialog`

  the base class for dialogs that you would inherit for user interaction like setting properties or changing values.

`QTabDialog`

  inherits
  `QDialog` and provides a dialog with predefined buttons and a set of tabs, which you will provide by the widgets
  that you create.

Custom Properties

  For the inheritance of a custom class as selected in the dialog class field, you have to specify the classname, which goes to "Custom Class". The dialog editor
  uses this for the code-generation; therefore, you also have to insert the "Custom Header", where the header filename of the custom class has to be set.

#### Files

In the "Files" section, you have to enter the widget's specific information. This is the classname (which would be e.g. `KColorSelectDlg` for a dialog that allows selecting the color of a pen), the header, C++, and Data filenames. When inserting the Classname, the filenames are given by the dialog editor
, but you can change the filenames.

Now, what about the files? When you are ready with constructing the widget visually, you will have to generate the files that contain the implementation
for your widget. As this will be a class, the dialog will exist by the header file containing the classdeclaration
, and a C++ file containing the method implementation
for your widget's methods and slots. The Data file is the file that will contain a function that is called by the constructor of your widget, the `initDialog()` method. This file itself shouldn't be changed as it will contain the generated code from the dialog editor
to create the widget on the screen.

If you ever have to change values, you should do this by the constructor, or be sure that you won't change the dialog during the development process, as the Data file will be overwritten each time the code is generated for your widget. The header and C++ file contain sections, where the dialog editor
writes and these are marked by comments. After file generation, you can change any values and settings, but only outside these sections, otherwise your changes will get lost by the next code-creation.

#### Location

For generating the widget's sources, the dialog editor
needs to know the location these will go. The default value for the output
directory is the current project subdirectory containing the sources, already present.

After pressing "OK", your default values are generated and an empty Widget constructor is opened. Then you are ready to go for creating your own widget. Mind that the dialog editor
currently only supports static widgets
without geometry management. If you're about to use geometry management for your widgets
, you should make yourself accustomed with the classes
that Qt provides for this, create a new class with the classgenerator, and write your widget by hand. For more information, see The KDevelop Programming Handbook.

### Adding Widgets

After specifying the dialogs or widgets
class and filenames, you are ready to start creating the widget and filling it with contents.

Adding low-level widgets
to your dialog is a very easy task. Just select the widget you want to add from the "Widgets" tab on the left by a single click on the according widget icon. The widget will then be laid on the left upper corner of the currently opened main widget.

An added widget then gets the default size of 100x30 pixels on the editor
view. To move a widget, click over it to activate the drawing frame, which is displayed in dark grey with hot spots on the corners and on the center of each of the top, bottom, left and right sides of the widget. A cross-cursor indicates that the widget can be moved. To move it, press the left mouse button and keep it pressed. then move the widget with your mouse to the place you want to have it displayed later.

To resize a widget, move your mouse cursor over one of the hot spots of the already activated item. The mouse cursor then changes to a double-arrow indicating the directions, in which resizing can be done. Press the left mouse button and hold it pressed. The widget item will change it's size when the mouse is moved to the direction indicated by the cursor.

Further, the widget editor contains a lot of context menus to help you coordinate your work. Those are available over all items in the widgets
tab and give you a quick help message window that shows the class name of the selected widget with a short description.

Over a selected widget, the context menu shows the class name of the selected item and offers:

- Raise

- Lower

- Raise to top

- Lower to bottom

- Cut

- Delete

- Copy

- Paste

- Help

After setting the size and position, you can edit the preferences for the selected item on the Preferences window.

#### The Widgets Tab

The widgets
tab represents the available widgets
you can place on the dialog. If you want information about a certain widget, press the right mouse button over a widget icon and select "Quick-Help" from the popup-menu. Mind that the dialog editor
automatically determines, if your project type is Qt-only or KDE. This prevents you from using KDE-widgets
in a Qt only application.

After you selected a widget item, it is placed with default sizes and values on the editing window and marked selected by a frame and darkened corners. To resize a widget, move your mouse over one of the dark spots and your cursor will change to display which resizing directions are possible. Then press the mousebutton and move the mouse while holding it. When you're finished with resizing the widget, release the mouse. While resizing, the statusbar displays the current position of the item by X and Y values and the current size by W(Width) and H(Height) values.

#### The Dialogs Tab

The dialogs tab is intended to let you open your project's dialogs by a mouseclick. As the dialog's structure is saved in a `*.kdevdlg` file within the directory that contains the generated files, only those dialog definition files are shown. Mind that you don't delete these definition files.

On selecting a dialog, it will be shown as by the state it was saved in the last editing step in the Widget-Editor view.

#### The Items Tab

The Items tab lets you have a hierarchal overview over the currently present widget items of the dialog. This means, that, as your background represents the parent of all widgets
within the dialog, it is shown on top of the tree. The children of the main dialog are then listed in the next tree-level.

On selecting an item, it gets marked in the editor view, and the properties are shown in the properties window. Using the items view is sometimes important if your widgets
behavior depends on the parent-child relationship.

### The Widget Editor

The Widget Editor is the main view that is placed in the middle, and is where you construct your widget. After adding items, they can be selected and resized, as well as moved to the place you need them. On all items, popup menus provide a quick access to functions like cut, copy and insert.

### Setting Properties

The properties window on the right is the place where you set the default behavior for the widget and its items. It displays the pre-set values for each selected item right away; changing values will result in direct changes on the Widget Editor view, e.g. naming labels or buttons.

To separate certain property values by their effect, the properties window contains four folders; selecting a folder will pop up all values for the properties group. All possible values are described below. Mind that the properties are dependent on the widget, e.g. a label and button will have a property for their on-screen name, while lineedits will have properties for methods like `setText()`.

For a complete list of the available values per item, you should see the class-reference of the widget which explains the used methods and all possible values. Note that most values are implemented in `
QWidget` and are used for all widgets
that inherit
`QWidget`. Also mind that the final code does not contain any method calls that are unchanged by the user, and therefore use the default values as given in the widget's constructors.

### Generating Files

After creating a widget, you have to generate the sourcecode to make it available in your project. This can be done either with the "Generate Sources" from the "Build" menu or by the corresponding icon in the dialog editor
toolbar. Your `Makefile
` files will be updated automatically to include the new widget in the compiling process; therefore, after calling "Generate Sources", you can build your project again within the dialog editor
. The output
window pops up below the Widget-Editor window, as in Project Editor mode.

Now that your project contains a new widget, your work as a programmer is to implement functionality to the used slots and eventually add other methods you may need. See The KDevelop Programming Handbook, The Dialogeditor for more information about widget properties and sourcecode generation.

## The Internal Debugger

### Setup

The default setup for KDevelop is to use the internal debugger. You can change this under "Options" selected from the "KDevelop setup" menu item, and then the Debugger tab.

Click on "Use external debugger" if you wish to use a different debugger and enter the name of the debugger to use. See your debuggers documentation on how to run it.

Selecting the internal debugger enables an additional set of options you can choose from:

Display static members

  Displaying static members makes gdb slower in producing data within kde and qt. It may change the "signature" of the data which `QString` and friends rely on. If you need to debug into these values, then check this option.

Display mangled names

  When displaying the disassembled code you can select to see the methods mangled names. However, non-mangled names are easier to read.

Try setting BPs on lib load

  Try setting BPs on lib load: This will try to set pending breakpoints on loading a library. If gdb hasn't seen a library that will be loaded via "dlopen" then it will refuse to set a breakpoint in that code. We can get gdb to stop on a library load and hence try to set the pending breakpoints. See Shared libraries and breakpoints for more details and a "gotcha" relating to this behaviour. If you are not "dlopen"ing libs, leave this off.

Enable floating toolbar

  Enable floating toolbar: This will allow you to use the floating toolbar to control the debugger in addition to the menu and buttons. The toolbar is most useful for debugging GUI applications. For details see The floating toolbar.

Enable separate terminal for application I/O

  This allows you to enter terminal input when your application contains terminal input code (e.g. cin, fgets etc.). If you use terminal input in your app, then tick this option. Otherwise leave this off.

  Tip: This option is most useful if you use it in combination with the floating toolbar, because this way, the terminal window won't be hidden behind the KDevelop window when you control the debugger.

### Using the internal debugger

#### Changes made in the tree and output view window

If you choose the internal debugger, four tabs are added to your tree and output view windows.

##### On the tree view window

VAR tab

  A tree view of the local variables at the current place in the program you have stopped at. You can also see local variables in the function that called this functions. The VAR tab also contains a watch window. This allows you to see the value of global variables, or perhaps you may want to see only one local variable rather than the variable in a large list of local variables.

##### On the output view window

breakpoint

  A list of breakpoints set, and their current state

framestack

  The calling stack

disassemble

  A machine instruction view of the code, showing the current instruction to be executed

#### Changes made in the Debug menu and on the panel

##### On the panel

Two normal and two dropdown buttons to control the debugger functions will be accessible as soon as you start the debugger.

##### In the Debug menu

When you start debugging, ten items to control the debugger will be enabled.

Available functions:

Debug Run

  Continue the program from the current point

Debug Run to cursor

  Execute the program up to the current cursor position

Debug Step over

  Execute one line of code, stopping in the next line of code in the same source file. This will run any functions encountered until the above condition is met

Debug Step over i(nstruction)

  Execute one machine instruction, as above

Debug Step in

  Execute exactly one line of source code. This means you will "step into" the current function, if necessary

Debug Step in i(nstruction)

  Execute one machine instruction as above

Debug Step out

  Run to the end of the current stack frame (function)

Debug Viewers

  Allows a variety of views into the data.

  Currently implemented views are:

  - Memory address

  - Disassemble code

  - Current registers

  - Current libraries

Debug Interrupt

  Stop the application executing

Debug Stop

  Stop the application executing, and exit the debugger

#### Details

##### Breakpoints

Breakpoints can be set against source lines in a file (referred to as breakpoints) or on variables in the source (referred to as watchpoints). Both types of breakpoints can be set at anytime, however watchpoints on local variables only have meaning in the variables local scope. Watchpoints have more meaning when you are dealing with global variables.

##### Set/Unset breakpoints

Simple one click set/unset. Click on the "icon" border to the left of the text in the editor at the line you want the breakpoint. Click again on this line to unset the breakpoint.

##### Alternative beakpoint manipulating via menus

By right clicking on a breakpoint in the breakpoint list or on a breakpoint in the editors icon border you will get a menu of breakpoint options. This allows you to remove this breakpoint, clear all breakpoints, or edit the breakpoint.

##### Editing breakpoints

Use the above menu to display the edit breakpoint dialog. This contains the following fields :

Conditional

  Enter the condition that must be met before gdb will interrupt the program execution

Ignore count

  How many times you want the code to pass through this breakpoint before gdb interrupts the program execution

Enable

  When enabled, gdb will break at this breakpoint. When disabled gdb will not break here

##### Clear all breakpoints

Removes all the breakpoints for this program.

##### Set/Unset watchpoints

In the VAR view click with the Right Mouse button on a variable. A popup menu will be displayed allowing you to set a watchpoint on the local variable. This functionality is limited to the scope that the local variable is in. As the variable goes out of scope, the program breaks, and the watchpoint is deleted.

WARNING: This is known to be problematic, so use caution when setting watchpoints on local variables.

The watchpoint can also be set by a right mouse click on a previously entered watch variable, and selecting "toggle watchpoint"

##### Set/Unset Watch variables

At the bottom of the VAR view there is the "Watch" field where you can enter the variable name you wish to see display in the watch list. Enter the variable name and type `enter` or click on the "Add" button alongside the field. Right Mouse clicking on the watch variable in the treeview will bring up a menu so that you can remove the variable from the list.

You can also enter a watch variable by right mouse clicking on a variable name in the editor window. This displays a popup menu with "watch: variable name" on it.

##### Changing variable values

This is done via the watch variable. If you have a variable `"test"` then to set `"test"` to 5, type `"test=5"` in the watch field and add it to the list. Note that `"test"` will be set to "5" every time the program stops at a breakpoint, so once you have set the variable, usually you should remove the item from the watch view.

### The floating toolbar

The floating toolbar is a feature of the internal debugger, which greatly improves your comfort in debugging GUI applications. The toolbar is either on top of all windows displayed, or docked into the panel. When docked you can run your code by clicking on the docked icon. The function this performs is the "step over" function. Right clicking on the docked item allows you to restore the toolbar and optionally place focus on Kdevelop.

Besides the functions available from the Debug Menu, the floating toolbar offers two additional functions:

Set focus on KDevelop

  Set the focus on KDevelop

Set focus on app

  Set focus on app : This sets the focus on the window that had focus when you pressed the "set focus on KDevelop" button. This is a compromise, it should set the focus on the application being debugged, but this is difficult to do. If anyone has a better solution than the current functionality then please let us know.

When gdb interrupts the program, probably because a breakpoint has been triggered, we highlight the "Set focus on KDevelop". We do not automatically switch focus to KDevelop so that you can view the application window at this point. Click on the "set focus" button to switch to KDevelop or press a button on the toolbar to perform your selected function.

### Shared libraries and breakpoints

Shared libraries and breakpoints have a problem but that problem has a reasonable solution. The problem is that gdb will not accept breakpoints in source that is in a shared library which has not yet been opened, but will be opened via a dlopen.

The solution is to get gdb to tell us when a shared library has been opened. We do so by setting "stop-on 1". This means that when the user sets a breakpoint, we flag this breakpoint as pending, try to set the breakpoint and if gdb says it succeeded then flag it as active. If gdb is not successful then we leave the breakpoint as pending. The next instruction will always be "continue" .

This is known as "lazy breakpoints"

However, this can lead to a problem when you use the "step over" command and step over code that will load a library. This will trigger a break on the library load, and, normally the debugger would do a "continue" (i.e. run to the next breakpoint or the end of the code). The user, however, is expecting the program to stop at the next line, so in this situation we do not continue, but leave it at that point (which will be somewhere inside a dlopen command). This is disconcerting but cannot be helped.

## CVS Integration

KDevelop also takes care of managing your project via CVS repositories. The goal behind CVS (concurrent version control) is to enable groups of developers to work on the same source-tree independently and to merge changes into the repository.

Usually, the repository is located on a server. The initial repository contains the base set of files that the project includes; directories and files are then added or removed to the CVS by the developers. Locally, the developer works on his own copy of the CVS tree. He writes his changes into his local files and tests if his project still works, at least to the extent where incomplete sources don't prevent other developers from still working on the CVS repository if they receive the changes.

### Creating a Repository

When creating a new project with KDevelop, you can directly import the project as a CVS module. To enable this, you have to have CVS installed (which should be already, if not, revise your system installation or contact your system administrator).

On the third page of the kappwiz; (VCS support), choose "CVS". Then the editing fields of this page become active and you can specify the import parameters, see below for the given options. The kappwiz; will then import the project source tree as a module into the CVS root directory and create your new project as a local copy of the CVS source tree that you will be working on.

Attention: to create an initial repository, you have to have write access to the CVS root directory! Also the CVS root directory has to be on the same machine where you´re running KDevelop at the time of it's creation! If you want to have the repository on a dedicated CVS server either contact this servers´ system administrator to create the project with KDevelop on the server machine or do the following steps:

1. create your project locally

2. import the project source tree as a module on the CVS server

3. delete local project source tree

4. check out the project source tree from CVS

5. enable CVS support in the project options dialog as described below after loading the project file of your CVS copy you checked out.

For more details on CVS commands, please revise your system help on cvs, e.g. by doing a `man cvs`.

In the following we will discuss the options when creating a repository with the kappwiz;

VCS Location:

  This is the CVS root directory where the project source tree will be imported and where commits, checkouts and updates take place.

Repository in CVS

  This is the module name given for your project. As this is the same as your project directory you can´t change that.

Vendor Tag

  this is a tag for the entire branch

Log Message

  is the first log message entry of the new module. When adding or commiting to the repository, you will be asked for a log message each time to document your changes to the repository source tree.

Release Tag

  this specifies the tag under which your project source tree can be found, meaning that you can create several projects with the same module name in the CVS root which differ in the tag, so you can work on different branches of the same project. Example: KDE 2 is developed under the tag HEAD (default tag), KDE 1.1.2. can be found in the tag KDE_1_1_2_RELEASE.

After creating your project with the kappwiz;, the CVS support option is already set for your project, so you can commit and add changes in the way described below in the section "Using CVS Commands".

### Enabling CVS Support

As CVS support is most often only needed by professionals or companies as well as by KDE developers maintaining their project over the KDE CVS server, using the CVS commands of KDevelop is optional. To enable the CVS commands, open the Project-Options dialog and change the option for Version Control to "CVS".

### Using CVS Commands

The following commands are available in the LFV and RFV through context menus:

Over a file not included in the repository:

Add to Repository

  Adds the file to the repository. The file is set up to be added and will be introduced to the repository on the next `commit` command that includes the directory where the added file is located locally.

Over a file included in the repository:

Update

  Update the selected file with the CVS version

Commit

  Commit the selected file to the CVS repository

Remove from Repository

  Remove the file from the repository

Over a folder:

Add

  Adds the folder to the repository

Remove

  removes the folder from the repository

Update

  Update the folder recursively to be in sync with the repository

Commit

  Commit any changes recursively to the repository

The CVS commands all require a working network connection to the CVS server. When invoking a command, you will be shown a dialog with the command sent to the CVS server and the retrieved output. Thereby you can control what actually happens and if the command was successful or not.

As the CVS commands of KDevelop only work with the `cvs` system command and its commandline options, you should have no trouble to use the CVS features.

## General Configuration

This chapter describes how you can set your individual preferences about how KDevelop works. All settings addressed below can be found by the according entry in the "Options" menu.

### Configuring the "Tools" Menu

As KDevelop supports the use of third-party programs within it's user interface, you are able to configure
any program that suits your application development needs. This can be done by adding programs to the pre-defined ones in the "Tools" menu
.

To change the "Tools" menu, select "Tools
" from the "Options" menu. This dialog allows you to specify the entry name, program, and any additional command line options you want to pass on execution.

To add a program, specify the menu entry, where an ampersand (&) is used as a menu-accelerator; you may compare with the already configured entries with the entry list. Select the binary and pass your commandline options. Then hit "Add" and the entry is added to the list.

To remove a program from the menu, select the entry name, and choose "Delete".

After leaving the configuration dialog
, the "Tools" menu updates itself, so the new configuration is already usable without restarting KDevelop.

### File Viewer Options

The Logical File Viewer can be configured by context menus completely. As it's intention is to separate files logically, to give a better overview over complex projects, one of the most used configurations is to create file groups. These can be set by opening the context menu with a right mouse button click over the project icon displayed at the root of the tree. The menu offers:

New File

  Opens the New File
  dialog.Equal to the menubar command File New

New Class

  Opens the Classgenerator to create a new class.>Equals to the menubar command Project New Class

New Group

  Opens a dialog to create a new group. There, set the group name and the file filter for the project files
  that will be displayed in this group.

Show relative path

  Displays the files with their path name starting from the main project directory if checked; otherwise only the filename is shown.

Over a group folder, the according context menu offers:

New Group

  Opens the New Group dialog as in the context menu described above.

Remove Group

  removes the group from the LFV
  .

Properties

  Opens the properties of the group. There, you can edit the file filters as a list of wildcards, separated by commas.

### KDevelop Setup

Make-command
:

  The General Options dialog lets you configure KDevelop's general settings. First, you should set the make-command
  to that available on your system (generally `make` or `gmake`.) If the selected program does not exist, KDevelop will warn you the next time you invoke a `make` command.

Autosave
:

  If Autosave is checked, KDevelop will save all changed files periodically. The autosaving time range can be set to 3, 5, 15, or 30 minutes.

Autoswitch
:

  If Autoswitch is enabled, the KDevelop windows will switch on and off according to the usage context, e.g. if you switch to documentation in the "Help" menu, the Documentation browser will be opened, together with the documentation tree, and the output
  window will be turned off.

Startup
:

  For starting KDevelop, you have the option to enable/disable the start-logo
  , normally shown during the time KDevelop is loading. Further, if you don't like the last project to be opened on startup, you can disable this default behavior.

### Changing Keyboard Shortcuts

The Configure Keys dialog lets you configure the KDevelop key bindings. A key function can be configured by first choosing the menu entry, then the configuration can be changed by checking values like the Alt / Ctrlkeys etc.

Note that global keys can be configured in the KDE Control Center, such as open file and print.

### Documentation

#### Directories

For setting up the documentation browser
to work correctly, KDevelop needs some information about where the HTML
documentation is placed on the system. Therefore, the Documentation Path properties dialog needs the path of the Qt online documentation in HTML
as well as the path to the KDE-Library documentation.

Usually, the Qt-Documentation
is placed in the same directory where Qt is installed; e.g. if Qt resides in `/usr/local/qt`, the path you have to enter is `/usr/local/qt/html`. For the KDE Documentation, you have to set the directory to the root of the documentation, assumed all KDE-Libs documentation resides in the same directory. Both paths can be selected by pressing the appropriate buttons, displaying a path-selection. If your system doesn't contain the documentation for the KDE-libs, you should first enter the next configuration dialog
, Update KDE-Documentation
. This will create the documentation to a path of your choice, and also sets the KDE Library Doc path automatically.

#### Options

##### Update KDE-Documentation

For those users who don't have a recent copy of the KDE-libraries
documentation, especially the documentation for the files installed on the system, the "Update KDE-Documentation"
dialog creates a new one or updates existing documentation. This function requires your system to have KDoc
and qt2kdoc installed, included in the KDE-SDK
package. First you have to set up the path to your recent kdelibs sources, which is not the include-path for KDE! Just enter the path to the sources, like: `/home/rnolden/kdelibs-1.1/`.

Next, you can choose from three different installation modes, as:

Delete old Documentation and install to recent Documentation-path

  this assumes that you already have documentation installed and it is placed in the path the entered in the Documentation Path-dialog. This will delete all documentation and install the newly generated documentation into the same path.

Delete old Documentation and install to new Documentation-path

  this will result in deleting the old documentation as above, but gives you the choice to set up a new documentation path.

Leave old Documentation untouched and install to new Documentation path

  This is recommended for a new generation of the kdelibs documentation for users who didn't have one before, and for those who want to keep the previous documentation for an older kdelibs version.

The "new KDE Libs Documentation path" needs to be set for options 2 and 3 of the installation mode. This is also recommended for users who generate a new documentation from scratch.

After pressing the OK button, KDevelop will create a subdirectory `KDoc
-reference` in the documentation path containing the KDoc
reference files. First, the qt library documentation classes
will be indexed, to connect the Qt documentation with the documentation to be generated for the kdelibs. So it is important that you have set up the Qt documentation path first to ensure that it can be found by qt2kdoc. Finally, the KDE libs will be indexed and the documentation will be built with cross-references, to give browsing the most functionality.

NOTE: When using KDoc 2, you can additionally add a set of documentation for the the libraries in the KDE-Base and KOffice package. To do this, create the KDE-Libs documentation as described above. Then reopen the dialog and choose the path to the `kdoc.rules` file in the kdebase package or the koffice package respectively. For kdebase, this is located in `kdebase/`, in the root directory of the sources, for KOffice in `koffice/lib`. Select option 3 (Leave old Documentation untouched) and leave the output path below that option as it is. This will keep the kdelibs documentation and generate the kdebase-libraries (resp. the koffice-libraries) documentation to the same location, with cross-references to the kdelibs documentation. After generating the documentation the libraries are available in the documentation tree automatically. For further KDE packages coming with additional libraries you should look for the `kdoc.rules` file to generate additional documentation, in the same way as with the KDE-Base and KOffice packages.

##### Create Search Database

The Create Search Database dialog, accessed via the create button, allows the programmer to create a database, used to search for a keyword interactively. To create and use the documentation search function, you must have the program glimpse
4.0 or ht://Dig installed.

Preset are the options to index the given KDE-Library documentation, as well as the Qt Documentation
, assuming the path to the documentation files were set in the "Documentation Path" dialog of the "Options menu. Additionally, the index can include directories the user has set up himself in the "additional directories to index" field.

After setting a path to an additional directory, the "Add" button must be pushed, to set the path. A path, once set, can be removed from the index by selecting the path in the path field, and pushing "Remove". Furthermore, the user is offered three different modes for the index size: tiny, small and medium. The higher the index size, obviously the more the index files will grow. On the other hand, a search in a bigger search-database will be faster and more successful, so we suggest choosing a "medium" size. For help on using the search function, see section Using the Documentation Browser.

##### Create also KDOC-reference of your project

This option allows you to create a cross-reference file for your project when generating the API documentation with KDoc. The cross-reference file will be placed in the references directory, and will make your project available in the documentation tree. If you don´t have write access to the directory containing the reference files, you have to uncheck this option to generate the API documentation without errors.

### Debugger

The default setup for KDevelop is to use the internal debugger. Click on "Use external debugger" if you wish to use a different debugger, and enter the name of the debugger to use. See your debuggers documentation for help on how to run it.

Selecting the internal debugger enables an additional set of options you can choose from:

Display static members

  Displaying static members makes gdb slower in producing data within KDE and Qt. It may change the "signature" of data which `Qstring` and friends rely on. Check this option if you need to debug into these values.

Display mangled names

  When displaying the disassembled code, you can select to see the method's mangled names. Non-mangled names are, however, easier to read.

Try setting BPs on lib load

  This will try to set pending breakpoints on loading a library. If gdb hasn't seen a library that will be loaded via "dlopen" then it will refuse to set a breakpoint in that code. We can get gdb to stop on a library load and hence try to set the pending breakpoints. See Shared libraries and breakpoints for more details, and a "gotcha" relating to this behaviour. If you are not "dlopen"ing libs, leave this off.

Enable floating toolbar

  This will allow you to use the floating toolbar to control the debugger, in addition to the menu and buttons. The toolbar is most useful for debugging GUI applications. For details see The floating toolbar.

Enable separate terminal for application I/O

  This allows you to enter terminal input when your application contains terminal input code (eg cin, fgets etc.). If you use terminal input in your app, then tick this option. Otherwise leave this off.

### Setting Paths

On the paths tab you can enter the paths to your Qt 2.x and KDE 2 installations, as well as where to create new projects.

To learn more about installing Qt 2.x / KDE 2 and configuring KDevelop for Qt 2.x and KDE 2 read the KDE Application Tutorials.

The default location for KDevelop to create new projects, is in the user's home directory. If you want to change this behaviour you can enter the desired location into the default project path field.

## Questions and Answers

This section addresses questions by users that were answered by the KDevelop Team or by their supporters on the KDevelop mailing list during experiences with the current versions of KDevelop, as well as bug reporting in general.

### Bug Reporting

Another innovation of KDevelop is the integrated bug-reporting system via email. If you experience a bug, you have the option to send the KDevelop development team a bug report either by your email client or by the bug-report dialog. All bug-reports are collected on the KDevelop web site and can be reviewed on http://bugs.kde.org//db/pa/lkdevelop.html.

To send bug reports, please use the email address submit@bugs.kde.org. If you want to use KDevelop for direct bug-reporting, choose "Bug Report" from the Help-menu
. You are presented a report dialog that lets you enter all necessary information about the bug you found. After pressing "OK", the dialog's contents are sent automatically to the correct place.

### Where to get Information

I have a question which is not addressed in the FAQ file, nor in the manuals of KDevelop. Where should I turn to?

Send all requests that are regarding KDevelop to the KDevelop mailing list. You can subscribe by sending an email with empty headers, and `"subscribe youremailaddress"` to kdevelop-request@barney.cs.uni-potsdam.de. All questions should go there and will be addressed there as well. If you stick to that, you will get the most help by the developers and all users having the same problems, as well as helping to keep the FAQ up to date.

The KDevelop Homepage
at http://www.kdevelop.org/ also contains a mailing-list
archive that allows you to browse the emails already sent by the subscribers. You should look there first as most problems should have been addressed already by the team or other users.

### Library and System Problems

Wrong JPEG library version: library is 61, caller expects 62

There are 2 possible fixes.

1. When the kdelibs are installed it installs header files for the jpeg libraries, these are version 6.1, however most distributions (Redhat) use version 6.2 libraries. To fix this just remove `jpeglib.h`from `/opt/kde/include`. The pukka include file for version 6.2 should then be picked up. However looking at the error message above it may be the other way round. In any case ensure you only have one version of the header file, the library and that they are consistent.

   It is useful to use the `locate` command to verify that you have the correct version of a library and header files e.g.

       updatedb
       locate libjpeg
       locate jpeglib

2. You must recompiled kdesupport without jpeg library (`./configure
   `--with-libjpeg --with-libgif``).

I get an error message that "AM_PROG_INSTALL is obsolete". What do I do?

If this is what you're seeing:

    make[2]: entering directory `/usr/local/src/kdevelop-0.3/po'
    cd .. && automake --gnu --include-deps po/Makefile
    aclocal.m4: 2709: `AM_PROG_INSTALL' is obsolete; use `AC_PROG_INSTALL'
    make[2]: *** [Makefile.in] Error 1

then the workaround for automake-1.4/automake-2.13 users: Just run `aclocal` manually, then it will compile.

What must I do, if `configure`
said that I need `giflib23`.

Try a newer snap of kdesupport, or maybe you have another giflib installed?

How can I convert a KDevelop 0.2 project to a 0.3 one?

Please change the `AC_OUTPUT` in the `configure
.in` to a oneline version

for example:

old version:

    AC_OUTPUT(Makefile \
    kdevelop/kwrite/Makefile \
    kdevelop/templates/Makefile
    )

new version:

    AC_OUTPUT(Makefile kdevelop/kwrite/Makefile kdevelop/templates/Makefile)

I get the following Linker
errors
when using SuSE Linux with KDE 1.1, what do I have to do to get KDevelop linked ?

    /usr/lib/libqt.so:
    warning: multiple common of `QArrayT<char> type_info node'
    ckdevelop.o: warning: previous common is here
    ckdevelop.o: In function `CKDevelop::slotFileSaveAll(void)':
    ckdevelop.o(.text+0x784): undefined reference to `kdebug(unsigned short,
    unsigned short, char const *,...)'
    ckdevelop.o(.text+0x839): undefined reference to `kdebug(unsigned short,
    unsigned short, char const *,...)'
    ckdevelop.o(.text+0x89d): undefined reference to `kdebug(unsigned short,
    unsigned short, char const *,...)'
    ckdevelop.o: In function `CKDevelop::slotFileSaveAs(void)':
    ckdevelop.o(.text+0xd28): undefined reference to `kdebug(unsigned short,
    unsigned short, char const *,...)'
    ckdevelop.o: In function `CKDevelop::slotFileClose(void)':
    ckdevelop.o(.text+0x1216): undefined reference to `kdebug(unsigned short,
    unsigned short, char const *,...)'
    ckdevelop.o(.text+0x1263): more undefined references to `kdebug(unsigned
    short, unsigned short, char const     *,...)' follow  collect2: ld returned 1
    exit status  make[2]: ***
    [kdevelop] Error 1  make[2]: Leaving directory
    '/home/LinuXDaten/Programme_Updates_Packete/KDE_Updates/Kdevelop_actual_snapshot/kdevelop-0.3/kdevelop'
    make[1]: *** [all-recursive] Error 1  make[1]: Leaving directory
    `/home/LinuXDaten/Programme_Updates_Packete/KDE_Updates/Kdevelop_actual_snapshot/kdevelop-0.3'
    make: *** [all-recursive-am] Error 2

If you have the SuSE rpms of KDE-1.1, you must recompile the kdelibs without the patch commited by SuSE, and reinstall them, or get an updated rpm of the kdelibs from ftp://ftp.suse.com

### Usage Questions

I see the KDevelop does not allow for usage of the delete key (or backspace deleting when text is marked).

Go to Options Editor and make sure that "Delete on Input" is enabled, then backspace and delete will work.

If I add files to my project, will they be automatically included and compiled?

Yes, they are included in the `Makefile.am`
files then, and if you make a "Rebuild All" (`./configure`
updates the `Makefile`
files), your new added files will be included as well.

If I removed a file, I get some weird Linker
messages. What is wrong with my project?

If the removed file is a header file, that is automatically processed by automoc (running the Qt-Meta-Object-Compiler automatically on all headers), your removed header is still present as a moc-generated `*.moc.cpp` file and compiled. Remove the appropriate `*.moc.cpp` file and rebuild the project.

Configure complains about not being able to compile a small KDE application. Examining `config.log` reveals that it can't find the library `libXext`.

Install the package xdevel

I´m developing an application where I need to set `-D` options to the preprocessor. If I add these in KDevelop to my project options, everything is ok, but when I distribute my package, the `-D` options set in KDevelop are not used. What do I have to do to make this work ?

Edit the file `configure.in` in your top level source directory. Here, you have to enter somewhere at the beginning:

    CXXFLAGS=$(CXXFLAGS) " -DYOURDEFINE"
    AC_SUBST(CXXFLAGS)

I´m already running a KDE 2 snapshot and I want to use KDevelop under KDE 2. What is the best way to do this ?

As KDevelop for KDE 2 is currently under development, you should consider using the current stable 1.x release of KDevelop for production usage. Running KDevelop 1.x under KDE 2 can be done by creating a shell-script:

    #/bin/bash
    QTDIR=/usr/lib/qt-1.44 export QTDIR
    KDEDIR=/opt/kde export KDEDIR
    exec /opt/kde/bin/kdevelop

Save this file as e.g. `kdevelop1` and set this file to executable with

`chmod 755 kdevelop1`

Then you can run KDevelop 1.x under KDE 2 by calling `kdevelop1`. For developing KDE 2 applications with KDevelop 1.x you have to set the correct path in the KDevelop Setup even if you´re running KDevelop under KDE 2.

## Authors

### Authors

#### Main Developers

- Sandy Meier - Maintainer, Development co-ordinator, and homepage provider smeier@kdevelop.de

  Main development of: frame structure, IDE look'n feel, project management.

- Stefan Heidrich sheidric@rz.uni-potsdam.de

  Main development of: kappwiz;
  , printing
  functionality

- Ralf Nolden rnolden@kdevelop.de

  Main development of: KDevelop<->Dialog Editor interface, configuration functionality, online-help and handbooks

- Jonas Nordin jonas.nordin@cenacle.se

  Main development of: Classviewer and -parser

- Pascal Krahmer pascal@beast.de

  Main development of: Dialog Editor

- Bernd Gehrmann bernd@physik.hu-berlin.de

  Main development of: Grep Dialog, CVS integration, new DOC tree

- Jörgen Olsson jorgen@cenacle.net

  Main development of: Visual Classtree

- Stefan Bartel bartel@rz.uni-potsdam.de

  Main development of: Real File Viewer

- Walter Tasin tasin@kdevelop.de

  Main development of: Enhancements and Bug fixing

- John Birch jbb@ihug.co.nz

  Main development of: Integrated Debugger

#### Translation Co-ordination

- Martin Piskernig mpiskernig@kdevelop.de

#### Startlogo

- KDevelop 1.0: Jacek Wojdel wojdel@kbs.twi.tudelft.nl

- KDevelop 1.1, 1.2: Ralph Kocher RKocher@t-online.de

#### Additions, patches, and bugfixes

- Pau Estalella Fernandez pef@upcnet.upc.es

- Jost Schenk jost@schenk.de

- David Barth dbarth@videotron.ca

- Matthias Hipp matthias.hipp@gmx.de

- Martin Piskernig martin.piskernig@stuwo.at

- Jochen Wilhelmy digisnap@cs.tu-berlin.de

- Matthias Hoelzer-Kluepfel mh@caldera.de

- Matt Koss koss@napri.sk

- Torsten Uhlmann tulmann@debis.com

- Stefan Mars mars@lysator.liu.se

- Nikolay Liber nikolay_liber@mail.ru

- Gordon Tyler gtyler@iafrica.com

- Huy Cuong Nguyen huyc@iquebec.com

- John R. Zedlewski zedlwski@princeton.edu

- Stephan Uhlmann suhlmann@gmx.de

- Charles Egan cega@oklahoma.net

- Andrew Morton morton@nortelnetworks.com

- p_george p_george@club-internet.fr

- Lubos Lunak l.lunak@sh.cvut.cz

- Armin L. Schneider armin@uumail.de.uu.net

- Martin Spirk spirk@kla.pvt.cz

- Ralf Palsa rpalsa@eso.org

- Richard Dale richard_dale@tipitina.demon.co.uk

- Holger Schurig holger@holger.om.org

- Dag Andersen dandersen@c2i.net

- Alexis Mikhailov alexis@abc.cap.ru

- Nils Ulltveit-Moe nils.ulltveit-moe@hia.no

- Nick Hudson nick@nthcliff.demon.co.uk

- R. Imura imura@cs.titech.ac.jp

- Falk Brettschneider gigafalk@yahoo.com

- Ralf Funken rfunken@kdevelop.de

#### Other Contributions

Kdevelop contains sourcecode from the following applications:

- KWrite 0.98 © by Jochen Wilhelmy digisnaps@cs.tu-berlin.de

- KDE Help © by Martin R. Jones mjones@kde.org

- KSwallow © by Matthias Hoelzer hoelzer@physik.uni-wuerzburg.de

- kcmlocale © by Matthias Hoelzer hoelzer@physik.uni-wuerzburg.de

Proofread and converted to Docbook SGML by Lauri Watts vampyr@atconnex.net

## Thanks

We would like to express special thanks to all of our family members and friends, who supported us in several ways to let us construct and improve KDevelop.

Further, we thank Jochen Wilhelmy for offering his program KWrite, and his help on integrating it into KDevelop.

Thanks also to the KDE team, and Stephan Kulow, who gave us the possibility to work on KDevelop via CVS

We hope that our free work on this product will lead to a better acceptance of Free Software and it's development. Without the help and idealism of many, the KDevelop IDE would never have been realized in such a short period of time, and we're proud that so many users already have reported good experiences and brought KDevelop to it's destiny: helping free software programmers to build a better world where users have the freedom of choice.

## Copyright

KDevelop Copyright 1998, 1999, 2000 The KDevelop Team.

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., 675 Mass Ave, Cambridge, MA 02139, USA.