<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kdevelop "<application>KDevelop 3</application>">
  <!ENTITY grep "<command>grep</command>">
  <!ENTITY egrep "<command>egrep</command>">
  <!ENTITY ctags "<command>ctags</command>">
  <!ENTITY automake "<command>automake</command>">
  <!ENTITY autoconf "<command>autoconf</command>">
  <!ENTITY libtool "<command>libtool</command>">
  <!ENTITY doxygen "<application>doxygen</application>">
  <!ENTITY doxywizard "<application>doxywizard</application>">
  <!ENTITY CVS "<application>CVS</application>">
  <!ENTITY cvs "<application>cvs</application>">
  <!ENTITY ssh "<application>ssh</application>">
  <!ENTITY python "<application>Python</application>">
  <!ENTITY perl "<application>Perl</application>">
  <!ENTITY php "<application>PHP</application>">
  <!ENTITY apache "<application>Apache</application>">
  <!ENTITY Microsoft "<application>Microsoft</application>">
  <!ENTITY Windows "<application>Windows</application>">
  <!ENTITY Mac "<application>Mac</application>">
  <!ENTITY kde "<acronym>KDE</acronym>">
  <!ENTITY qt "<acronym>Qt</acronym>">
  <!ENTITY qte "<application>Qt/embedded</application>">
  <!ENTITY kappname "&kdevelop;">
  <!ENTITY % addindex "INCLUDE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<book lang="&language;">

<bookinfo>
  <title>&kdevelop; User Manual</title>

  <date>2003-09-01</date>
  <releaseinfo>3.0</releaseinfo>

  <authorgroup>
    <author>
      <firstname>Bernd</firstname>
      <surname>Gehrmann</surname>
      <affiliation>
        <address><email>bernd@kdevelop.org</email></address>
	  </affiliation>
    </author>

    <author>
	  <firstname>Caleb</firstname>
      <surname>Tennis</surname>
      <affiliation>
        <address><email>caleb@aei-tech.com</email></address>
      </affiliation>
    </author>

    <author>
      <firstname>Bernd</firstname>
      <surname>Pol</surname>
      <affiliation>
        <address><email>bernd.pol@online.de</email></address>
      </affiliation>
    </author>
  </authorgroup>

  <copyright>
    <year>2002</year>
    <holder>Bernd Gehrmann</holder>
  </copyright>
  <copyright>
    <year>2002</year>
    <holder>Caleb Tennis</holder>
  </copyright>

  <legalnotice>&FDLNotice;</legalnotice>

  <abstract>
    <para>This documentation describes the &kdevelop; Integrated Development
    Environment</para>
  </abstract>

  <keywordset>
    <keyword>KDE</keyword>
    <keyword>KDevelop</keyword>
    <keyword>IDE</keyword>
    <keyword>development</keyword>
    <keyword>programming</keyword>
  </keywordset>

</bookinfo>

<!-- ====================================================================== -->

<chapter id="overview-manual">
<title>About this manual</title>

<para>
This user manual is intended to describe the contents and use of the &kdevelop; Integrated Development Environment (<acronym>IDE</acronym>) from a user's point of view. It is no programming manual nor does it describe the development process in detail. It's only aim is to guide you in the handling of the <acronym>IDE</acronym>.
</para>
<para>
You will here find information on the following topics:
</para>
<itemizedlist>
  <listitem><para>
  <link linkend="unixdev">Development on UNIX</link> - a historical overview on UNIX program development, the main tools necessary and why you need an <acronym>IDE</acronym>.
  </para></listitem>
  <listitem><para>
  <link linkend="kdevelopinstall">Installing &kdevelop;</link> - tells you where to obtain &kdevelop; and how to get it up and running.
  </para></listitem>
  <listitem><para>
  <link linkend="kdevelopoverview">Overview: &kdevelop;'s features</link> - is some kind of a warm-up, giving a short overview of what is built-in into &kdevelop; and makes you acquainted with the look and feel of this <acronym>IDE</acronym>.
  </para></listitem>
  <listitem><para>
  <link linkend="initialsetup">Configuring &kdevelop;</link> - shows how you can taylor the <acronym>IDE</acronym> to suit your needs.
  </para></listitem>
  <listitem><para>
  <link linkend="appwizard">Getting started: the application wizard</link> - describes the basics on how to set up a new project in &kdevelop; using the built-in application wizard.
  </para></listitem>
  <listitem><para>
  <link linkend="editing">Editing tools</link> - all you need to write your source files: using the editor, searching for text both locally and project-wide, up to integrating new files and classes into the project.
  </para></listitem>
  <listitem><para>
  <link linkend="filebrowsers">The file browsers</link> - demonstrates various tools to look at the structure of your project and how to access the files you want to work with.
  </para></listitem>
  <listitem><para>
  <link linkend="classbrowser">The class browsers</link> - describes one of the most powerful tools of &kdevelop; which lets you navigate through class dependencies and allows to easily create and access the classes and methods you need.
  </para></listitem>
  <listitem><para>
  <link linkend="documentation">Documentation</link> - shows how to access the rich built-in documentation &kdevelop; provides and tells you how to create documentation of your project, concise and powerful API documentation providing you an overview over all your project sources as well as docbook-based user documentation.
  </para></listitem>
  <listitem><para>
  <link linkend="projectmanagement">Building and project management</link> - deals with the creating and management of your project, describing the basics of autoconf and automake as well as how to set up custom make files and how to use compiler or make options to taylor your application to suit your needs.
  </para></listitem>
  <listitem><para>
  <link linkend="advancedautoproject">Advanced autoproject usage</link> - looks at ways to keep multiple build configurations, to cross-compile for diverse platforms, or to make an embedded system using the <application>Qt/embedded</application> library.
  </para></listitem>
  <listitem><para>
  <link linkend="debugger">The debugger interface</link> - describes how to use the integrated <application>gdb</application> debugger interface so you can hunt down bugs without leaving &kdevelop; so to always maintain easy acess to the program sources in question.
  </para></listitem>
<!-- ### Maybe interesting, of course, but too detailed for an IDE user manual
  <listitem><para>
  <link linkend="python">Python</link> - an overview on how to create Python-based applications in &kdevelop;.
  </para></listitem>
  <listitem><para>
  <link linkend="php">PHP</link> -  an overview on how to create PHP-based HTML applications in &kdevelop;.
  </para></listitem>//-->
  <listitem><para>
  <link linkend="cvs">Using CVS</link> - tells you how you can maintain your project using the CVS versioning system, a must especially if many developers work at the same project.
  </para></listitem>
  <listitem><para>
  <link linkend="externalprogs">Leveraging external programs</link> - shows how to access ecternal programs and tools from within &kdevelop; thus greatly extending its capabilities.
  </para></listitem>
  <listitem><para>
  <link linkend="plugintools">Plugin tools</link> - provides you an overview on the parts which make up &kdevelop; and how you can taylor it to suit your needs by loading the necessary parts only, both <acronym>IDE</acronym> and project-wide.
  </para></listitem>
</itemizedlist>
</chapter>

<!-- ====================================================================== -->

<chapter id="unixdev">
<title>Development on UNIX</title>

<sect1 id="history">
<title>Some historical remarks</title>

<para>
From the beginning, UNIX has maintained two very different development paradigms. One is the world of <emphasis>system and application programming languages</emphasis>, where some source code is translated to machine code by a translation program, usually a <emphasis>compiler</emphasis> or an <emphasis>interpreter</emphasis>. The programming language C is an example. UNIX was the first operating system kernel to be written in such a high level language instead of tightly machine-oriented assembler which was common before that time. (In fact, the C language once even was invented to write the UNIX kernel and associated programs on a DEC PDP-11 computer.)
</para>
<para>
The other paradigm is the world of <emphasis>scripting languages</emphasis>. This world evolved with the invention of the UNIX shell which was the user's interface to the operating system - and at the same time a very high level programming language. A shell script is built from a set of small utility programs like e.g. <command>grep</command>, <command>sed</command>, or <command>find</command>. Each such utility is designed for some tightly defined job. The trick is that any such utility can be connected to another one via a simple transport mechanism, called a <emphasis>pipe</emphasis>, which directs the output of the foregoing utility into the input of the next processed one. This makes up for a very powerful and highly flexible programming tool.
</para>
<para>
As time has gone by, both worlds have evolved. While C is still used mainly as a system programming language, C++ as a variant of C enriched by object-oriented and genericity extensions has found its place for the development of complex applications in the 1990's. There are numerous other programming languages, even older ones keep their place - FORTRAN77 and Ada e.g. still have their stronghold in numerical applications.
</para>
</sect1> <!-- history -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="unixdev-scripting-languages">
<title>Contemporary scripting languages</title>
<para>
In the scripting area, there has been a shift away from the shell, which suffers from portability concerns, to languages which unify all commonly needed functionality in their standard libraries, while still being able to interface to the outside through pipes when necessary.
</para>
<para>
All these scripting languages have in common that they are widely portable between UNIX variants, &Microsoft; &Windows;, &Mac; OS or even VMS. Also, they all have implementations that are freely distributable.
</para>

<sect2 id="unixdev-SL-Perl">
<title>Perl</title>
<para>
&perl; has become popular as a text processing and system administration language. In the beginning of the World Wide Web, CGI scripts written in &perl; were a widely used method to create dynamic web pages from databases. Today, this method has been replaced mostly by the <command>mod_perl</command> plugin for the &apache; web server. Among &perl;'s strengths are its built-in support for advanced regular expression matching and its rich archive of freely distributed modules, see: <ulink url="http://cpan.org">CPAN</ulink>.
</para>
</sect2>

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

<sect2 id="unixdev-SL-PHP">
<title>PHP</title>
<para>
&php; was invented as a language directly embeddable into HTML pages and consequently has its main uses in delivering dynamic content in the web.
</para>
</sect2>
</sect1> <!-- unixdev-scripting-languages -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="unixdev-dcop">
<title>The DCOP interface</title>

<para>
Another evolution on UNIX-like scripting is the <emphasis>DCOP</emphasis> protocol. DCOP stands for <emphasis>Desktop COmmunikation Protocol</emphasis> and is implemented as a simple IPC/RPC mechanism built to operate over sockets. In effect this provides facilities similar to the traditional UNIX pipe mechanism.
</para>
<para>Traditional shell scripting is based on fairly small tool programs which were designed to work on a strictly textual basis. DCOP allows elaborate graphical programs to communicate with each other in a quite similar way. This enables e.g. a &kde; programm to send messages to another &kde; program, or receive data from it for its own purposes.
</para>
<para>
There are drawbacks, however. To use DCOP a program must be designed to contain a special DCOP interface. And the DCOP communication process runs somewhat slowly. Yet it returns much of the power and flexibility of UNIX scripting to high-level programs which are based on a graphical user interface.
</para>
<para>
For more information, see <citetitle>The DCOP Desktop COmmunication Protocol library</citetitle> API reference of the &kde; dcop library.
</para>
</sect1> <!--  unixdev-dcop -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="unixdev-buildsystems">
<title>Build systems</title>

