CMake basics

CMake is the powerful cross-platform build system used in gtk-fortran. Each directory of the project containing source code also contains a CMakeLists.txt script. The gtk-fortran user don't need to know that script language but needs to know a few CMake options to build, test and install gtk-fortran.

• CMake documentation (latest release).
• Ken Martin, Bill Hoffm, Mastering CMake - A Cross-Platform Build System, Kitware, 2010, ISBN 978-1930934313.
  • Mastering CMake (online updated version).

Basic usage

Atfer downloading gtk-fortran, in the root of the project you will generally type the following commands to configure, build and install the project:

$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install

The cmake .. means CMake must use the main CMakeLists.txt at the root of the gtk-fortran project.

Useful CMake options

CMake variables are set by using the syntax -D <variable>=<value> where -D means define.

• You can build in Debug mode using -D CMAKE_BUILD_TYPE=debug
• To change the default install directory from /usr/local to /usr, type: cmake -D CMAKE_INSTALL_DIR=/usr ..
• CMake uses f95, which is generally a link toward the default Fortran compiler. You can override that, for example to choose a specific gfortran version or another compiler like ifort:

$ cmake -D CMAKE_Fortran_COMPILER:FILEPATH=$(which ifort) -D EXCLUDE_PLPLOT=true ..

Note that you must use the same compiler to compile gtk-fortran and your own programs, because the .mod files are compiler specific.

gtk-fortran CMake variables

A few CMake variables are defined in gtk-fortran:

• NO_BUILD_HL Set this to disable building the High Level sub-library (includes PLplot and sketcher).
• EXCLUDE_PLPLOT Set this to disable building the PLplot integration even if PLplot is found: -D EXCLUDE_PLPLOT=true. It is necessary if PLplot was not compiled with your Fortran compiler.
• INSTALL_EXAMPLES Set this to install the source code of the examples into ${CMAKE_INSTALL_DATAROOTDIR/gtk-fortran/examples<gtkversion>, this would for example be useful if you were making a binary package of gtk-fortran.
• NO_BUILD_EXAMPLES Set this to prevent compiling the example programs, also mostly useful for packagers.

Make options useful to build gtk-fortran

• For parallel building use make -j or make --jobs. In some systems, like FreeBSD, you must give explicitly the number of jobs: make -j 4
• If some examples cause a building error, you can ignore them with: $ make -i
• Sometimes it can help to clean out the build directory with $ make clean. Removing the CMakeCache.txt file may help in case of error. And remove also any .mod file that could lie around in the gtk-fortran subdirectories if you have compiled something without using CMake.

Using Ninja instead of make

Note that you can also use ninja with CMake:

$ cmake -GNinja ..
$ ninja

Testing all the examples with CTest

You can use CTest to launch and test all the examples from the build directory (with -VV to read all the outputs of the examples):

$ ctest -VV

Quickly testing that all examples run can be done with the following options, to launch 4 examples simultaneously and close them after 5 seconds:

$ ctest --timeout 5 -j 4 -VV

Note that in that case, the tests are considered to have all failed because they are interrupted after 5 seconds (most of the examples are using windows that should normally be closed by the user).

You can use a regex to test only the matching examples, e.g. the pixbuf examples:

$ ctest -VV -j 4 -R pixbuf

You can use the -I option to launch a specific example, for example ctest -I 10 to launch the 10th example, or ctest -I ,,5 to launch one example over five.

Back to Home