The User Manual to KDevelop: Projects

Next Previous Table of Contents

### 8. Projects

### 8.1 Projecttypes

#### Programs

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

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

- a single document interface (SDI) KDE-application including a menubar, a toolbar and a statusbar. It contains basic control resource management to allow extending the frame application into a unique KDE application. The application frame also contains statusbar help messages as known from commercial products just like KDevelop itself. From the programmer's point of view, it is based on three application-specific classes leaning on the MVC-concept (Model-View-Controller). Technically, the base classes may not be viewed that way, but it's construction is at least created most logical to create applications with a GUI.
- a KDE-based application frame window. This application type offers most flexibility to those wanting to develop their program from scratch, but can also be used as a basis for developing wizard applications or modules.
- a Qt-only based program framework. For those programmers who want to use the Qt-library as the GUI interface alone, we tried to offer you a smart framework to support your application development. As Qt programming is fully supported, you should have no problems to create a full-functional application by using Qt only.
- a C++ program framework. This application type is intended for those wanting to write a terminal based C++ program. Just remove the "Hello World" line in main() and construct your classes the same way with KDevelop as for KDE applications.
- a C program framework for C programmers. This is as well a terminal based application but only uses the C compiler.

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

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

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

Mind that KDevelop does not write any information into Makefiles or configuration files. You are responsible for any project behavior and build settings yourself.

#### Libraries

A general project-type to create libraries is not available at the moment. Anyway, building libraries is not impossible with KDevelop. Here are a few guidelines and workarounds:

- Whenever your project subdirectory gets another subdirectory that contains source files, KDevelop will build a static library of these. That means static libraries are already supported by automatic creation in order to sort project sourcefiles. Mind that the static library is part of the binary later and won't get installed.
- to create a shared library KDevelop offers an easy way to turn a such created static library into a shared: Open the RFV on the left of KDevelopīs main window and browse to the created subdirectory. There, use the right mouse button over the subdirectory. The popup-menu offers the following options:
  - update Makefile.am
  - change to static lib
  - change to shared lib
  Use "change to shared lib" to convert the default generated static library into a shared one. You can reverse your decision later if you decide that using it as a static library will work as well for your project- just do the same steps again and select "change to static lib".

#### Multiple Targets

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

Another way to still work with this type and to still have access to the binaries themselves are creating empty projects and move their subdirectories in conjunction with the project files to the directory containing all sources later. Then you could load each target independently by its project file; this also allows executing and debugging the target.

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

- add your target to the bin_PROGRAMS if it is an executable
- add your library declaration line if it is a shared library
- add the same declarations like the original project binary is build:
  - newtarget_METASOURCES
  - newtarget_LD_FLAGS
  - DISTCLEANFILES
  - copy the messages: entry for the original binary and replace target_SOURCES with newtarget_SOURCES, target.pot with newtarget.pot
- add your sources like the KDevelop write area contains outside the write area for your binary or library
- for installing static libraries, create the library with KDevelop's auto-creation inside subdirectories. Then modify the Makefile.am outside the write area according to the needed settings

### 8.2 New Projects

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

For KDE applications there are six different frameworks:

- Mini: Creates a KDE-application with an empty main widget.
- Normal: Creates a KDE-application with session-management, menubar, toolbar, statusbar and support for a document-view codeframe model.
- Normal-OpenGL: Creates a KDE-application with session-management, menubar, toolbar, statusbar and support for a document-view codeframe model. OpenGL(tm) (Mesa3D) support is added.
- KDE 2 Normal: Creates a KDE-2 application with session-management, menubar, toolbar, statusbar and support for a document-view codeframe model.
- KDE 2 Mini: Creates a KDE-2 application with an empty main widget.
- KDE 2 MDI: Creates a KDE-2 MDI (Multiple Document Interface) application with menubar, toolbar, statusbar and support for a document-view codeframe model.

If you wish no dependencies towards the KDE-libraries for end-users, you can choose from four Qt-only types:

- Normal: Creates a Qt-Application with a main window containing a menubar, toolbar and statusbar, including support for a generic document-view model.
- QT 2.x SDI: Creates a Qt-2.x Application with a main window containing a menubar, toolbar and statusbar, including support for a single document-view interface (SDI) model.
- QT 2.1 MDI: Creates a Qt-2.1 Application with a main window containing a menubar, toolbar and statusbar, including support for a multiple document interface (MDI) model.
- QextMDI: Creates an MDI framework based on the QextMDI library and Qt2.0x. Allows to switch between both modes, Toplevel and Childframe. Requires the QextMDI library, see http://www.geocities.com/gigafalk/qextmdi.htm for more information.

Mind that the Qt 2 normal and Qt 2 MDI template make use of the KDE autoconf/automake system. This enables you to convert your existing Qt-only application into a KDE application easily as the automatic checks for needed KDE libraries and header files can be added with little change on the project; see section Project Hacking for more information.

These two Qt templates also enable you to internationalize the GUI of your application by integrating Qt Linguist. The way to handle KDevelop for adding languages is identical to KDE projects.