<para>
Except in very simple cases your programming project will consist of a lot of building blocks of source code each put into a separate file for easier maintenance. To make this running you have to effectively translate all this stuff into a few machine language units in a suiting format which allows the operating system to load and execute the program.
</para>
<para>
To accomplish this, the basic tools you need are
<itemizedlist>
  <listitem><para>
  a <emphasis>text editor</emphasis> to write the source code files,
  </para></listitem>
  <listitem><para>
  a translating program, usually a <emphasis>compiler</emphasis> to turn the source code into object files,
  </para></listitem>
  <listitem><para>
  a <emphasis>librarian</emphasis> which collects object files into libraries to reuse them easily without the need to recompile,
  </para></listitem>
  <listitem><para>
  a <emphasis>linker</emphasis> which binds several object files and libraries together into one executable,
  </para></listitem>
  <listitem><para>
  a <emphasis>make system</emphasis> which provides some means to manage all this stuff and - not to forget
  </para></listitem>
  <listitem><para>
  a <emphasis>debugger</emphasis> to (hopefully) find all errors in the program and possibly some other diagnosis tools to get everything running smootly.
  </para></listitem>
</itemizedlist>
</para>
<para>
When you have a large project consisting of possibly hundreds of source code files, the process of compiling may become quite laborsome. You do not want to recompile all files each time you have changed only some of them. Instead, you only want to compile those files which are affected by the changes. In general, it is not obvious which these are. When you e.g. change a function prototype in a header file, you need to compile every file which includes this header file.
</para>
<sect2 id="unixdev-buildsystems-make">
<title>The make process</title>
<para>
A tool which takes care of recompilations is <command>make</command>. It keeps track of all work using a set of <emphasis>rules</emphasis> which describe what to do in case some piece of information (usually a source or object code file) was changed. All rules belonging to a certain project are stored in a so-called <filename>Makefile</filename> which is processed by <command>make</command> any time you want to update your work.
</para>
<para>
Each rule consists of several building blocks, namely
<itemizedlist>
  <listitem><para>
  a <emphasis>target</emphasis>, i.e. the file to be built
  </para></listitem>
  <listitem><para>
  a set of <emphasis>dependencies</emphasis>, basically the names of those files the target depends on (e.g. the name of a source file, where then the target will be the name of the object file to be built) and
  </para></listitem>
  <listitem><para>
  the <emphasis>commands</emphasis> which are to be executed to "make" the target (i.e. to compile it or to link other object files together to build an executable progam file).
  </para></listitem>
</itemizedlist>
</para>
<para>
Basically the <command>make</command> command will read the rules one after another, check each file in the dependency list of a given target and make this target anew if any one of these files has changed, using the commands listed in that rule.
</para>
<para>
There are several additional possibilities to control such a make process, and a <filename>Makefile</filename> can thus grow very complex. We cannot go into the details here. However, we recommend that you make yourself accustomed to the syntax of <command>make</command>. Even if you do not normally use it directly, an understanding of the fundamentals of the build system can be useful. See the <ulink url="info://make/Top"> <citetitle>GNU Make Manual</citetitle></ulink> for more information. </para>
<para>
For more &kdevelop; specific detail see the <link  linkend="projectmanagement">Building and Project Management</link> chapter of this manual.
</para>
<para>
There are some tutorials available:
<itemizedlist>
  <listitem><para>A short <ulink url="http://www.kdevelop.org/index.html?filename=tutorial_autoconf.html">autoconf tutorial</ulink> written by Christopher W. Curtis available on the KDevelop home page. It concentrates on some basic steps to modify a <filename>Makefile</filename>.
  </para></listitem>
  <listitem><para>
  A more detailed tutorial can be found at <ulink url="http://www.amath.washington.edu/~lf/tutorials/autoconf/toolsmanual_toc.html"></ulink>. This is part of a greater set of tutorials on <citetitle>Developing software with GNU</citetitle>.
  </para></listitem>
</itemizedlist>
</para>
</sect2>

</sect1> <!-- unixdev-buildsystems -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="unixdev-guidevelopment">
<title>GUI development</title>

<para>
Application developers become even more encumbered by having to not only create program libraries and logic, but also provide an easy to use custom built user interface that is both intuitive and functional.  Most programmers receive little to no training in GUI development, and as a result user interfaces are <ulink url="http://www.rha.com/ui_hall_of_shame.htm">poorly designed</ulink>.
</para>
<para>
During the years some common design principles have evolved. It is strongly advised to adhere to them. This way your user interfaces will retain a common look and feel that the users of your application will gratefully appreciate.
</para>
<para>
For &kde; GUI development there is a style guide available. It is found in the <ulink url="http://developer.kde.org/documentation/standards/kde/style/basics/index.html">&kde; User Interface Guidelines</ulink> on the &kde; Developer's Corner page.
</para>

</sect1> <!-- unixdev-guidevelopment -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="unixdev-ide">
<title>Integrating concepts and tools: the IDE</title>

<para>
There are separate tools available for almost any step in the programming process - planning, editing, managing files and compilation processes, debugging, documentation and the like. But once the projects grow the programming process will most likely become quite cumbersome.
</para>
<para>
Much repetitive work has to be done when designing, compiling, and debugging a program. A lot of work can be saved through the use of templates and scripts. And another lot by simple keeping the tools easily available and able to communicate with each other under a common GUI. E.g. it really does come in handy if a debugger were able to open the source file in question in an editor and place the cursor directly at the position of the bug just found.
</para>
<para>
To more easily accomplish such a scheme, <emphasis>Integrated Development Environments</emphasis> (IDE) were devised. Such an IDE integrates all templates, tools, and scripts which are needed in the development process into one single environment.
</para>
<para>
For the &kde; platform &kdevelop; is such an IDE. It provides a wide range of tools which ease program development and maintenance, even for different programming languages and across platforms.
</para>
</sect1> <!-- unixdev-ide -->

</chapter> <!-- unixdev -->

<!-- ====================================================================== -->

<chapter id="kdevelopinstall">
<title>Installing &kdevelop;</title>

<sect1 id="howto">
<title>How to obtain &kdevelop;</title>

<para>
&kdevelop; can be found via the project home page at <ulink url="http://www.kdevelop.org"> http://www.kdevelop.org</ulink> or via the <ulink url="http://download.kde.org">&kde; ftp site</ulink> &kdevelop; is also available from many different Linux distributions.
</para>

<sect2 id="howto-cvs">
<title>Get daily &kdevelop; snapshots from &CVS;</title>

<para>Anonymous &CVS; repository snapshots are available.  The module name is <emphasis>kdevelop</emphasis> at <filename class="directory">:pserver:anonymous@anoncvs.kde.org:/home/kde</filename>.
</para>

<sect3 id="howto-cvs-co">
<title>Initial &CVS; checkout</title>

<para>
To obtain an initial version of &kdevelop; you must download it (this is a so-called <emphasis>checkout</emphasis> operation) from anonymous &CVS;. Just follow these steps. (We assume you want to put your &kdevelop; copy into the <filename class="directory">kde3src</filename> directory.)
</para>

<simplelist>
  <member>
    <prompt>~&gt; </prompt>
    <userinput>mkdir kde3src</userinput>
  </member>
  <member>
    <prompt>~&gt; </prompt>
    <userinput>cd kde3src</userinput>
  </member>
  <member>
    <prompt>~/kde3src&gt; </prompt>
    <userinput>cvs -z3 -d :pserver:anonymous@anoncvs.kde.org:/home/kde co kdevelop</userinput>
  </member>
  <member>
    <prompt>~/kde3src&gt; </prompt>
    <userinput>cd kdevelop</userinput>
  </member>
</simplelist>
<para>
Now you may compile your &kdevelop; version as shown in the <link linkend="compileandinstall">&kdevelop; Compilation and Installation</link> chapter.
</para>
<para>
<emphasis>Note:</emphasis> Once you successfully checked out your &kdevelop; version, you may keep up with the changes using the update procedure shown in the next section. <emphasis>Please do not checkout every time you want to keep your &kdevelop; up to date!</emphasis>
</para>
</sect3>

<sect3 id="howto-cvs-up">
<title>Keeping your &CVS; copy actual</title>

<para>
After you checked out (and successfully compiled) &kdevelop; from CVS as shown above, you'll want to keep it up to date in order to get all the patches. Follow these steps. (We again assume you have put your &kdevelop; copy into the <filename class="directory">kde3src</filename> directory.)
</para>
<para>
Note the <command>up</command> (= <emphasis>update</emphasis>) command instead of the <command>co</command> (which stands for <emphasis>checkout</emphasis>).
</para>

<simplelist>
  <member>
    <prompt>~&gt; </prompt>
    <userinput>cd kde3src</userinput>
  </member>
  <member>
    <prompt>~/kde3src&gt; </prompt>
    <userinput>cvs -z3 -d :pserver:anonymous@anoncvs.kde.org:/home/kde up kdevelop</userinput>
  </member>
  <member>
    <prompt>~/kde3src&gt; </prompt>
    <userinput>cd kdevelop</userinput>
  </member>
</simplelist>

<para>
<emphasis>Note:</emphasis> Keep an eye on the messages &CVS; produces during the update sequence. The exact steps in the compilation sequence depend on this.
</para>
<para>
Now you can compile a new &kdevelop; version as shown in the <link linkend="compileandinstall-make-cvs">Special &CVS; compilation considerations</link> chapter.
</para>
</sect3>

</sect2>

</sect1> <!-- howto -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="requirements">
<title>&kdevelop; requirements</title>
<para>
In order to successfully compile and use &kdevelop;, you need the following programs and libraries. They are available on most platforms as distribution packages and thereby can be installed easily.
</para>

<itemizedlist>
<title>Required:</title>
  <listitem><para><application>gcc/g++</application> 2.95.3 or greater (or compatible)</para></listitem>
  <listitem><para><application>GNU make</application> (or compatible)</para></listitem>
  <listitem><para><application>perl</application> 5.004</para></listitem>
  <listitem><para><application>autoconf</application> 2.52 or greater</para></listitem>
  <listitem><para><application>automake</application> 1.6.1 or greater</para></listitem>
  <listitem><para><application>flex</application> 2.5.4</para></listitem>
  <listitem><para><application>Qt</application> 3.0.3 or greater</para></listitem>
  <listitem><para><application>KDE</application> 3.0.4 or greater</para></listitem>
</itemizedlist>

<itemizedlist>
<title>Optional:</title>
  <listitem><para>
  The <application>ctags</application> source navigation tool, from <ulink url="http://ctags.sourceforge.net">http://ctags.sourceforge.net</ulink>, which enables you fast access to declarations and definitions by a few simple clicks on a name in the editor.
  </para></listitem>
  <listitem><para>
  <application>dot</application>, a graphics language compiler, from <ulink url="http://www.graphviz.org">http:/www.graphviz.org</ulink>. This
  <!-- ### temporarily disabled until the graphial class browser works again
  allows you to navigate in a graphical view of your classes' dependencies. Likewise the <application>dot</application> //-->
  tool is needed in conjunction with <application>doxygen</application> below if you want to have class relationships graphically displayed (which is highly recommended).
  </para></listitem>
  <listitem><para>
  The <application>doxygen</application> documentation tool, from <ulink url="http://www.stack.nl/~dimitri/doxygen">http://www.stack.nl/~dimitri/doxygen</ulink> if you want to generate concise and powerful API documentation from your projects.
  </para></listitem>
  <listitem><para>
  <application>valgrind</application> from <ulink url="http://developer.kde.org/~sewardj/">http://developer.kde.org/~sewardj/</ulink> helps you to find memory management problems in your applications.
  </para></listitem>
  <listitem><para>
  Any other compiler and/or tool in case you want to develop for another language/platform than <acronym>C++</acronym>/&kde; or use some special facility.
  </para></listitem>
