How to Compile a Project
Compiling a project in KDevelop requires several setup steps and then building the application. All these are available through the menu.
Building a project requires several steps.
We are interested for now in the upper section only of this menu. The entries there are sorted in order of their importance. Thus the most often needed command is on top, the entry, which will cause all of the project be initialized, compiled and linked as needed. Other entries are there to compile selected project portions or a single file only, to perform several initialization sequences, or to install the completed application binaries.
For now we will concentrate on several facilities which KDevelop provides for project setup, initializing, building, and running an application. In general, this includes:
| Looking briefly at the basic build cycle. |
| Looking at some basic means to configure a project. |
Once you created a new project you usually want to check if everything went right so far. This implies a first build and test run of the application, which we will do now. In order to initially compile a project there are several steps to perform, which we will briefly look at.
| How to initialize the project for a first build. |
| How to do the initial configuration. |
| How to build the project. |
| How to run the application from within KDevelop. |
This discussion implies that your project is based on the GNU autotools, which enabled the Automake Manager tool in KDevelop as our example Hello project does. If you created another type project, e.g. for the Qt™ based QMake project manager, there will be other facilities available in the menus or perhaps even none of them. You will have to consult the respective vendor documentation on project management and application building in these cases.
When the Application Wizard created our Hello example project, it left it in a sort of raw, “virgin” state. The GNU autotools chain dictates several initialization steps to be performed before the application could be actually compiled and linked. If you try to build a project in such a raw state, e.g. by selecting the -> menu or pressing the F8 function key, you will get the following warning.
Trying to build a raw automake based project.
You may press the button in which case KDevelop will try to automatically run all required setup steps prior to compiling and linking the application. But we will look at those initial steps in sequence, so cancel the dialog by pressing .
As mentioned already, compiling and linking the application is done through the menu. Call it up and select .
Initiating a basic initialization run.
KDevelop will now open the Messages tool view window at
the bottom and list a series of messages produced by several make tools. If
everything went right, the final line will read
“*** Success ***”.
If you scroll back to the top, you will find the command line, KDevelop issued to call up the tools beneath the surface:
cd '/home/devel/projects/hello' && \ WANT_AUTOCONF_2_5="1" WANT_AUTOMAKE_1_6="1" gmake -f Makefile.cvs
This basically tells that KDevelop first switched to the root directory
of our example project. Then it set up a dedicated environment, advising the
make system of the autoconf and
automake tool revisions used for this initialization.
And finally it instructed the make tool (GNU gmake
in this case) to process the Makefile.cvs make file.
This make file was automatically set up when you created the Hello
project. It contains all the commands necessary to properly initialize the
project so the resulting application will run under KDE. Especially this will
create the configure skript file necessary to perform the
next setup step.
Configuring means to tailor the build process to the hardware and software peculiarities of your system. This is a basic requirement in build processes based on the GNU autotools scheme as you probably will know.
You can command a configure sequence once the basic automake
initialization has been successfully finished because only after this
initial run the necessary configure files will be
available. This done, select the -> menu entry to initiate a
configuration sequence.
KDevelop opened the Messages tool view
window again if necessary and listed the messages of the configure run therein.
If all went right, the final messages will be “Good - your
configure finished. Start make now” (which was issued by
configure) followed by the KDevelop “*** Success
***” message.
On top of the Messages window you will again find the command line, KDevelop used to initiate this configuration run:
mkdir '/home/devel/projects/hello/debug' && \ cd '/home/devel/projects/hello/debug' && \ CXXFLAGS="-O0 -g3" "/home/devel/projects/hello/configure" --enable-debug=full
You can tell several interesting details from these commands.
 |
