Using QtCreator for GRASS C development

QtCreator can be used for GRASS development in C or C++ by using QtCreator's Generic project . This article is focused only on QtCreator for general information about development see Development or GRASS Programming Howto.

First steps

Download, configure and compile GRASS as usual .

In QtCreator go to

File -> New File or Project -> Other Project -> Import Existing Project

and fill Project name. Choose something which allows you to recognize these files easily, e.g. not just grass. Separate projects are usually created for separate modules, group of modules or group of functions (part of a library). Location is directory where your GRASS sources are. Project files will be created in the same directory (it can not be changed).

Managing files

After pressing Next, QtCreator will scan this directory for all possible source files. Now you should choose which directories and files you want to include in project. It is highly recommended to uncheck every directory which you don't need. This applies especially to modules because modules' local header files can contain declarations which can confuse QtCreator's source completion. You will probably need only include and lib directories and if you are working on a module, you will need also your module directory. However, there is an issue with include directories. Include directory is at different places in source codes and in GRASS distribution directory. You have to help QtCreator to find header files by adding dist include directory to QtCreator project. This directory is here:

dist.(...)/include/grass

Now it is possible that you will experience problems with changing header files. It is always caused by editing file in dist directory instead of original source file because QtCreator's source browsing functions now bring you to wrong files. So if you are editing header file be sure that this file is in source code directory.

You can also apply filters to exclude particular file patterns, e.g.:

*.tcl; *.po; *.sh; *.m

On the last wizard page you have to set Add to version control to None. (Warning: If you forgot this step, QtCreator project files will be added to GRASS SVN.)

Once project is created you can add new files through Edit files option in project context menu in project tree. If you open this dialog and you press OK button, all files in marked directories will be added, so this is the way how to add new files from SVN.

Building

In order to compile GRASS it is necessary to change compilation settings.

Projects -> your_project_name -> Build Settings -> Build Steps

In Details uncheck all in Targets field. If you have more than one core, you may want to specify number of cores used by make by setting Make arguments field to -j n where n is number of cores you want to use. You can also change Build directory to run make only for necessary directories.

Debugging

Run QtCreator from GRASS command line (actual command depends on your QtCreator installation and operating system):

qtcreator 2> /dev/null &

# other examples:
/opt/qtcreator-2.5.0/bin/qtcreator.sh 2> /dev/null &
/opt/QtSDK/QtCreator/bin/qtcreator 2> /dev/null &

Then you should be able to debug GRASS modules in QtCreator. Note that you should compile GRASS with -ggdb compiler option, see GRASS Debugging for details.

Note that same applies also for analyzing using Valgrind within QtCreator.

Samples

File project_name.files:

dist.x86_64-unknown-linux-gnu/include/grass/defs/arraystats.h
...
dist.x86_64-unknown-linux-gnu/include/grass/waterglobs.h
lib/raster/align_window.c
...
lib/raster/zero_cell.c
raster/r.mymodule/main.c

File project_name.includes:

include
include/defs
include/iostream
include/vect
lib/raster
dist.x86_64-unknown-linux-gnu/include

File project_name.config:

// only for pure C
// to avoid QtCreator confusion when variable named new is used
#define new dummy_new

Notes

• In Project Code Style Settings create new style and set Tab policy to Mixed, Tab size to 8 and Indent size to 4 (applies only for C).
• Since QtCreator can do indentation pretty well, it is easy to forget run indentation script, so do not forget to run it (applies only for C).
• QtCreator with some particular settings can replace tabs in Makefiles by spaces, so be careful editing Makefiles.
• For development in C++ you have to follow some special rules to create Makefile etc. (see some of existing GRASS C++ modules, try find . -name "*.cpp").
• You may want to set your own executable (your module) in Run Settings. In this case it is suggested to prefix or suffix output files since there is no convenient way how to browse command history in QtCreator. For this you also need to run QtCreator in GRASS environment.