</itemizedlist>

<para>
<emphasis>Note 1:</emphasis> You can circumvent the need for &autoconf; >= 2.52 and &automake; >= 1.6.1. Just remove the <filename class="directory">admin</filename> directory in your &kdevelop; installation directory and type
</para>
<para>
<prompt>(your-kdevelop-directory)&gt; </prompt>
<userinput>ln -s $KDEDIR/share/apps/kdelibs/admin admin</userinput>
</para>
<para>
at the console. This causes &kdevelop; to use the standard settings in the &kde; <filename class="directory">admin</filename> directory instead.
</para>

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

</sect1> <!-- requirements -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="compileandinstall">
<title>&kdevelop; compilation and installation</title>

<sect2 id="compileandinstall-preliminaries">
<title>Preliminary steps</title>

<para>
Before entering the compile sequence you must make sure all libraries and tools are available to the make system. To accomplish this some environment variables need to be properly set. The actual steps to be performed depend on the console shell you use.
</para>
<para>
<emphasis>Note:</emphasis> To avoid typing in all the statements that set the necessary environment variables every time you want to compile, you should put them in your <filename>.bashrc</filename> or <filename>.cshrc</filename> file. That way the environment variables will be properly set every time you start the shell.
</para>

<sect3 id="compileandinstall-preliminaries-bash">
<title>bash shell</title>

<para>
If you use the bash shell add the following lines:
</para>
<screen>
export KDEDIR=(where-your-kde3-is)
export QTDIR=(where-your-qt-library-is)
export LD_LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib:$LD_LIBRARY_PATH
export LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib:$LIBRARY_PATH
export PATH=$QTDIR/bin:$KDEDIR/bin:$PATH
</screen>
</sect3>

<sect3 id="compileandinstall-preliminaries-tcsh">
<title>tcsh shell</title>

<para>
If you use the tcsh shell add the following lines:
</para>
<screen>
setenv KDEDIR (where-your-kde3-is)
setenv QTDIR (where-your-qt-library-is)
setenv LD_LIBRARY_PATH $QTDIR/lib:$KDEDIR/lib:$LD_LIBRARY_PATH
setenv LIBRARY_PATH $QTDIR/lib:$KDEDIR/lib:$LIBRARY_PATH
setenv PATH $QTDIR/bin:$KDEDIR/bin:$PATH
</screen>
</sect3>

</sect2>

<sect2 id="compileandinstall-make">
<title>Compile &kdevelop;</title>

<para>
<emphasis>Note:</emphasis> In the following discussion we assume that you have put your &kdevelop; sources in the <filename class="directory">~/kde3src/kdevelop</filename> directory.
</para>

<sect3 id="compileandinstall-make-cvs">
<title>Special &CVS; compilation considerations</title>

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

<formalpara id="compileandinstall-make-cvs-co">
<title>After a CVS checkout</title>
<para>
You should initialize the make system after a fresh checkout. The same is true every time you need to start over from scratch. (Note that you must have access to the &CVS; repository for the clean-up.) Type:
</para>
</formalpara>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>make -f admin/Makefile.common cvs-clean</userinput>
</para>
<para>
and then <emphasis>all</emphasis> of the following steps.
</para>

<formalpara id="compileandinstall-make-cvs-up">
<title>After a CVS update</title>
<para>
The next step depends on the output of the &CVS; update sequence. If you got something like (note the U marker to the left):
<screen>
U /some_directory_path/Makefile.am
</screen>
or if you just did a full checkout, you must do:
</para>
</formalpara>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>make -f Makefile.cvs</userinput>
</para>
<para>
before you proceed with <emphasis>all</emphasis> of the following steps.
</para>
</sect3>

<sect3 id="compileandinstall-make-basic">
<title>Basic <command>make</command> command sequence</title>

<para>
Once the basic make system is set up this way you must decide on the type of the &kdevelop; system you want to use. This is done in the following configure step which buids the actual <filename>Makefile</filename> the <command>make</command> command will use.
</para>
<para>
<emphasis>Note:</emphasis> You may drop the <option>--prefix</option> option in the following <command>configure</command> command lines if you want &kdevelop; be installed in the default &kde; directory. See the <link linkend="compileandinstall-options">Some notes on <command>configure</command> options</link> chapter for this.
</para>

<formalpara>
<title>A debug-compiled version</title>
<para>
If you want to keep track of what your &kdevelop; application does at run-time you may buid a debug-compiled version. Just command <command>configure</command> to do so:
</para>
</formalpara>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>./configure --enable-debug=full
                         --prefix=(where-your-kde3-is)</userinput>
</para>

<formalpara>
<title>A release-compiled version</title>
<para>
If you only want to use &kdevelop; as-is a (smaller and faster running) release version suffices. <command>configure</command> defaults to this.
</para>
</formalpara>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>./configure --prefix=(where-your-kde3-is)</userinput>
</para>

<formalpara>
<title>Make and install &kdevelop;</title>
<para>
<command>configure</command> will check the system and build a <filename>Makefile</filename> according to what it found. The <command>make</command> command will use this <filename>Makefile</filename> by default. Thus
</para>
</formalpara>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>make</userinput>
</para>
<para>
suffices. If necessary, now gain root user rights by
</para>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>su</userinput>
</para>
<para>
and entering the root password. Then install the application:
</para>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>make install</userinput>
</para>
<para>
That was all. If you installed &kdevelop; in the default &kde; directory you can now run the <acronym>IDE</acronym>. Otherwise some additional steps will be necessary as shown in the <link linkend="compileandinstall-options-dir">Non-default installation directory</link> section below.
</para>

</sect3>
</sect2>

<sect2 id="compileandinstall-bsd">
<title>How to compile on FreeBSD</title>

<para>
If you want compile and install &kdevelop; on a <acronym>FreeBSD</acronym> system follow the normal instructions but after
</para>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>make -f Makefile.cvs</userinput>
</para>
<para> do:
</para>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>export CXXFLAGS="-L/usr/X11R6/lib -I/usr/local/include/db41 -I/usr/local/include -L/usr/local/lib -I/usr/X11R6/include"</userinput>
</para>
<para><emphasis>Note:</emphasis> You need the <emphasis>berkeley db 4.1</emphasis> installed, if you have another version, you have to adjust the path.
</para>

<sect3>
<title>Check the berkeley db version</title>
<para>
To find out which berkeley db version you have installed, run:
</para>
<para>
  <prompt>~&gt; </prompt>
  <userinput>pkg_info | grep db41</userinput>
</para>
<para>
This should return someting like:
<screen>
db41-4.1.25_1       The Berkeley DB package, revision 4.1
</screen>
</para>
</sect3>

<sect3>
<title>More changes</title>
<para>
Change the line
</para>
<para>
<option>ac_cv_bdb=no</option>
</para>
<para>
to
</para>
<para>
<option>ac_cv_bdb=yes</option>
</para>
<para>
in the <filename>configure</filename> file because otherwise configure can't find the db libraries.
</para>
<para>
<emphasis>Note:</emphasis> As <command>make -f Makefile.cvs</command> rebuilds the <filename>configure</filename> file you have to always change this entry as well.
</para>
<para>
The <acronym>FreeBSD</acronym> guys renamed <filename>libdb.so</filename> to <filename>libdbxx.so</filename>. So replace
</para>
<para>
<option>libkdevcatalog_la_LIBADD = -ldb</option>
</para>
<para>
by
</para>
<para>
<option>libkdevcatalog_la_LIBADD = -ldb41</option>
</para>
<para>
in <filename>lib/catalog/Makefile.am</filename>.
</para>
<para>
Then you can continue with the normal <command>configure</command> and <command>make</command> steps as shown above.
</para>
</sect3>

</sect2>

<sect2 id="compileandinstall-options">
<title>Some notes on <command>configure</command> options</title>

<sect3 id="compileandinstall-options-dir">
<title>Non-default installation directory</title>

<para>
By default <command>configure</command> prepares the <acronym>IDE</acronym> to be installed in the default &kde; directory. This is necessary because &kdevelop; assumes direct access to some tools and parts which reside there. If want to use your own installation directory, you must tell <command>configure</command> this by the <option>--prefix</option> option:
</para>
<para>
  <prompt>~/kde3src/kdevelop&gt; </prompt>
  <userinput>./configure --prefix=(where-your-kde3-is)</userinput>
</para>
<para>
There is a caveat if you do so. You must provide a means for &kdevelop; to access the needed tools and parts in the &kde; directory. (You can still use the IDE without doing so, but with very restrained capabilities.) You have to use a shell where the following commands must be executed before you can start &kdevelop; at the shell prompt.
</para>
<para>
(<emphasis>Note the plural:</emphasis> KDEDIRS, not just KDEDIR)
</para>
<simplelist>
  <member>
    <prompt>(your-kdevelop-directory)&gt; </prompt>
    <userinput>export KDEDIRS=/usr/local/kde:/opt/kde3</userinput>
  </member>
  <member>
    <prompt>(your-kdevelop-directory)&gt; </prompt>
    <userinput>kbuildsycoca</userinput>
  </member>
</simplelist>
<para>
In a tcsh shell you must set the environment variables using:
</para>
<para>
    <prompt>(your-kdevelop-directory)&gt; </prompt>
    <userinput>setenv KDEDIRS /usr/local/kde:/opt/kde3</userinput>
</para>
<para>
The <command>kbuildsycoca</command> command ("build system control cache") looks around for libraries and caches their location and version, so that &kdevelop; can find them. The caveat is that it takes noticeable time - and it has to be run any time you call up the shell to start &kdevelop; from a non-default directory. You may want to put the above commands into a shell script to reduce the typing effort.
</para>
<para>
(You could as well put the lines in your <filename>.bashrc</filename> or <filename>.cshrc</filename> file, but this is not advisable as <command>kbuildsycoca</command> will then be run any time you call up the shell.)
</para>
</sect3>

<sect3>
<title>Other options</title>
<!-- *** other configuration options -->
<para>
<emphasis>(... to be written ...)</emphasis>
</para>
</sect3>
</sect2>

</sect1> <!-- compileandinstall -->

</chapter> <!-- kdevelopinstall -->

<!-- ====================================================================== -->

<chapter id="kdevelopoverview">
<title>Overview: &kdevelop;'s features</title>

