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.

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, you have the option to create another project subdirectory. The sourcefiles that are created in this subdirectory are included in the project and are therefore available in the classviewer as root classes. To create the shared library, the KDevelop Programming Handbook offers a Makefile.am template. If the subdirectory's Makefile is added to the configure.in script, you only have to run "Autoconf and automake" and "Configure" to create the Makefiles. The build instead is only possible from a make-command within the subdirectory, as KDevelop invokes the build from within the original project subdirectory. Another possibility to create shared libraries is changing the Makefile.am of the original project-subdirectory according to the template in the Programming Handbook by hand following the rules for project modifications explained in chapter Project Hacking.
- for installing a shared library, you have to watch the KDE-File-system Standard as explained in The KDevelop Programming Handbook

#### 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 four 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, the wizard offers two different frameworks, the KDE-Application, providing a complete application with base classes for document type, view and application. This includes the creation of a menubar, toolbar and statusbar, the mainwindow inherits the KTMainWindow class. The KDE-Mini-Application only gives a view which is empty. This type of project can be used for the creation of small desktop tools or other simple applications without too much change on the existing code provided by the framework. A Qt-Application offers the creation of a Qt-only program if you wish no dependencies towards the KDE-libraries for end-users. The Qt-Application also is created by using tree base classes like the KDE-standard-Application and provides a menubar, toolbar and statusbar.

The C++ -Application type offers a framework for creating commandline applications. It is ready to run and by default displays "Hello World" as the only action. This may be useful for C++ learners who would like to program applications without using a GUI first or for those working on commandline programs written in C++ or C. C programmers can also take advantage of the C-only project, which requires any C-compiler at the minimum.

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.

### 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 The Dialog Editor and The KDevelop Programming Handbook where questions about internationalization are covered again.

#### Extending the Project Documentation

All projects created with KDevelop contain a pre-configured documentation, 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.

#### 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.

### 8.5 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.6 External Projects

Existing projects can be converted to KDevelop projects by selecting "New" from the project menu. The following dialog creates an empty project file with your project name, version and type information as well as your name and email address. Then copy all your compilation and construction files to the new project directory and choose "Add Files" from the project menu. The files selected will be copied into your project directory and the Makefile.am's are updated. Please change all Makefile.am entries existing before the conversion towards the now created entries done by KDevelop in the KDevelop area. Test, if your program can still be compiled and installed after the conversion to ensure the project's consistency.

Next Previous Table of Contents