|
All these settings are configurable on a per project basis. You will learn more about this in the Project Management chapter.
Once you got this far you will be ready to actually build, i.e. compile and link the application. Looking at the menu, there are three such compile options from which to select.
KDevelop commands to build binaries.
Going from bottom to top, there are:
— This will compile the source file in the currently open editor window. Mostly used for quick error checks.
— This is mainly used in conjunction with the Automake Manager which we will briefly look at below.
— Now this is what we currently are interested in. It will iterate over the whole project, compiling and linking all files as necessary.
It might be interesting to watch what happens to the
Debug directory created in the former
configure run. So best keep it open with all
subdirectories unfolded just as shown above. Then select
-> (or press the F8 key) to
initiate the build sequence. As before, the Messages tool
view window will open at the bottom and list the outcome of this build run. And
additionally some files will appear on the Debug subtree.
There are not many source files in our Hello example project, so the Messages window will contain only a few lines. On top of them again find the command line KDevelop issued to the underlying shell.
cd '/home/devel/projects/hello/debug' && \ WANT_AUTOCONF_2_5="1" WANT_AUTOMAKE_1_6="1" gmake -k
Not very surprisingly, KDevelop switched to the Debug subtree root in order to run the
Makefile located there. A dedicated sub-environment was
set up again as before in the Initialization step in which
then the gmake tool was called.
Note the -k option in the
gmake call. It forces the build process to continue
up to its very end, even if errors will occur. This makes sense as KDevelop
will list all error messages in the Messages window. If
there are any, use the virtues of an IDE: Just click on the error message in
the Messages window and KDevelop will take you to
exactly the position where the error occurred in the source file.
And what did happen inside the Debug subtree? Not very much. A few files showed up
on the doc/en and src branches, most notably the
hello file in /home/devel/projects/hello/debug/src/. This,
finally, is the application binary we were looking for. All what is left
to do in our initial project check is to run this
hello.
There are no extra steps involved to run this new Hello application. Either select -> or press Shift-F9 or use the button on the Build Toolbar shown below.
Running an application form the Build Toolbar.
That was all. KDevelop will now start the new application in the dedicated console window which opens as Application tool view on the bottom. There the command KDevelop issued to execute the program will be shown in the top line:
./hello
showing that the IDE has a notion about where the executable it shall run resides. This notion can be widely configured. See more about this in the Project Management chapter.
The ./hello line will most likely
be followed by a warning message. Ignore this for now. It does not keep
our Hello form running.
Our initial Hello application.
Close the Hello application window as
usual. If no errors occurred, KDevelop will report this as
“*** Exited normally ***”
in the Application tool view window.
In KDevelop there are numerous ways how you can manage your project. This behavior is configurable on a per-project basis and mostly of interest to the advanced developer. Yet there are a few project specific settings you should know of right from the beginning.
| Of what use are build configurations? |
Where to the define
the behavior of the configure script. |
| Some considerations how make should run. |
| Where should the executable be and how should it be called? |
When we did a first run of the configure script in
the Initial Hello
Configuration section above, we noted that KDevelop had set up a
dedicated debug subdirectory for this
purpose. In this section we will briefly consider some consequences of
this feature.
First of all, KDevelop does not necessarily use dedicated build directories apart from the source. The preparations to automatically use dedicated build configurations is done through templates the Application Wizard uses when creating a new project.
To find out which build configurations currently are available, have a look at the -> menu.
There are various build configurations available for this project.
In this case, like our Hello example project, there are three different build configurations available. In other cases, there may — initially — be only one such build configuration, namely .
The currently used build configuration has a check mark left to it. In order to switch to another build configuration simply select its menu entry.
Now let us have a brief look at what these build configurations provide.
You should use this as the standard build configuration during the
development process. The build occurs separately from the source directories in
the dedicated debug subdirectory, i.e.
all object, auxiliary, and executable files will be put in the subdirectories
there instead of their counterparts in the project root. The
configure script will be given the
--enable-debug=full option and the
CXXFLAGS="-O0 -g3" will signal the gcc
compiler to not optimize the code and to insert extensive debug information
into the resulting binaries.
This is used to build a final C++ application. The build occurs
separately from the source directories in the dedicated optimized subdirectory. No specific arguments to
the configure script will be preset, yet the
CXXFLAGS="-O2 -g0" will signal the gcc
compiler to optimize the code and to not insert debug information into the
resulting binaries.
The term “default” denotes the standard setup when you build an application from the console using e.g. the GNU configure and make/gmake command line oriented build tools. Other than or no dedicated build directory will be used. The application will by default be built in the sources directories instead. There are no special configuration switches predefined. Building and running the application will use the default settings of the underlying tools (e.g. gcc, etc.).
Think twice before you decide to use the build environment!
It cannot be used in parallel to the dedicated
or ones.
Any build operation using will
render both of the other build environments unusable. This is caused
by some peculiarities of the Makefile construction process
using the
automake/autoconf
machinery, which cannot be easily overcome.
Now, why does one one want to use different build configurations at all, when they even appear to be not compatible to each other? The answer is — it simplifies edit-compile-debug cycles. The extra debug instructions inserted into the binaries as well as all those subtle structure changes to the program code made during optimizations will effect the run time behavior of the resulting application. So in many cases, when the logical structure of some routine appears to be correct, you may want to test whether it still behaves correctly under more practical conditions.
This is where the build configurations of KDevelop step in. Because the built object and executable files in each dedicated build directory and the build commands are kept separately from each other only source changes need to be handled when you switch between these build configurations.
Thus instead of cleaning up and recompile everything from scratch with alternate options, you need only switch from the to the build configuration, have the source changes compiled in and then retest the application under these circumstances. If anything inappropriate shows up, simply switch back to and immediately continue your work there.
A final note — many build configuration settings are configurable. You can even define your own build configurations if your development process requires some. We will briefly look at these possibilities in the next section.
Configuring the application properly is vital in the GNU
autotools building chain. This is usually guided by option definitions to the
configure script and/or specific flags settings in the
environment prior to running configure as e.g. the
CXXFLAGS in our previous discussions.
You may set most of the configuring options for a given project from within KDevelop GUI. Select -> and then from the icon bar on the left of the dialog the Configure Options icon. The Configure Options dialog featuring several tabbed windows will display on the right handed side.
Most configure options can be defined here.
As you see, there are quite a lot of options you can set up in this dialog. For now we will briefly look at only a few of them with regard to our Hello example project. For detailed instructions see the Configuring Projects chapter. If you want to know more about the meaning of the various flags which can be set, look up info make from the console (or info:make from within Konqueror) and there the -> section.
There are several tabbed dialog setup windows from which the first one, General, refers to commonly used settings, while the others are rather compiler specific. In all cases, however, will the actual contents of those dialogs be governed by the given build configuration.
You select the build configuration whose configuration settings have to be defined from the Configuration combo box on top of the Configure Options dialog.
Select the build configuration whose settings to define.
Now select another build configuration from this combo box and note how the contents of e.g. the Configure arguments and Build directory text boxes change according to the settings we mentioned in the build configurations list above.
On the General dialog page, these configuration options can be defined:
Configure arguments. These are the options KDevelop assigns to the
configure script call in the build process. See the
example in
the “Initial Hello Configuration” section above.
Build directory. This is the subdirectory in the current project root, where KDevelop will put all files created in the build process. Ideally, this should correspond to the name of the build configuration in use, but you are free to use any name you like, provided it is different from any other build configuration directory.
Top source directory. You won't need this one often. It defaults to the project root directory and needs only be redefined if your project sources are located in another place.
C/C++ preprocessor flags (CPPFLAGS). Put specific instructions for the preprocessor here. KDevelop will use this to set up a temporary environment before it calls the actual build tool. Again, see the example in the “Initial Hello Configuration” section above how this is done.
Linker flags (LDFLAGS). This is extra information for the ld linker tool where it should look for additional libraries. It is used to build the temporary build environment as well.
Environment Variables. Here you may define additional variables to be set up in the temporal build environment, KDevelop will set up before calling the respective build tool. Again, you must define these environment variables for every build configuration where they are to be used.
The other tabs on the Configure Options dialog page are for compiler specific settings. They are similarly structured, so it suffices to have a brief look at the C++ page.
Select the compiler and its working environment KDevelop shall use here.
This is what you can set up from here:
C++ compiler. Select the C++ compiler KDevelop should regularly use from this combo box. It however lists only those compilers KDevelop really knows of.
Compiler command (CXX). Only for experts. This is only needed if the C++ compiler is not standard. Put the name by which it is called here.
Compiler flags (CXXFLAGS). Here you can enter any extra option KDevelop shall pass (via the
Makefile) to the compiler. Some option values will be
preset according to the build configuration selected in the
Configuration combo box.
Note, that many common compiler options can be selected from a dialog which will pop up when you press the button to the right of the text box.
Use this dialog to define the GNU C++ compiler behavior.
We deliberately selected the Optimization tab
here. Note how the No Optimization option has been
preselected (according to the -O0
option preset in the debug build
configuration).
Unfortunately you cannot currently select all options from this
dialog. The -g3 option e.g. used by the
debug build
configuration would have to be altered manually if ever needed.
You can as well configure the way KDevelop will call the make tool in the project build. Select -> and then the Make Options icon from the left dialog window side. The Make Options dialog page will then be displayed to the right.
Define how KDevelop will call the make tool.
There is not much to do here for now. The only setting of interest in
most cases will be the Abort on first error switch.
You will find it deactivated in most projects. This corresponds to the
-k option in the
gmake call we found in the initial build of
our example Hello project.
This makes sense in an IDE like KDevelop which will protocol any error message during the build. After the build process you may easily navigate to any error message in the Messages tool window. Use -> and -> or respectively the F4 and Shift-F4 keys for this. KDevelop will automatically activate the editor window of the source file in question and put the cursor on the error line.
If on the other hand you rather want the build be stopped on whenever an
error occurs, check the Abort on first error option
in this dialog. KDevelop will then call gmake
without the -k option.
Once the build is complete, you can easily run the application from within KDevelop. Use either ->, the Shift-F9 keys, or the button in the Build Toolbar of KDevelop.
Run the program from here.
But where is the executable located which should be run? How does one have KDevelop append options to the call? Or, how can I have the application executed in a terminal by its own to test its console interactive behavior?
All this can be solved by configuring some project oriented run options in KDevelop. Select -> and then the Run Options icon from the icon bar on the left dialog window side. The Run Options dialog page will display to the right.
Define where and how your program shall be run.
Now, there is quite a lot which can be set up from this dialog. Basically there are four groups of configuration items.
Directory. This tells KDevelop where it basically shall assume the executable to be called. There are three possibilities you can select from.
Note however that only root directories are defined here. KDevelop usually looks for the executable in some subdirectory given in the next configuration group.
Run from the directory, where the executable was build the last time. This is the default. You can keep this for now.
Run from the build directory according to the currently selected build configuration. The name of this directory was set up on the General Configuration dialog page.
This is the root where KDevelop will find the executable. It changes automatically with the selection you made in -> menu. Try it.
Other than always running the most recently built executable according to the setting above, this allows you to switch the program to be executed by simply selecting another build configuration from the menu.
Run the executable found in a fixed custom directory. Again this is the root only from where the actual executable is to be found.
Use this if you e.g. want to run the actually installed program instead of the version located in the project directories.
Program. This tells KDevelop the relative position and name of the program it shall actually call. This is relative to the root directory defined in the configuration group above. Furthermore you can define any argument KDevelop will pass to the program when it is actually called.
If leave the Main program text box empty, the active target settings of the Automake Manager will be used. Although this is an expert setting, inadvertently leaving this input field blank is a common cause of problems. Check this setting if KDevelop appears not to call the executable you wanted.
Environment Variables. KDevelop will set up a dedicated shell environment to run the program in. Define any extra environment variable in this configuration group.
Miscellaneous. Two more check boxes are located at the bottom of this dialog page.
Automatically compile before execution comes in handy most of time. KDevelop will check the project for changes and perform necessary configure and build steps for you any time you command it to run the program.
Uncheck this in case you want to run the program version prior to the last change.
Start in external terminal is interesting if you want to test the input/output behavior of non-GUI programs in a console terminal. This is unchecked by default, so KDevelop does start the program in a window of its own without console terminal I/O capabilities.