<para>
&kdevelop; integrates a lot of tools, scripts, and templates in a common user interface. Basically it consists of
<itemizedlist>
  <listitem><para>
  several <link  linkend="uimodes-overview">user interface modes</link> from which you can select the look and feel of the workspace,
  </para></listitem>
  <listitem><para>
  an <link linkend="appwizard">application wizard</link> which aids you in setting up a new project,
  </para></listitem>
  <listitem><para>
  several <link linkend="makesystems">project management systems</link> which aid in building and managing your project,
  </para></listitem>
  <listitem><para>
  some <link linkend="editing">editing tools</link> to easily work on your program texts
  </para></listitem>
  <listitem><para>
  various <link linkend="filebrowsers">file browsers</link> providing you different views on your file system,
  </para></listitem>
  <listitem><para>
  various <link linkend="classbrowser">class browsers</link> to aid you in maintaining the classes and their relationships of your object-oriented programming project,
  </para></listitem>
  <listitem><para>
  a <link linkend="debugger">debugger interface</link> to find and remove program errors from within &kdevelop;, and
  </para></listitem>
  <listitem><para>
  several <link linkend="plugintools">plugin tools</link>, extensible modules which can be loaded at runtime and on demand.  This allows you to only turn on those features you really need.
  </para></listitem>
  <listitem><para>
  a set of other diagnosis, documentation, and optimization helper tools.
  </para></listitem>
</itemizedlist>
</para>

<sect1 id="uimodes-overview">
<title>Availabe user interface modes</title>

<para>
&kdevelop; offers developers four separate user interface modes (click on the mode name to view an example):
<itemizedlist>
  <listitem>
  <para><link linkend="mdi-desc">Child Frame Windows</link></para>
  <itemizedlist>
    <listitem><para>All tool views are initially docked to the mainframe.</para></listitem>
    <listitem><para>Editor and browser views will live like toplevel windows within a view area of the mainframe.</para></listitem>
  </itemizedlist>
  </listitem>

  <listitem>
  <para><link linkend="tabbed-desc">Tabbed Pages</link></para>
  <itemizedlist>
    <listitem><para>
	All tool views are initially docked to the mainframe.
	</para></listitem>
    <listitem><para>
	Editor and browser views will be stacked in a tab window.
	</para></listitem>
  </itemizedlist>
  </listitem>

  <listitem>
  <para><link linkend="toplevel-desc">Toplevel Windows</link></para>
  <itemizedlist>
    <listitem><para>
	All editor, browser, and tool views will be toplevel windows directly on the desktop.
	</para></listitem>
    <listitem><para>
	The main widget only contains the menu, toolbars, and statusbar.
	</para></listitem>
  </itemizedlist>
  </listitem>

  <listitem><para><link linkend="ideal-desc">IDEAl</link></para>
  <para>
  This is a novel user interface approach optimizing both work space and intuitive handling of the tools.
  </para>
  <itemizedlist>
    <listitem><para>
	All tool views are docked in a tabbar fashion around the mainframe area. They are grouped left, bottom, and right according to the services provided.
	</para></listitem>
    <listitem><para>
	Editor and browser views will be stacked in a big sized tab window inmidst the mainframe area.
	</para></listitem>
  </itemizedlist>
  </listitem>
</itemizedlist>
</para>

<sect2 id="uimodes-switch">
<title>How to switch user interface modes</title>

<para>
To switch the user interface mode select <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure Gideon...</guimenuitem> </menuchoice> from the menus. The <guilabel>Customize KDevelop</guilabel> dialog will pop up, where you have to select <guilabel>User Interface</guilabel> in the left hand field. This will get you to the settings page shown below.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="select-user-interface.png" format="PNG"/>
	</imageobject>
	<caption><para>
	Select a user interface mode
	</para></caption>
  </mediaobject>
</screenshot>

<para>
Select the radio button of the user interface mode you want to switch to, then press <guibutton>OK</guibutton>
</para>
<para>
<emphasis>Note 1:</emphasis> If you switch to or from the (non-windowed) IDEAl mode, you'll have to restart &kdevelop;.
</para>
<para>
<emphasis>Note 2:</emphasis> Currently there are two IDEAl modes provided - a "window" IDEAl mode and a "standard" IDEAl mode (bottom row of the radio buttons). The window mode fits with the other mdi modes, but is still experimental. You don't need to restart &kdevelop; if you select this one from one of the other three mdi modes. Yet it is recommended to use the standard IDEAl mode in everyday work for now.
</para>
</sect2>

<sect2 id="maximize-workspace">
<title>How to maximize the work space area</title>
<para>
To maximize space, there is a full-screen window mode available which expands the mainframe area to the screen borders. Additional space can be reclaimed by hiding the menubar. And you can of course hide any toolbar as usual in <application>KDE</application> applications.
</para>

<formalpara>
<title>Full screen mode</title>
<para>
To switch to or from full screen mode select <menuchoice> <guimenu>Tools</guimenu> <guimenuitem>Full-Screen Mode</guimenuitem> </menuchoice> from the menus or press <keycombo> <keycap>Ctrl</keycap> <keycap>Shift</keycap> <keycap>F</keycap> </keycombo>. There is also a <guiicon>Full-Screen Mode</guiicon> icon in the <guilabel>Browse Toolbar</guilabel> available.
</para>
</formalpara>

<formalpara>
<title>Hide/unhide the menubar</title>
<para>
To <emphasis>hide</emphasis> the menu bar select <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Show Menubar</guimenuitem> </menuchoice> from the menus or press <keycombo> <keycap>Ctrl</keycap> <keycap>M</keycap> </keycombo>. You may also include a <guiicon>Show Menubar</guiicon> icon in a suiting toolbar, e.g. the <guilabel>Browse Toolbar</guilabel> for that purpose. To <emphasis>unhide</emphasis> the menubar you must press <keycombo> <keycap>Ctrl</keycap> <keycap>M</keycap> </keycombo> or use the <guiicon>Show Menubar</guiicon> icon if available.
</para>
</formalpara>

</sect2>

</sect1> <!-- uimodes-overview -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="makesystems">
<title>Project management systems</title>

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

<itemizedlist>
  <listitem><para>
  <link linkend="automake-project">Automake projects</link> use the GNU standard development tools.
  </para></listitem>
  <listitem><para>
  <link linkend="qmake-project">QMake projects</link> use the trolltech QMake project manager.
  </para></listitem>
  <listitem><para>
  <link linkend="ant-project">ANT projects</link> use the Apache ANT project manager for Java development.
  </para></listitem>
  <listitem><para>
  <link linkend="custom-project">Custom projects</link> require you to maintain your own <filename>Makefiles</filename>.
  </para></listitem>
</itemizedlist>
</para>

<sect2 id="automake-project">
<title>Automake project</title>

<para>
Projects created with &kdevelop;'s Automake Project Manager make it very easy for developers to use the GNU standard development tools. They provide
<itemizedlist>
  <listitem><para>
  a better way of <filename>Makefile</filename> generation and
  </para></listitem>
  <listitem><para>
  a good and safe way for fast adaption towards different systems by autoconf-generated <filename>configure</filename> scripts.
  </para></listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="qmake-project">
<title>QMake project</title>

<para>
For developers who enjoy the flexibility and feel of &qt;'s qmake system, &kdevelop; offers the ability to handle qmake based projects (.pro files) within the GUI.
</para>
<para>
For more information on the QMake project manager see the <citetitle>qmake User Guide</citetitle> which should be included in your distribution or have a look at the <ulink url="http://doc.trolltech.com/">TROLLTECH Documentation</ulink> home page where you may find the QMake documentation of your <citetitle>Qt C++ GUI Application Development Toolkit</citetitle> version.
</para>
</sect2>

<sect2 id="ant-project">
<title>ANT project</title>

<para>
Java developers may want to use the Apache ANT project manager for their projects. To set up a new Ant project in &kdevelop; select <menuchoice><guimenu>Project</guimenu>
<guimenuitem>New Project...</guimenuitem>
<guimenuitem>Java</guimenuitem>
<guimenuitem>Ant Project</guimenuitem>
<guimenuitem>Application</guimenuitem></menuchoice>.
</para>
<para>
For more information see <ulink url="http://ant.apache.org/">The Apache Ant Project</ulink> home page.
</para>
</sect2>

<sect2 id="custom-project">
<title>Custom project</title>

<para>
If you prefer to maintain your own <filename>Makefiles</filename> for your project you may use the custom project option of &kdevelop;. This may be feasible in unusually structured projects or if you want to retain full control over the <command>make</command> process.
</para>
<para>
Yet, if you do not <emphasis>really need</emphasis> the extra flexibility and control of the custom project manager you should consider Autoproject or one of the other project managers, because they considerably ease the program building and distribution processes.
</para>
</sect2>

<sect2 id="makesystems-distribution">
<title>How to distribute your application</title>

<para>
The distribution of your applications does not require the end-user to have anything different installed other than
<itemizedlist>
  <listitem><para>an appropriate compiler,</para></listitem>
  <listitem><para>a linker, and</para></listitem>
  <listitem><para>the appropriate development libraries,</para></listitem>
</itemizedlist>
</para>
<para>
which at least for C++ applications is most often the case. But you can as well distribute <emphasis>binary packages</emphasis> of your application.
<!-- ### more detail on binary construction needed somewhere -->
In either way, the end-user of your product does not need &kdevelop; installed.
</para>
<para>
For giving away your sources, we advise to include the <emphasis>project file</emphasis> of &kdevelop; as well. This makes it very easy for other developers - if they use &kdevelop; - to work with your sources.
</para>
<para>
For projects where s<emphasis>everal developers</emphasis>, maybe working on different places, are involved, this should be the case anyway. So you can ensure consistency of the <filename>Makefiles</filename> to not run into trouble.
</para>
<para>
Especially on multi language applications, <emphasis>translators</emphasis> won't actually work with the source code, except in cases that require correction for enabling translation support.
</para>

</sect2>

</sect1> <!-- makesystems -->

</chapter> <!-- kdevelopoverview -->

<!-- ====================================================================== -->

<chapter id="initialsetup">
<title>Configuring &kdevelop;</title>

<para>
</para>

<sect1 id="initialsetup-general">
<title>General configuration issues</title>

<para>
</para>
</sect1> <!-- initialsetup-general -->

<sect1 id="initialsetup-advanced">
<title>Advanced configuration</title>

<para>
</para>
</sect1> <!-- initialsetup-advanced -->

</chapter> <!-- initialsetup -->

<!-- ====================================================================== -->

<chapter id="appwizard">
<title>Getting started: the application wizard</title>

<para>
In &kdevelop; software development work is organized in <emphasis>projects</emphasis>. Such a project keeps everything together which belongs to a complete programming task: source files, additional data files, any actually needed management facilities as the make system as well as access to all components and/or tools specially needed to get the application up and running.
</para>
<para>
Organizing all development work in projects allows you to easily switch between the global tasks at hand. This is quite handy if you e.g. work on several applications at the same time as is often the case. Tell &kdevelop; to open the project you want to work at and you may proceed in the environment just where you left.
</para>

<sect1 id="newprojects">
<title>New projects</title>

