Starting a New Project
Almost any application will consist of dozens, hundreds, even thousands of files which need kept structured and maintainable. To accomplish this, KDevelop organizes software development tasks in projects. Thus the first practical step to develop software in KDevelop usually is to create a new project.
Fortunately this is fairly easily accomplished. KDevelop provides the so-called Application Wizard tool for this. (See the Getting Started — the Application Wizard chapter for more.)
We will now start a simple KDE application project to illustrate how easily this is accomplished and which files and tools KDevelop will have provided. Thereby we will have a short look at:
| How to create a new project with the help of the Application Wizard. |
| Which files the Application Wizard initially did set up. |
| What about the additional tool view shown with the project? |
Let us create a rather simple “Hello World” KDE project. Just follow these steps.
To start the Application Wizard click the -> menu.
The Create New Project dialog will pop up. In the upper left All Projects window there will be a number of programming languages listed.
We want to build a KDE C++ application as usual, thus click on the + label left of the C++ label to open this branch.
A series of possible application targets will be displayed. We will build a KDE application, thus open the next sub-branch via the + label next to KDE
Now you will be offered a series of possible project templates. Navigate down to the end of this branch and click Simple KDE Application.
A preview and short description of the application this project template will produce pops up in the two windows to the right.
Selecting a “Hello World” project template
Our application will need a name. Find the Properties area on the dialog bottom and enter a suitable name into the Application name input field.
We use “Hello” in our example, but you can use whatever you like, provided the name consists of letters, number digits, and underlines only. You will find that the Application Wizard rejects any other character.
Make sure the Location text box below the input field shows the name of your top project directory as set up in the A Bit of Configuration chapter above. If it does not do so, enter a suitable directory name or select one from the directory list provided by the folder labeled button to the right.
If all went well, the Final location line at the bottom will show the directory path your new project will use. In case there was an “(invalid)” suffix appended, try another name for your project and/or make sure the top project directory in the Location text box really exists and is writable.
Once everything is right, the button in the bottom row of the dialog will be enabled. Click it to proceed.
This will lead you to the Project Options dialog page. Make sure the Author and Email text boxes are properly filled in. Usually they will default to your general KDE user settings as given in the Password & User Account dialog of the KDE Control Center. If not, change them to some settings you prefer for your application.
Provide your name and (optionally) email address.
You must provide an Author name at least. This is mandatory for the application files setup.
If all is right, the button will be enabled. Click it to further proceed.
The following Version Control System, Template for .h Files, and Template for .cpp Files dialog pages are not of interest for now. Skip them by clicking the buttons and, finally, the button.
That was all! The Application Wizard will take over and construct a series of initial files in the Final location directory you provided in step 2c above.
Once this file creation phase is finished, KDevelop will open an editor
window for the application main window implementation file
(which is hello.cpp in our example), so you can readily
proceed.
Even if our sample Hello project is fairly simple, the Application Wizard did create a whole bunch of source and project management files. You will most easily list them if you open the File Tree tool view on the bottom left. This will open a file list similar to the one below.
Initial files in our “Hello World” project
To demonstrate the main bunch of files the Application Wizard produced, we did open most of the directory branches in the left-hand File Tree tool view window. Just click the branch names in the tree to see for yourself.
Additionally, just for demonstration, we did as well open most of the branches the Automake Manager tool view window to the right where some of the project sources are listed, too.
All GNU conformant applications must be copyrighted. There are two levels which require copyright notices, individual source files and run-time application level. The Application Wizard did already put appropriate copyright and licensing information into the project files.
Source File Level Copyrights. Do you remember the Project Options dialog page in the new project setup? You had to provide your (the developer's) name and optionally an email address there. Now refer to the top of the hello.cpp editor window currently displayed in the workspace area. The Application Wizard did enter these statements on top of the licensing header of every source file it created.
/*************************************************************************** * Copyright (C) 2006 by Joe User * * joe@user.com * * * * This program is free software; you can redistribute it and/or modify *
You will find exactly the same text headers in every source file you will
create inside KDevelop (provided you use the proper built in tools for file
creation). KDevelop remembers these settings in some template files you may
find in the templates directory.
Application Run-Time Copyrights. Once your KDE application runs, the user may display some
About data, usually from the menu.
The Application Wizard did also take care of this. If you have a look at the
main.cpp file, you will find an entry similar to the one
below.
int main(int argc, char **argv)
{
KAboutData about("hello", I18N_NOOP("Hello"), version, description,
KAboutData::License_GPL, "(C) 2006 Joe User", 0, 0,
"joe@user.com");
about.addAuthor( "Joe User", 0, "joe@user.com" );
This will put the main developer's name (“Joe User” in our case) and email address into the About copyright page in the display and list this name and address on the Authors page there as well.
Whenever you make substantial changes to an existing project, be sure to enter your name and email address to the copyright notices on every file you changed and to the run-time copyright display as well. Don't be shy, you help the open source society considerably if you do so.
The Application Wizard did put the source files into the src sub-directory of the project's directory.
You will find the main.cpp, hello.h,
and hello.cpp files there as you may have possibly
expected.
There are some additional files you usually will find in a typical KDE application, namely
hello.desktop contains some meta data used by
KDevelop to maintain and start the application.
hi16-app-hello.png, and
hi32-app-hello.png contain some initial default icons,
KDevelop will use for application display.
Finally, helloui.rc contains a description of the
application's user interface, currently the menus the application will
provide.
In the doc/en subdirectory of the
project you will find the index.docbook file. This is a
default template from where you can start to write a suitable user
documentation.
You will have noted that the files we introduced so far are listed in boldface in the File Tree tool view while most of the other files are not. This depicts the substantially different tasks these files are used for. The contents of those bold listed files directly influence the application. Source files will produce the code to be run, others will provide necessary data or documentation. These files must be maintained and orderly processed in the build stages by the project, hence they are called project files.
If you have a look at the lower Automake Manager window to the right of the workspace area you will find all project files listed as well. The Automake Manager tool uses this knowledge to take care of the build control as we shortly will see.
The other, non-bold listed files are of more auxiliary nature. They belong to several distinctive classes as follows:
Project Build Control. These files control the compile, install, documentation building, etc.
processes. If the project utilizes the GNU
autotools machinery as our example does, you will
find a Makefile.am file in each project directory. These
are kind of basic make core files which contain build control commands and will
be processed in conjunction with various configure files
during the build stages. Such a build produces a final
Makefile in every directory. And from these in turn the
make utility will finally build the binaries of the
application.
Those Makefile.am files need to be maintained
throughout the development process. Luckily, KDevelop relieves you of most of
this burden by the Automake Manager tool, which basically is a graphical front end to
maintain Makefile.am contents.
Other project build control files currently listed are
configure.in.in and subdirs in the
project root directory. They will be processed by some of the files in the
admin KDE specific administration
directory to produce more configure and
Makefile type files and finally the application's
binaries.
KDevelop Control Files. KDevelop needs some control and administration data on its own. These
are located in the project root directory, in our example
hello.kdevelop, hello.kdevelop.pcs,
and hello.kdevses.
Of particular importance in each project is the
xxx.kdevelop (where “xxx” denotes the project
name) file. It is the main KDevelop 3 Project File and
needed if you later want load this project into the IDE.
Never do manually modify, rename, or even delete any of these KDevelop control files! The IDE will most likely not function properly on your project afterwards.
GNU Project Description Files. Some files in the project root directory are mandatory in any GNU
conformant application. These are: AUTHORS,
ChangeLog, INSTALL,
COPYING (which contains the GNU GENERAL PUBLIC LICENSE),
INSTALL, NEWS,
README, and TODO.
Other Files. A few more files, not mentioned yet, are:
Doxyfile controls the creation of the project
specific API internal programming interface documentation.
The templates directory containes
file templates the IDE uses as stubs to create new source files.
You may at any time edit these templates. The new contents will be reflected in
the next source files you create of the related types.
You may e.g. want to realign the right hand stars in the copyright lines
the Application Wizard inserted into the cpp and
h template files, so the source files created from them
will look less awkward.
The po directory will be used for
localization purposes. It is essentially part of the project files (contains a
Makefile.am) but will mainly be used in translation
processing. Not of main interest to the application developer, however.
Finally, the admin directory is
specially needed in KDE oriented applications. It provides a whole bunch of
files necessary to maintain the application's sources and binaries so they
will integrate properly into the KDE environment.
As you will have noticed, as soon as the Application Wizard had the new project ready, several additional tool views were provided. These make sense during project development only and, in short, provide the following functionality.
The tool views actually visible depend on the plugins currently loaded into KDevelop. There are ways to control this. See the Plugin Tools chapter for instructions.
Bookmarks. You can mark any text file line in order to quickly return to this position from everywhere. KDevelop will remember all those bookmarks, even if you close the editor window afterwards. The Bookmarks tool view lists all those bookmarks by file name and line number. You need only click such an entry to open the editor window accordingly and position the cursor on that line.
Classes. Lists classes, methods, etc. known in the project. Clicking the entry opens the appropriate header or source file in an editor window and positions the cursor at the respective declaration or definition.
File Groups. Sorts the files in the projects into various utility groups, i.e. Sources, User Interface, Icons, Translations, and Others. Clicking an entry opens that file in an editor window.
Variables. This is used by the debugger tool to display, evaluate, and watch variables during debug runs.
Valgrind. Valgrind is a run-time program analyzer. This tool view lists the results of such an analyze run. It is used e.g. to find memory leaks.
Security Problems. There is a Security Checker plugin tool for KDevelop. It analyzes the currently edited source file for several common security problems which may occur in the application and notifies the user in this tool view window.
Breakpoints. This tool view allows to explicitly set, clear, and manage debug breakpoints in the application source files. It is used in conjunction with the debugger.
CTags. Allows to create a database of identifier indexes using the popular CTags application. This tags database may then be used from out this tool view window to look up any needed identifier in the project sources. Clicking a thus found item line will open an editor window and position the cursor on the appropriate identifier there.
Problems. KDevelop keeps track of common programming problems in the currently edited source file and notifies the user in this tool view window.
Automake Manager. The Automake Manager tool is basically a graphical front end to maintain the
contents of the Makefile.am files located in each project
directory. This tool view uses two windows to control its work. The upper window
mirrors part of the project subdirectories, namely those which explicitly
contain project files. Each subdirectory of this kind must
contain a Makefile.am file and is termed a
subproject in the Automake Manager context.
Clicking a subproject entry opens a suitable display of the project files
in this subproject in the lower window. The files listed there will be grouped
according to their Makefile.am functionality in this
subproject.
The Automake Manager is a very powerful tool to manage the project and its subprojects as well as the roles project files play in building the application. We will have a short look at a few major details below. See the Building and Project Management chapter for a more extensive description.