Further, the Application Wizard offers a template for creating GNOME-compliant applications with the GTK+ C-library with a ready-to-run mainwindow containing a menubar, toolbar and statusbar. The two C and C++ -Application types offer a framework for creating commandline applications.

And last but not least you can create an empty projekt, e.g. to work with existing projects.

The wizard asks for your project name, version and the location where the project directory will be build. Further, your Name and Email address are asked for inserting them in header and cpp templates on top of your source files as well as for entries in the *.lsm file.

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

### 8.3 Opening and Closing of Projects

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

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

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

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

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

### 8.4 Editing a Project

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

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

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

#### Adding and Removing Files and Classes

Adding a new file is often used when you think that you should separate your class implementation file into several ones. Then you need to create an new file which will contain the part of the class implementation you want to move. You can do this by choosing "New" from the "File"-menu, opening the "New File" dialog. This enables you to specify the file-type, name and the location. When entering the filename, KDevelop automatically enters the extension for you, but you can as well change the extensions towards your own preferences. Further, you can include the header template for sourcefiles, so you don't have to copy this into your new file yourself. Also, you can decide, if the file is included in the project or not. Mind that this doesn't cover the installation destination; this has to be configured later by setting the file preferences.

After the new file has been created, the project file will be updated as well as the according Makefile.am's. To add a complete class to your project, you can construct a new class with the Classgenerator which is invoked by "New Class" from the Project-menu.

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

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

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

#### Setting Project File Options

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

#### Adding Translations

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

First, you have to enclose all visible strings of your application that appear in bars or dialogs with the `i18n()` macro. This macro is a replacement for the function `klocale->translate()` of the KLocale class and much easier to use. As this macro is declared in the `kapp.h` include file, you have to add `#include <kapp.h>` to the source file or the class declaration file of the class that makes use of the macro. Also it should be mentioned, that although `i18n()` is a macro and therefore you could think about using the original function, this won't work because the strings that are set up for translation have to be read out of the sources and get stored in the application's translation file (<YourApp>.pot in the /po subdirectory). This task is done by the program xgettext, and to do this, you would enter `make messages` in your project directory containing the sources. As xgettext depends on the `i18n()` macro, the original function won't do the job.

For translations themselves, you first have to create the message file containing all strings that are used in your sources with the `i18n()` macro. This can be done by choosing "Make messages and merge" from the Build-menu. Then you have to add the languages that your application wants to support. Therefore, select "Add Translation File" from the Project-menu. This opens a language selection dialog. Select the language and press OK. This will build the ASCII file containing entries for the filename of the string and the line where the original string is placed. Then you will see a `msgid` line containing the string to translate, followed by `msgstr`. The msgstr line is mostly empty except for the translations already provided by the KDE-libraries. Those have to be filled with the according translations of your language.

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

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

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

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

#### Internationalization of KDE 2.0 Applications

KDE 2.0 projects have a slightly different handling of adding po files and keeping them up-to-date than KDE 1.x projects.

The first thing to watch out is that when generating a new KDE 2.0 project, make package-messages is called from the base directory of your project in opposition to make messages in the projectīs subdirectory in KDE 1.x applications. While merging strings is done with calling make merge in the po directory in KDE 1, this is called automatically `within` make package-messages - resulting in an error message even while creating your project with the application wizard.

Another issue to watch out is that KDevelop installs a script called extractrc into your $KDEDIR/bin directory. This script is originally located in the KDE CVS module kdesdk/scripts and is called automatically within make package-messages, if your Makefile.am contains the line `messages:rc.cpp` instead of `messages:`. This is the default for the KDE 2 normal and KDE 2 MDI project type, the KDE 2 mini only uses `messages:`.

What it does actually is extracting the strings out of your XML resource file to build the applicationīs GUI, which is called <yourapp>ui.rc, and stores these stings in a temporary rc.cpp file that gets processed while building the pot-file to include these strings into your internationalization.

However, if you intend to build a KDE 2.0 application based on the KDE 2 mini template, change the Makefile.am in this section, there are already comments in it what to change where.

#### Internationalization of Qt 2.2.x applications

Since Qt includes the tr() method together with the QTranslator class in Qt 2.x, you can easily internationalize your Qt-only project as well. KDevelop 1.4 supports this by using the tools that come with Qtīs Linguist: lupdate and lrelease. The strings used with tr() are read into language-dependent *.ts files by lupdate; lrelease then converts the translated XML file to a file *.qm which stores the translations as binary information. You can add each language automatically within KDevelop, just use the same way as for KDE projects. The *.ts files are stored in the LFV-Folder "Translations" automatically and Linugist is called when selecting them in the LFV and the RFV.

#### Extending the Project Documentation

All projects created with KDevelop contain a pre-configured documentation, which already contains standard chapters for installation, project name and version as well as the author name and email-address. As KDevelop uses SGML-templates, it's very easy to extend the documentation to a full descriptive helpsystem. The only thing you have to do is editing the SGML file, placed in docs/en as index.sgml. The reference documentation included with your sgml-tools package can be added to the Helpbrowser and allow you direct access to special tags as well as a short description of how to extend the documentation. SGML has a lot of advantages, whereas KDE makes wide use by this documentation type with the additional KSgml2Html tool. This creates the typical KDE-style documentation and makes it look nicer. Anyway, the sgmltools alone are enough to produce a html output that is already included in your application. To create the documents using KSgml2Html, install the tool and run "Make User-Manual" from the Build-menu. The Documentation Browser allows a direct controlling of the output by selecting "Project User-Manual" from the Help-menu or the according icon in the DOC-tree. Then you can browse the documentation online in KDevelop and have a better overview by the output over errors that result in missing tags.