<para>
Whenever you want to initiate a new programming project quite a lot of formal setup procedures need to be done. An initial directory structure has to be set up, initial header and source files must be provided, the make system has to be initialized, etc.
</para>
<para>
&kdevelop; provides an easy way to initiate a new programming project - the <emphasis>application wizard</emphasis>. You will find the application wizard at menu entry <menuchoice><guimenu>Project</guimenu> <guimenuitem>New Project</guimenuitem></menuchoice>.
</para>
<para>
Only a short series of steps is necessary to start a new programming project, using the application wizard:
</para>
<orderedlist>
  <listitem><para>
  <link linkend="newprojects-start-type">Select the programming language</link> you want to use and the type of the application you want to build from a set of predefined templates.
  </para></listitem>
  <listitem><para>
  <link linkend="newprojects-start-general">Supply some general information</link> as application name, directory where the application shall be built, etc.
  </para></listitem>
  <listitem><para>
  Decide whether you want to use a version control system, like e.g. CVS, and supply the necessary data if needed.
  </para></listitem>
  <listitem><para>
  Set up some templates for initial header and source files (if applicable).
  </para></listitem>
  <listitem><para>
  Finally tell application wizard to set up all initial directory structure, starting header/source file templates, and managment tools, like e.g. an initial make skeleton, etc.
  </para></listitem>
</orderedlist>
<para>
Voil&agrave; - that's all. Application wizard will have provided you with a primary functional set of programming files, where you can readily start working.
</para>
<para>
Let's look at all this in more detail now ...
</para>

<sect2 id="newprojects-start">
<title>Initial steps</title>

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

<screenshot id="screenshot-newprojectwizard">
  <mediaobject>
    <imageobject>
      <imagedata fileref="createnewproject.png" format="PNG"/>
    </imageobject>
<!-- ### caption is disturbing in this context
	<caption><para>
	The Create New Project application wizard dialog
	</para></caption> -->
  </mediaobject>
</screenshot>

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

<sect3 id="newprojects-start-type">
<title>Select programming language and application type</title>

<para>
The left hand side of the upper part in this dialog is where you do the selection work. When it shows up, you'll find there a list of folders each labeled with a programming language, as for instance:
</para>
<itemizedlist>
  <listitem><para>Ada</para></listitem>
  <listitem><para>C</para></listitem>
  <listitem><para>C++</para></listitem>
  <listitem><para>Fortran</para></listitem>
  <listitem><para>Java</para></listitem>
  <listitem><para>PHP</para></listitem>
  <listitem><para>Pascal</para></listitem>
  <listitem><para>Perl</para></listitem>
  <listitem><para>Python</para></listitem>
  <listitem><para>Ruby</para></listitem>
  <listitem><para>Shell</para></listitem>
</itemizedlist>
<para>
To be precise, these folders do not contain real programming tools actually. They do lead to pre-defined <emphasis>templates</emphasis> you can use as a starting point for development in that language. To get an idea of what is provided, just open the folders one after the other. There will be a series of subfolders on some, one or more simple entries only on others. The subfolders you see organize the available templates according to some tasks, the simple entries name the templates you may select.
</para>
<para>
We cannot go into detail here on which tasks each template provides, but it's easy to find out. Whenever you select a template entry some information is displayed in the fields to the right. In the lower field you will find a <emphasis>short description</emphasis> on what the template is supposed to do. In the field above that a picture will be shown, if available, about the the outcome of the application this template produces if you compile and run it unmodified. Usually this is a <emphasis>screenshot</emphasis> of the main window the application will display.
</para>
<para>
Select the template which best fits your application's goals as a starting point. Then enter the general properties information in the lower field as shown in the next chapter.
</para>
</sect3>

<sect3 id="newprojects-start-general">
<title>Provide general information</title>

<para>
The lower part of the <guilabel>Create New Project</guilabel> dialog <guilabel>General</guilabel> page is a framed field labeled <guilabel>Properties</guilabel>. You must provide some general information about your project here so that the application wizard knows how to build the initial structure.
</para>
<formalpara>
<title>Application Name</title>
<para>
Your application needs a name of course. Enter this in the uppermost <guilabel>Properties</guilabel> field, called <guilabel>Application Name</guilabel>.
</para>
</formalpara>
<para>
When you do so, you will notice that the application wizard refuses to accept special characters of any kind. The only characters accepted are:
<itemizedlist>
  <listitem><para>upper and lower case characters</para></listitem>
  <listitem><para>numbers</para></listitem>
  <listitem><para>the underline character</para></listitem>
</itemizedlist>
</para>
<para>
One prominent cause of this restriction is that the application manager will use this application name as the <emphasis>basis of some class names</emphasis> it will construct when it sets up an initial project. Thus the name of the application must stick to the rules of the programming language you use.
</para>
<formalpara>
<title>The project directory</title>
<para>
The other prominent cause of this restriction you can see at the bottom line of the <guilabel>Properties</guilabel> area. It is labeled <guilabel>Final location</guilabel> and shows the directory where the application manager  will create the application.
</para>
</formalpara>
<para>
As you type the application name you will notice that the application wizard repeats your input at the end of the <guilabel>Final location</guilabel> line, using lower case only characters.
</para>
<para>
Thus you must select the name of your new application with care.  If you end up with an already used directory the application manager will complain, albeit only at the very end of the setup process:
</para>

<screenshot id="screenshot-wrongprojectloc">
  <mediaobject>
    <imageobject>
      <imagedata fileref="wrong-project-location.png" format="PNG"/>
    </imageobject>
  </mediaobject>
</screenshot>

<para>
Once you pressed <guibutton>OK</guibutton> on this the application manager will send you back to this first <guilabel>General</guilabel> page of the <guilabel>Create New Project</guilabel> dialog, requiring you to correct the application directory.
</para>

<formalpara>
<title>The starting path</title>
<para>
There are two ways to select another path for your new application. One is to select another name. Yet, this is not always feasible (you might e.g. set up for another version of an already existing application). As an alternative you may select another path to the application directory.
</para>
</formalpara>
<para>
This is done in the second row input field of the <guilabel>Properties</guilabel>, named <guilabel>Location</guilabel>. What you enter here is the <emphasis>starting path</emphasis> of the new application development directory. The application manager appends the application name to this path when it initializes the new project. The result is shown in the <guilabel>Final location</guilabel> line to give you better control on what is going on.
</para>
<para>
Application manager will copy an <emphasis>initial value</emphasis> to the <guilabel>Location</guilabel> field on start-up. This is taken from what you have chosen in the <guilabel>Default projects directory</guilabel> field during the <link linkend="initialsetup-general">general configuration steps</link>.
</para>
<para>
Alter the <guilabel>Location</guilabel> field contents so that the application deveopment directory shown in the <guilabel>Final location</guilabel> line will be unique.
</para>
<para>
<emphasis>Note:</emphasis> Take care that the path you enter in the <guilabel>Location</guilabel> field already exists. Otherwise the application manger will not allow you to continue to the next step, keeping the <guibutton>Next &gt;</guibutton> button deactivated (greyed).
</para>
<para>
The application manager will warn you about non-existing paths by appending <emphasis>(invalid)</emphasis> to the <guilabel>Final location</guilabel> line. Thus, if the <guibutton>Next &gt;</guibutton> button will remain greyed whatever you do - check here whether your application development path is valid.
</para>

<formalpara>
<title>Personal information</title>
<para>
The fields following this are not so critical. Just supply your name (i.e. the name of the person who is responsible for the application) in the <guilabel>Author</guilabel> field, and a valid e-mail address in the <guilabel>Email</guilabel> field, so that users can give you feedback on the application.
</para>
</formalpara>
<para>
<emphasis>Note 1:</emphasis> The application manager will integrate this information into the starting program templates if applicable. In KDE C++ programs for instance you will find it near the beginning of the <filename>main.cpp</filename> source file.
</para>
<para>
<emphasis>Note 2:</emphasis> Of all fields, the <guilabel>Email</guilabel> is <emphasis>optional</emphasis>, reflecting the fact that not every developer may have access to the internet. You may keep this field empty if you wish and proceed nevertheless.
</para>

<formalpara>
<title>Version and license info</title>
<para>
Finally enter a starting version number for your new application in the <guilabel>Version</guilabel> field, and select the license under which you want your application be put from the <guilabel>License</guilabel> control.
</para>
</formalpara>
<!-- ### Supply a link to licence stuff explanation -->
<para>
<emphasis>Note:</emphasis> Both version and license information will as well be integrated into the starting templates in a suiting format the application type you selected does provide.
</para>

<para>
Once you have correctly entered all this information stuff, press the <guibutton>Next &gt;</guibutton> button to proceed as will be shown in the following chapters.
</para>
</sect3>

</sect2>

<sect2 id="newprojects-start-cvs">
<title>Supply version system information</title>
<para></para>
</sect2>

<sect2 id="newprojects-start-templates">
<title>Supply header/source templates</title>
<para></para>
</sect2>

<sect2 id="newprojects-start-build">
<title>Build the initial project files</title>
<para></para>
</sect2>

</sect1> <!-- newprojects -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="importing">
<title>Importing existing projects</title>

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

<figure id="screenshot-importdirectory" float="1">
<title>The Import Directory dialog</title>
<mediaobject>
<imageobject><imagedata fileref="importdirectory.png"/></imageobject>
</mediaobject>
</figure>

</sect1> <!-- importing -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="convertingold">
<title>Converting old KDevelop project files</title>

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

</sect1> <!-- convertingold -->

</chapter> <!-- appwizard -->

<!-- ====================================================================== -->

<chapter id="editing">
<title>Editing tools</title>

<sect1 id="keyboardmapping">
<title>Keyboard mapping</title>
<indexterm zone="keyboardmapping"><primary>keybindings</primary></indexterm>

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

<informaltable>
<tgroup cols="2">
<tbody>

<row><entry><para><keycap>
  Left
</keycap></para></entry>
<entry><para>
  Moves one character left
</para></entry></row>

<row><entry><para><keycap>
  Right       
</keycap></para></entry>
<entry><para>
  Moves one character right
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  Left   
</keycap></keycombo></para></entry>
<entry><para>
  Moves one word left
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  Right  
</keycap></keycombo></para></entry>
<entry><para>
  Moves one word right
</para></entry></row>

<row><entry><para><keycap>
  Up          
</keycap></para></entry>
<entry><para>
  Moves up one line
</para></entry></row>

<row><entry><para><keycap>
  Down        
</keycap></para></entry>
<entry><para>
  Moves down one line
</para></entry></row>

<row><entry><para><keycap>
  PgUp        
</keycap></para></entry>
<entry><para>
  Moves up one page
</para></entry></row>

<row><entry><para><keycap>
    PgDn        
</keycap></para></entry>
<entry><para>
  Moves down one page
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  PgUp   
</keycap></keycombo></para></entry>
<entry><para>
  Moves to the beginning of the file
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  PgDn   
</keycap></keycombo></para></entry>
<entry><para>
  Moves to the end of the file
</para></entry></row>

<row><entry><para><keycap>
    Home        
</keycap></para></entry>
<entry><para>
  Moves to the beginning of the line
</para></entry></row>

<row><entry><para><keycap>
    End         
</keycap></para></entry>
<entry><para>
  Moves to the end of the line
</para></entry></row>

</tbody>
</tgroup>
</informaltable>

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

<informaltable>
<tgroup cols="2">
<tbody>

<row><entry><para><keycap>
  Backspace   
</keycap></para></entry>
<entry><para>
  Deletes one character left
</para></entry></row>

<row><entry><para><keycap>
  Delete      
</keycap></para></entry>
<entry><para>
  Deletes the character under the cursor
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  C
</keycap></keycombo></para></entry>
<entry><para>
  Copies the selected text to the clipboard
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  V
</keycap></keycombo></para></entry>
<entry><para>
  Pastes the selected text from the clipboard
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  X      
</keycap></keycombo></para></entry>
<entry><para>
  Deletes the selected text and puts it into the clipboard
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Ctrl
</keycap><keycap>
  Z        
</keycap></keycombo></para></entry>
<entry><para>
  Undo
</para></entry></row>

<row><entry><para><keycombo><keycap>
  Shift
</keycap><keycap>
  Ctrl
</keycap><keycap>
  Z  
</keycap></keycombo></para></entry>
<entry><para>
Redo
</para></entry></row>

</tbody>
</tgroup>
</informaltable>

</sect1> <!-- keyboardmapping -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="searchinggrepping">
<title>Searching and grepping</title>
<indexterm zone="searchinggrepping"><primary>searching</primary></indexterm>
<indexterm zone="searchinggrepping"><primary>finding</primary></indexterm>

<sect2 id="searching">
<title>Searching for text</title>

<para>
<keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo>- Find 
<keycombo><keycap>Ctrl</keycap><keycap>R</keycap></keycombo>- Replace
</para>

</sect2>
 

<sect2 id="isearch">
<title>ISearch</title>
<indexterm zone="isearch"><primary>isearch</primary></indexterm>
<indexterm zone="isearch"><primary>incremental search</primary></indexterm>
<indexterm zone="isearch"><primary>search</primary><secondary>incremental</secondary></indexterm>

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

</sect2>


<sect2 id="grep">
<title>Grep</title>
<indexterm zone="grep"><primary>search</primary><secondary>in files</secondary></indexterm>

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

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

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

<informaltable>
<tgroup cols="2">
<tbody>

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

</tbody>
</tgroup>
</informaltable>

<para>
Backreferences to bracketed subexpressions are also available by the notation
<literal>\n</literal>.
</para>

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

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

</sect2>

</sect1> <!-- searchinggrepping -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="newfiles">
<title>Creating new files and classes</title>

<para>
</para>

</sect1> <!-- newfiles -->

</chapter> <!-- editing -->

<!-- ====================================================================== -->

<chapter id="filebrowsers">
<title>The file browsers</title>

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

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

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

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

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

<figure id="screenshot-filetree" float="1">
<title>A screenshot of the file tree</title>
<mediaobject>
<imageobject><imagedata fileref="filetree.png"/></imageobject>
</mediaobject>
</figure>

</listitem>

<listitem>
<formalpara>
<title>File groups</title>
<para>
This shows the files belonging to the project, grouped by their file name 
extension. As in the file tree, you can edit a file by clicking on it
with the left mouse button.
</para>
</formalpara>

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

</listitem>

</itemizedlist>

</chapter> <!-- filebrowsers -->

<!-- ====================================================================== -->

<chapter id="classbrowser">
<title>The class browsers</title>
<indexterm zone="classbrowser"><primary>class browser</primary></indexterm>

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

<sect1 id="classview">
<title>Class view</title>

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

<figure id="screenshot-classview" float="1">
<title>A screenshot of the class view</title>
<mediaobject>
<imageobject><imagedata fileref="classview.png"/></imageobject>
</mediaobject>
</figure>

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

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

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

</sect1> <!-- classview -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="classtools">
<title>Class tools</title>

<para>
The class tool dialog is activated by right clicking on a class in the class
view and choosing <guimenuitem>Class tool...</guimenuitem>.
</para>

</sect1> <!-- classtools -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="classhierarchy">
<title>Class hierarchy</title>

<para>
</para>

</sect1> <!-- classhierarchy -->

</chapter> <!-- classbrowser -->

<!-- ====================================================================== -->

<chapter id="documentation">
<title>Documentation</title>

<para>
Documention unfortunately belongs to the most-overlooked programming issues. Yet, once properly set up and maintained internal and external documentation provides most valuable help.
</para>
<para>
Documentation has multiple facets. There is
<itemizedlist>
  <listitem><para>
  <emphasis>project internal documentation</emphasis>, mainly consisting of
  <itemizedlist>
    <listitem><para>
	<emphasis>comments</emphasis> in header/source files
	</para></listitem>
    <listitem><para>
	<emphasis>internal API documentation</emphasis> of your project generated from the program file by special tools, e.g. <application>Doxygen</application>
	</para></listitem>
  </itemizedlist>
  </para></listitem>
  <listitem><para>
  <emphasis>project external documentation</emphasis>, comprising among others
  <itemizedlist>
	<listitem><para>
	<emphasis>external API documentation</emphasis> of e.g. common system libraries (<application>KDE</application>, <application>Qt</application>, etc.)
	</para></listitem>
	<listitem><para>
	any other documentation (programming language manuals, general system information, HowTo articles and the like)
	</para></listitem>
  </itemizedlist>
  </para></listitem>
</itemizedlist>
</para>
<para>
All this documentation should be easily maintainable and ready at hand whenever you need it. &kdevelop; has provisions for just this.
</para>

<!-- ### doc browser, notes on internal documentation, how to profit from Doxygen -->

<sect1 id="docbrowser">
<title>The documentation browser</title>


<figure id="screenshot-doctreeview" float="1">
<title>A screenshot of the documentation tree</title>
<mediaobject>
<imageobject><imagedata fileref="doctreeview.png"/></imageobject>
</mediaobject>
</figure>

</sect1> <!-- docbrowser -->

</chapter> <!-- documentation -->

<!-- ====================================================================== -->

<chapter id="projectmanagement">
<title>Building and project management</title>

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

<para>
In <xref linkend="unixdev-buildsystems"/> we have given a rough overview of
the build systems commonly in use on UNIX systems. We now give a detailed
introduction into the project management modules supported by &kdevelop;
The most important one is the <command>autoproject</command> plugin which
serves as a frontend to the collection of scripts sometimes referred to as
GNU autotools (&automake;, &autoconf;, &libtool;). Almost all application
templates use this project management.
</para>

<para>
In addition, &kdevelop; contains the <command>customproject</command> plugin,
which can be used for projects for which you maintain your own
<filename>Makefiles</filename>, but also for projects that use the tool
<command>ant</command> which is very common in the Java world, or projects
using <command>qmake</command>.
</para>


<sect1 id="autoproject">
<title>Automake projects</title>
<indexterm zone="autoproject"><primary><command>autoproject</command></primary></indexterm>
<indexterm zone="autoproject"><primary>&automake;</primary></indexterm>
<indexterm zone="autoproject"><primary>&autoconf;</primary></indexterm>
<indexterm zone="autoproject"><primary>&libtool;</primary></indexterm>

<para>
</para>


<sect2 id="autoconf">
<title>Autoconf</title>
<indexterm zone="autoconf"><primary><filename>configure</filename> script</primary></indexterm>
<indexterm zone="autoconf"><primary><filename>config.status</filename> script</primary></indexterm>
<indexterm zone="autoconf"><primary><filename>Makefile.in</filename></primary></indexterm>
<indexterm zone="autoconf"><primary><filename>config.h.in</filename></primary></indexterm>

<figure id="flow-configure" float="1">
<title>Effect of the configure script</title>
<mediaobject>
<imageobject><imagedata fileref="configure.png"/></imageobject>
</mediaobject>
</figure>

<para>
<filename>Makefile.in</filename> into <filename>Makefile</filename>
</para>

<programlisting>
prefix = @prefix@
INSTALL = @INSTALL@
build_triplet = @build@
CXX = @CXX@
</programlisting>

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

<para>
<filename>config.h.in</filename> into <filename>config.h</filename>
</para>

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

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

</sect2>


<sect2 id="automake">
<title>Automake</title>

<para>
</para>

</sect2>


<sect2 id="automakemanager">
<title>KDevelop's automake manager</title>

<figure id="screenshot-automakemanager" float="1">
<title>A screenshot of the automake manager</title>
<mediaobject>
<imageobject><imagedata fileref="automakemanager.png"/></imageobject>
</mediaobject>
</figure>

</sect2>


<sect2 id="automakelibrary">
<title>Building and installing libraries</title>

<para>
<itemizedlist>
<listitem><para>
  -rpath
</para></listitem>
<listitem><para>
  PIC
</para></listitem>
<listitem><para>
  static
</para></listitem>
<listitem><para>
  plugins: no-undefined
</para></listitem>
</itemizedlist>
</para>

</sect2>

</sect1> <!-- autoproject -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="customproject">
<title>Custom makefiles and build scripts</title>
<indexterm zone="customproject"><primary><filename>Makefile</filename></primary></indexterm>
<indexterm zone="customproject"><primary><filename>build.xml</filename></primary></indexterm>

<para>
</para>

</sect1> <!-- customproject -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="compileroptions">
<title>Compiler options</title>

<para>
</para>

</sect1> <!-- compileroptions -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="makeoptions">
<title>Make options</title>

<para>
</para>

</sect1> <!-- makeoptions -->

</chapter> <!-- projectmanagement -->

<!-- ====================================================================== -->

<chapter id="advancedautoproject">
<title>Advanced autoproject usage</title>
<indexterm zone="advancedautoproject"><primary>&automake;</primary></indexterm>

<sect1 id="buildconfigurations">
<title>Multiple build configurations</title>
<indexterm zone="buildconfigurations"><primary>build configurations</primary><secondary>multiple</secondary></indexterm>

<para>

</para>

</sect1> <!-- buildconfigurations -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="crosscompiling">
<title>Cross-compiling</title>
<indexterm zone="crosscompiling"><primary>cross compiling</primary></indexterm>
<indexterm zone="crosscompiling"><primary>compiling</primary><secondary>cross</secondary></indexterm>
<indexterm zone="crosscompiling"><primary><option>--host</option></primary></indexterm>

<para>
When you have suitable cross compilers available, you can cross compile your
programs for processors and operating systems different from the system where
&kdevelop; and the compiler is running. The GNU compiler collection GCC can
be configured and compiled as a cross compiler if you compile it yourself.
Consult the <ulink url="info://gcc/Cross-Compiler">GCC info pages</ulink> for
more information. Some Linux distributions also provide binary packages.
</para>

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

<para><screen>
<option>--host=</option><replaceable>platform</replaceable>
</screen></para>

<para>
to the configure options. The <replaceable>platform</replaceable> name
is a tuple of the form
</para>

<programlisting>cpu-vendor-os</programlisting>
<para>or</para>
<programlisting>cpu-vendor-kernel-os</programlisting>

<para>
For many combinations, you can use a short form, for instance
<wordasword>i386-linux</wordasword> or <wordasword>arm-elf</wordasword>.
</para>