Now, while extending the documentation, you can't avoid that additional files are produced that have to be included into the project as each `sect`-tag creates a new HTML file. The output generated by the KAppWizard is already included in the project, so you don't have to care for their installation path. What you have to watch out for is any index-xx.html file, where xx is higher than 6 (as the first six pages are already included in the project). After generating the documentation, switch to the RFV and browse to your documentation directory. Press the right mouse button over the files to add and select "Add". Further, KSgml2Html adds the KDE logo to the documentation directory. This file, `logotp3.gif`, has to be added to the project as well. Then you have to select the "File Properties" either from the Project menu or by the popup menu in the file-viewers. The easiest way to set the installation path is to select a documentation file already set up for installation such as `index.html`. You see that `Install` is checked and the Installdir+filename already contains the destination. Mark the Installdir and enter CTRL+C to copy the installation path to the clipboard. Then select the file you want to specify for installation. Enable `Install`, this will enable the installdir-entry field, already containing the filename. Place the cursor in front of the filename and enter CTRL+V to insert the clipboard contents (which was the installation path copied before). This is the fastest way to specify the installation path. For more options about specifying installation destinations, see The KDevelop Programming Handbook.

### 8.5 Project Hacking

When working with a project, you should never edit the project file by hand. This will prevent KDevelop from loading your project correctly under certain circumstances, as well as changes will not result in updating the Makefiles. To change any settings for your project, you have to use the given menu entries like e.g. for adding files or setting file properties. For experts that are not comfortable with certain options for e.g. the Linker or need additional project configuration, you should work yourself into the Makefile.am macros and add all changes in the Makefile.am's after the section separated with the entry "KDevelop write area". As the GNU-tools are using the commands at the end of all macro files, you can overwrite KDevelop's settings with this. Mind that this will prevent using KDevelop for any changes related to project configuration.

#### Project Type Definitions

KDevelopsī project files stores the project information in the style of readable KDE config files. You can find the according sections therefore easily youīre looking for. Now, to convert an existing project to another project typ can shorten the time to port an existing KDE 1.x project over to KDE 2 (which counts as well for Qt). Just change the following section with the according project tpe:

> `

>     [General]
>     author=Ralf Nolden
>     project_type=normal_kde2

> `

Valid project tpes are:

- `normal_empty`: Custom Project
- `normal_kde`: KDE 1.x Normal (SDI) Project
- `mini_kde`: KDE 1.x Mini Project
- `normalogl_kde`: KDE 1.x OpenGL Project
- `normal_kde2`: KDE 2.0 Normal (SDI) Project
- `mini_kde2`: KDE 2.0 Mini Project
- `mdi_kde2`: KDE 2.0 MDI Project
- `normal_qt`: Qt-1.44 Project (SDI)
- `normal_qt2`: Qt-2.2.x Project (SDI)
- `mdi_qt2`: Qt-2.2.x Project (MDI, uses QWorkspace)
- `mdi_qextmdi`: Qt-2.x Project (uses the QextMDI library)

#### Qt Designer

Another hint may be of good use when developing KDE 2.0/ Qt 2.2.x applications using the Qt Designer to create user interfaces. The ui files get added by KDevelop to the _SOURCES line in the Makefile.am of the subdirectory containing the ui file. This may result in the scenario that you want to include the header file of the generated dialog which may not exist yet when your file that includes it gets compiled as the uic (Qt user interface compiler) generates the C++ output. However, the am_edit file will resolve all dependencies for you, so you donīt have to worry about that.

#### Converting *.kdevdlg files

KDevelop 1.4 comes with a converter script `kdevdlg2ui` to turn already constructed dialogs with itīs internal dialogeditor into a *.ui file. However, you should be aware that you may have to re-inherit from your class that is generated by Qtīs uic and add your implementations from your former KDevelop dialog there. The converter script is mainly used to convert the dialogsī user interface, not your methods, signals or slots. So, re-editing the converted *.ui file may be necessary as well as inheriting from itīs generated class. Existing KDE 1.x applications canīt make use of *.ui files, therefore generate a new framework for your KDE 2/Qt2 application and move over your implemtation, *.kdevprj and Makefile.amīs of your subdirectories.

### 8.6 Compiler and Linker Flags for Projects

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

### 8.7 External Projects

Existing automake/autoconf compatible projects (which make use of Makefile.amīs to store their information) can be used together with KDevelop by creating a KDevelop project file with the kimport script. After the project file has been build up, you should edit it with your favorite editor and set the project type accoding to your needs, see Project Hacking for more details about available project types. Mind that you should deselect "modify Makefiles" in the Project Options after you loaded your project the first time.

Next Previous Table of Contents