</sect1> <!-- crosscompiling -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="qtembedded">
<title>Qt/Embedded</title>
<indexterm zone="qtembedded"><primary>embedded</primary><secondary>Qt</secondary></indexterm>
<indexterm zone="qtembedded"><primary>Qt/Embedded</primary></indexterm>
<indexterm zone="qtembedded"><primary>Qtopia</primary></indexterm>
<indexterm zone="qtembedded"><primary>framebuffer</primary></indexterm>

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

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

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

<para><screen><command>
app <option>-qws</option> <option>-display QVFb:0</option>
</command></screen></para>

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

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

</sect1> <!-- qtembedded -->

</chapter> <!-- advancedautoproject -->

<!-- ====================================================================== -->

<chapter id="debugger">
<title>The debugger interface</title>
<indexterm zone="debugger"><primary>debugger</primary></indexterm>

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

<itemizedlist>
<listitem>
<para>
With <menuchoice><guimenu>Debug</guimenu><guimenuitem>Start</guimenuitem></menuchoice>,
the main program of your project is loaded into the debugger.
</para>
</listitem>

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

<listitem>
<para>
With <menuchoice><guimenu>Debug</guimenu>
<guimenuitem>Start (other)</guimenuitem>
<guimenuitem>Attach to process</guimenuitem></menuchoice> you invoke the
debugger on an already running program. You will be shown a
process list where you can select the process which the debugger
should take over.
</para>
</listitem>

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

<para>
The debugger frontend offers several views "into" the process:
</para>

<itemizedlist>
<listitem>
<formalpara>
<title>Variables</title>
<indexterm zone="debugger"><primary>watch variables</primary></indexterm>
<para>
This window lists the values of all local variables at the current execution
point of the program. It covers the variables in the complete call stack,
i.e.  the function where the process was interrupted, the function that called
this function, and so on up to <function>main()</function> function.
</para>
</formalpara>

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

<listitem>
<formalpara>
<title>Breakpoints</title>
<indexterm zone="debugger"><primary>breakpoints</primary></indexterm>
<para>
</para>
</formalpara>
</listitem>

<listitem>
<formalpara>
<title>Frame stack</title>
<indexterm zone="debugger"><primary>frame stack</primary></indexterm>
<para>
</para>
</formalpara>
</listitem>

<listitem>
<formalpara>
<title>Disassemble</title>
<indexterm zone="debugger"><primary>disassemble</primary></indexterm>
<para>
</para>
</formalpara>
</listitem>

</itemizedlist>


<sect1 id="settingbreakpoints">
<title>Setting breakpoints</title>

<para>
</para>

</sect1> <!-- settingbreakpoints -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id ="debuggeroptions">
<title>Options</title>

<formalpara>
<title>Display mangled names</title>
<indexterm zone="debugger"><primary>name mangling</primary></indexterm>
<indexterm zone="debugger"><primary>mangling</primary><secondary>name</secondary></indexterm>

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

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

<formalpara>
<title>Try setting BPs on lib load</title>
<indexterm zone="debugger"><primary>lazy breakpoints</primary></indexterm>
<indexterm zone="debugger"><primary>breakpoints</primary><secondary>lazy</secondary></indexterm>

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

<formalpara>
<title>Enable floating toolbar</title>
<indexterm zone="debugger"><primary>debugger toolbar</primary></indexterm>
<indexterm zone="debugger"><primary>toolbar</primary><secondary>debugger</secondary></indexterm>

<para>
</para>
</formalpara>

</sect1> <!-- debuggeroptions -->

</chapter> <!-- debugger -->

<!-- ====================================================================== -->
<!-- ### Questionable, if not IDE-specific.
<chapter id="python">
<title>Python</title>

<para>
</para>

</chapter> --> <!-- python -->

<!-- ====================================================================== -->
<!-- ### Questionable, if not IDE-specific.
<chapter id="php">
<title>PHP</title>

<para>
</para>
</chapter> --> <!-- php -->

<!-- ====================================================================== -->

<chapter id="cvs">
<title>Using CVS</title>
<indexterm zone="cvs"><primary>CVS</primary></indexterm>
<indexterm zone="cvs"><primary>revision control</primary></indexterm>

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

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

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

<para>
&CVS; is implemented as a client-server system. As a user, all communication
with the repository goes through the command line program &cvs;. A higher
level user interface is available through frontends like 
<application>Cervisia</application> (<ulink url="http://cervisia.sf.net"/>)
or <application>TkCVS</application> (<ulink url="http://tkcvs.sf.net"/>).
In &kdevelop;, only a small part of the &cvs; functionality which is
important for your daily work can be used directly.
</para>

<para>
Basic knowledge of &CVS; usage is assumed. In particular, you should know 
how to checkout a given project from the repository. We recommend the
book "Open Source Development With CVS" by Karl Fogel which is freely
distributed (except for the non-technical chapters). See
<ulink url="http://cvsbook.red-bean.com/cvsbook.html"/>.
</para>

<para>
In the file views, the following context menu items are available:
</para>

<itemizedlist>

<listitem>
<formalpara>
<title>Add to repository</title>
<para>Prepares the marked file for addition to the repository. The file
is transferred to the repository when you commit it (or the containing
directory) the next time.
</para>
</formalpara>
</listitem>

<listitem>
<formalpara>
<title>Remove from repository</title>
<para>
Prepares a file for removal from the repository. This also deletes
the file on the local file system, so use this feature with care!
</para>
</formalpara>
</listitem>

<listitem>
<formalpara>
<title>Update</title>
<para>
Runs <command>cvs update</command> to merge any changes from other
users into your working directory. When you use this menu item over
a directory, the update normally happens recursively, except if you
have disabled this in the configuration file <filename>.cvsrc</filename>.
</para>
</formalpara>
</listitem>

<listitem>
<formalpara>
<title>Commit</title>
<para>
Runs <command>cvs commit</command> to upload any locally made changes
to the repository. Note that you should update before doing this.
Otherwise, when another user has committed his own changes before,
&CVS; may give you an error message.
</para>
</formalpara>
</listitem>

</itemizedlist>

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

</chapter> <!-- cvs -->

<!-- ====================================================================== -->

<chapter id="externalprogs">
<title>Leveraging external programs</title>
<indexterm zone="externalprogs"><primary>programs</primary><secondary>external</secondary></indexterm>

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

<para>
The most general and simple feature of this kind is the tool menu, which you
can freely configure. This is done in the <menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure KDevelop...</guimenuitem></menuchoice>.
dialog under <guibutton>External tools</guibutton>.
</para>

<para>
Other tools will be discussed in the chapter <xref linkend="plugintools"/>.
</para>

</chapter> <!-- externalprogs -->

<!-- ====================================================================== -->

<chapter id="plugintools">
<title>Plugin tools</title>
<indexterm zone="plugintools"><primary>plugins</primary></indexterm>

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

<itemizedlist>
<listitem>
<formalpara>
<title>The abbrev plugin</title>
<indexterm zone="plugintools"><primary><command>abbrev</command></primary></indexterm>

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

<para>
The set of code templates is configurable. You can see
which ones are available in the <menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure KDevelop...</guimenuitem></menuchoice>
dialog under <guibutton>Abbreviations</guibutton>
</para>
</listitem>

<listitem>
<formalpara>
<title>The filter plugin</title>
<indexterm zone="plugintools"><primary><command>filter</command></primary></indexterm>

<para>
This offers two features. If you select <menuchoice><guimenu>Tools</guimenu>
<guimenuitem>Execute command</guimenuitem></menuchoice>, you can enter a shell
command. The output of this command is inserted into the editor buffer when
you hit the <guibutton>Start</guibutton> button.
</para>
</formalpara>

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

<listitem>
<formalpara>
<title>The doxygen plugin</title>
<indexterm zone="plugintools"><primary>&doxygen;</primary></indexterm>
<indexterm zone="plugintools"><primary>documentation tool</primary></indexterm>
<indexterm zone="plugintools"><primary>API documentation</primary></indexterm>

<para>
This one helps you to use the &doxygen; API documentation tool 
(<ulink url="http://www.doxygen.org"/>). You can select 
<menuchoice><guimenu>Project</guimenu>
<guimenuitem>Run Doxygen</guimenuitem></menuchoice> to generate API 
documentation for your current project, based on the configuration given by 
the file <filename>Doxyfile</filename> in your project directory.
</para>
</formalpara>

<para>
Furthermore, you can configure &doxygen; in the
<menuchoice><guimenu>Project</guimenu>
<guimenuitem>Project options...</guimenuitem></menuchoice> dialog. This dialog
is very similar to the &doxywizard; tool.
</para>
</listitem>

<listitem>
<formalpara>
<title>The ctags plugin</title>
<indexterm zone="plugintools"><primary>&ctags;</primary></indexterm>

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

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

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

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

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

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

<listitem>
<formalpara>
<title>The astyle plugin</title>
<indexterm zone="plugintools"><primary><command>astyle</command></primary></indexterm>
<indexterm zone="plugintools"><primary><application>Artistic Style</application></primary></indexterm>
<indexterm zone="plugintools"><primary>indentation</primary></indexterm>

<para>
</para>
</formalpara>
</listitem>

<listitem>
<formalpara>
<title>The regexptest plugin</title>
<indexterm zone="plugintools"><primary><command>regexptest</command></primary></indexterm>
<indexterm zone="plugintools"><primary>debugging</primary><secondary>regular expressions</secondary></indexterm>
<indexterm zone="plugintools"><primary>regular expressions</primary><secondary>debugging</secondary></indexterm>

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

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

<para>
When you enter an expression, you get immediate feedback about any syntax
errors in it. By entering a text under <guilabel>Test string</guilabel>,
you can see whether the expression matches this string. In particular, if
your regular expression includes groups, such as <literal>"([a-z])"</literal>,
the content of the matched subgroups will be shown in a list box.
</para>
</listitem>
  
<listitem>
<formalpara>
<title>The konsole plugin</title>
<indexterm zone="plugintools"><primary><command>konsole</command></primary></indexterm>
<indexterm zone="plugintools"><primary>terminal</primary><secondary>embedded</secondary></indexterm>

<para>
</para>
</formalpara>
</listitem>

</itemizedlist>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="parts-overview">
<title>Overview</title>

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

<para>
Some of the parts are considered <link linkend="table-global-parts">global</link> - that is, they effect the entire operation of &kdevelop;. For example, the uimode part allows a developer to select which user interface they wish to use.
</para>

<para>
Other parts are <link linkend="table-project-parts">project specfic</link>, and are only utilized when a project of that type is loaded.  The Automake Manager, for example, only needs to be active when an Automake based project is currently loaded.  Otherwise, this part will not be active.
</para>

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

<table id="table-project-parts">
<title>Project management parts in &kdevelop;</title>

<tgroup cols="2"><tbody>
<row>
  <entry>antproject</entry>
  <entry>ANT Project Manager (Java applications)</entry>
</row>
<row>
  <entry>autoproject</entry>
  <entry>Automake Project Manager</entry>
</row>
<row>
  <entry>customproject</entry>
  <entry>Custom Project Manager</entry>
</row>
<row>
  <entry>trollproject</entry>
  <entry>QMake based Project Manager</entry>
</row>
</tbody></tgroup>
</table>

<table id="table-global-parts">
<title>Global parts in &kdevelop;</title>

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

<table>
<title>Language support parts in &kdevelop;</title>
<tgroup cols="2">
<tbody>
<row><entry>cppsupport</entry><entry>Support for C/C++</entry></row>
<row><entry>fortransupport</entry><entry>Support for Fortran</entry></row>
<row><entry>javasupport</entry><entry>Support for Java</entry></row>
<row><entry>perlsupport</entry><entry>Support for Perl</entry></row>
<row><entry>phpsupport</entry><entry>Support for PHP</entry></row>
<row><entry>pythonsupport</entry><entry>Support for Python</entry></row>
</tbody></tgroup>
</table>

<table>
<title>Project specific parts in &kdevelop;</title>
<tgroup cols="2"><tbody>
<row><entry>astyle</entry><entry></entry></row>
<row><entry>buglist</entry><entry></entry></row>
<row><entry>classview</entry><entry>Classview Manager</entry></row>
<row><entry>ctags</entry><entry></entry></row>
<row><entry>debugger</entry><entry>GNU Debugger Manager</entry></row>
<row><entry>diff</entry><entry></entry></row>
<row><entry>distpart</entry><entry></entry></row>
<row><entry>doxygen</entry><entry></entry></row>
<row><entry>fileview</entry><entry></entry></row>
<row><entry>javadebugger</entry><entry></entry></row>
<row><entry>manager</entry><entry></entry></row>
<row><entry>nedit</entry><entry></entry></row>
<row><entry>outputviews</entry><entry></entry></row>
<row><entry>perforce</entry><entry></entry></row>
<row><entry>qeditor</entry><entry></entry></row>
<row><entry>scripting</entry><entry></entry></row>
<row><entry>scriptproject</entry><entry></entry></row>
<row><entry>sourcenav</entry><entry></entry></row>
<row><entry>svn</entry><entry></entry></row>
<row><entry>visualboyadvance</entry><entry></entry></row>
<row><entry>windowmenu</entry><entry></entry></row>
</tbody></tgroup>
</table>

</sect1> <!-- parts-overview -->

</chapter> <!-- plugintools -->

<!-- ====================================================================== -->

<appendix id="app-uimodes-examples">
<title>&kdevelop; user interface mode examples</title>

<sect1 id="mdi-desc">
<title>Child frame windows mode</title>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
    <imagedata fileref="gideon-mdi-mode.png" format="PNG"/>
    </imageobject>
    <textobject><phrase>Screenshot</phrase></textobject>
	<caption><para>&kdevelop; child frame windows mode</para></caption>
  </mediaobject>
</screenshot>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

</sect1> <!-- mdi-desc -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="tabbed-desc">
<title>Tabbed pages mode</title>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="gideon-tabbed-mode.png" format="PNG"/>
    </imageobject>
    <textobject><phrase>Screenshot</phrase></textobject>
	<caption><para>&kdevelop; tabbed pages mode</para></caption>
  </mediaobject>
</screenshot>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

</sect1> <!-- tabbed-desc -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="toplevel-desc">
<title>Toplevel windows mode</title>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="gideon-toplevel-mode.png" format="PNG"/>
    </imageobject>
    <textobject><phrase>Screenshot</phrase></textobject>
	<caption><para>&kdevelop; toplevel windows mode</para></caption>
  </mediaobject>
</screenshot>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

</sect1> <!-- toplevel-desc -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="ideal-desc">
<title>IDEAl mode</title>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

<screenshot>
  <mediaobject>
    <imageobject>
      <imagedata fileref="gideon-ideal-mode.png" format="PNG"/>
    </imageobject>
    <textobject><phrase>Screenshot</phrase></textobject>
	<caption><para>&kdevelop; IDEAl mode</para></caption>
  </mediaobject>
</screenshot>

<para>
Click <link linkend="uimodes-overview">here</link> to return to the modes overview.
</para>

</sect1> <!-- ideal-desc -->

</appendix>

<!-- ====================================================================== -->

<appendix id="app-misc-info">
<title>Further information</title>
<sect1 id="gettinginformation">
<title>Getting information</title>
<para>
</para>
</sect1> <!-- gettinginformation -->

<sect1 id="app-reporting-bugs">
<title>Reporting bugs</title>
<para>
</para>
</sect1> <!-- app-reporting-bugs -->

<sect1 id="app-licensing">
<title>Licensing</title>
&underFDL;
&underGPL;
</sect1> <!-- app-licensing -->
</appendix>

<!-- ====================================================================== -->

<appendix id="app-changelog">
<title>Changes</title>
<sect1 id="changes">
<title>Changes to this document</title>
<para>
<itemizedlist>
<listitem><para>
2003-01-03 - Started this Changelog
</para></listitem>
</itemizedlist>
</para>
</sect1> <!-- changes -->
</appendix>

<!-- ====================================================================== -->

<!--  Note (bp, 2003-09-04): <bibliography> should remain the last appendix section because of a (meinproc???) bug which sends the Next selection in circles back to it. -->

<appendix id="app-bibliography">
<title>Bibliography</title>

<bibliography>

<biblioentry>
<title><ulink url="info://make/Top">GNU Make Manual</ulink></title>
<authorgroup>
<author><firstname>Richard M.</firstname><surname>Stallman</surname></author>
<author><firstname>Roland</firstname><surname>McGrath</surname></author>
</authorgroup>
</biblioentry>

<biblioentry>
<title><ulink url="info://automake/Top">GNU Automake</ulink></title>
<authorgroup>
<author><firstname>David</firstname><surname>MacKenzie</surname></author>
<author><firstname>Tom</firstname><surname>Tromey</surname></author>
</authorgroup>
</biblioentry>

<biblioentry>
<title><ulink url="info://autoconf/Top">GNU Autoconf</ulink></title>
<authorgroup>
<author><firstname>David</firstname><surname>MacKenzie</surname></author>
<author><firstname>Ben</firstname><surname>Elliston</surname></author>
</authorgroup>
</biblioentry>

<biblioentry>
<title><ulink url="info://gcc/Top">Using the GNU Compiler Collection</ulink></title>
<author><firstname>Richard M.</firstname><surname>Stallman</surname></author>
</biblioentry>

<biblioentry>
<title><ulink url="info://libtool/Top">GNU Libtool</ulink></title>
<authorgroup>
<author><firstname>Gordon</firstname><surname>Matzigkeit</surname></author>
<author><firstname>Alexandre</firstname><surname>Oliva</surname></author>
<author><firstname>Thomas</firstname><surname>Tanner</surname></author>
<author><firstname>Gary V.</firstname><surname>Vaughan</surname></author>
</authorgroup>
</biblioentry>

<biblioentry>
<title>GNU Autoconf, Automake, and Libtool</title>
<edition>1st edition</edition>
<pubdate>October 2000</pubdate>
<authorgroup>
<author><firstname>Gary V.</firstname><surname>Vaughan</surname></author>
<author><firstname>Ben</firstname><surname>Elliston</surname></author>
<author><firstname>Tom</firstname><surname>Tromey</surname></author>
<author><firstname>Ian Lance</firstname><surname>Taylor</surname></author>
</authorgroup>
<publisher><publishername>New Riders Publishing</publishername></publisher>
<isbn>ISBN 1578701902</isbn>
</biblioentry>


<biblioentry>
<title>Advanced Programming in the UNIX(R) Environment</title>
<edition>1st edition</edition>
<pubdate>June 1992</pubdate>
<author><firstname>W. Richard</firstname><surname>Stevens</surname></author>
<publisher><publishername>Addison-Wesley Pub Co</publishername></publisher>
<isbn>ISBN 0201563177</isbn>
</biblioentry>

<biblioentry>
<title>Thinking in C++, Volume 1: Introduction to Standard C++</title>
<edition>2nd Edition</edition>
<pubdate>April 15, 2000</pubdate>
<author><firstname>Bruce</firstname><surname>Eckel</surname></author>
<publisher><publishername>Prentice Hall</publishername></publisher>
<isbn>ISBN 0139798099</isbn>
</biblioentry>

<biblioentry>
<title>Open Source Development with CVS</title>
<edition>2nd Edition</edition>
<pubdate>October 12, 2001</pubdate>
<authorgroup>
<author><firstname>Karl</firstname><surname>Fogel</surname></author>
<author><firstname>Moshe</firstname><surname>Bar</surname></author>
</authorgroup>
<publisher><publishername>The Coriolis Group</publishername></publisher>
<isbn>ISBN 158880173X</isbn>
</biblioentry>

<biblioentry>
<title>Programming PHP</title>
<edition>1st edition</edition>
<pubdate>March 2002</pubdate>
<authorgroup>
<author><firstname>Rasmus</firstname><surname>Lerdorf</surname></author>
<author><firstname>Kevin</firstname><surname>Tatroe</surname></author>
</authorgroup>
<publisher><publishername>O'Reilly &amp; Associates</publishername></publisher>
<isbn>ISBN 1565926102</isbn>
</biblioentry>

<biblioentry>
<title>Programming Python</title>
<edition>2nd Edition</edition>
<pubdate>March 2001</pubdate>
<author><firstname>Mark</firstname><surname>Lutz</surname></author>
<publisher><publishername>O'Reilly &amp; Associates</publishername></publisher>
<isbn>ISBN 0596000855</isbn>
</biblioentry>

<biblioentry>
<title>Gui Programming With Python : Using the Qt Toolkit</title>
<edition>Bk&amp;Cd-r edition</edition>
<pubdate>January 2002</pubdate>
<author><firstname>Boudewijn</firstname><surname>Rempt</surname></author>
<publisher><publishername>Opendocs Llc</publishername></publisher>
<isbn>ISBN 0970033044</isbn>
</biblioentry>

<biblioentry>
<title>Programming Perl</title>
<subtitle>The Camel book</subtitle>
<edition>3rd Edition</edition>
<pubdate>July 2000</pubdate>
<authorgroup>
<author><firstname>Larry</firstname><surname>Wall</surname></author>
<author><firstname>Tom</firstname><surname>Christiansen</surname></author>
<author><firstname>Jon</firstname><surname>Orwant</surname></author>
</authorgroup>
<publisher><publishername>O'Reilly &amp; Associates</publishername></publisher>
<isbn>ISBN 0596000278</isbn>
</biblioentry>

<biblioentry>
<title>Learning Perl</title>
<subtitle>The Lama book</subtitle>
<edition>3rd Edition</edition>
<pubdate>July 15, 2001</pubdate>
<authorgroup>
<author><firstname>Randal L.</firstname><surname>Schwartz</surname></author>
<author><firstname>Tom</firstname><surname>Phoenix</surname></author>
</authorgroup>
<publisher><publishername>O'Reilly &amp; Associates</publishername></publisher>
<isbn>ISBN 0596001320</isbn>
</biblioentry>

</bibliography>

<para>
<!-- (dummy paragraph to get DTD right) -->
</para>

</appendix>

<!-- ====================================================================== -->

<index id="app-index"/>

</book>
