Advanced CMake¶
Editing the CMake cache¶
Having run cmake
and generated a ‘’build’’ directory full of
makefiles, one sets build options by editing the CMake cache. You can
start the editor with “make edit_cache”, or by invoking the cache
editor, ccmake
, directly:
$ cd ~/Icecube/meta-projects/combo/stable/build
$ make edit_cache
A handy curses app will pop up allowing you to change the values of various configuration variables. As you move the cursor over them a description is shown at the bottom of the window:
BOOST_FOUND ON
BOOST_INCLUDE_DIR /Users/troy/ports/include/boos
BOOST_LIBRARIES /Users/troy/ports/lib/boost-1.
BUILD_DATACLASSES ON
BUILD_DATAIO ON
BOOST_FOUND: BOOST found successfully
Press [enter] to edit option CMake Version 2.4 - patch 6
Press [c] to configure
Press [h] for help Press [q] to quit without generating
Press [t] to toggle advanced mode (Currently Off)
After you have set things as you like them press c to run the configuration. You may have to do this twice. When CMake is ready to generate makefiles, an option g will appear in the menu. Press g to generate the new makefiles and exit.
Command line configuration¶
If you know what you want to set, you can also just do so from the
command line. For instance, I have checked out source to directory
src/
and am in a parallel directory build/
. I want to build
the “release” variant, the one with optimizations on, i issue:
$ cmake -DCMAKE_BUILD_TYPE=Release ../src
Common CMake Settings¶
Not all of the variables are useful. Here are some that are:
Option |
Description |
Default |
---|---|---|
|
Toggles the build of project PROJECT.
e.g. |
ON |
|
Build with ROOT support. Disabling this option will cause some projects to be skipped when building. IceTop users will want this option to be on. |
ON |
|
Build dictionaries with rootcint. rootcint support is deprecated as of April 1st, 2015, and this option will soon do nothing. |
OFF |
|
Use ccache to aid in compilation. Requires administrator setup in order to use efficiently on multi-user systems. |
OFF |
|
ON |
|
|
Set the cmake build type. Choices are: None Debug Release RelWithAssert RelWithDebInfo MinSizeRel Coverage. |
Release or RelWithAssert |
|
Use your operating system’s installed versions of supporting libraries. Safe to use on modern (2015 and newer) OS’s, but some more obscure libraries may need to be installed by hand. |
OFF |
Uncommon CMake settings¶
Option |
Description |
Default |
---|---|---|
|
Override ROOT version detection if you want to use a specific version of ROOT. |
autodetected |
|
A semicolon delimited list of options to pass to sphinx. Useful for developers and documentation writers. |
“-N;-a;-E” |
|
Use the distcc distributed compilation system. |
OFF |
|
Check some of the flags passed to the compilers. This option is mostly of interest to developers when adding new compilation/linking flags. |
OFF |
|
Add compiled-in git revision information. Do not disable this option unless you want to have a bad time. |
ON |
|
Install header files when making tarball. |
OFF |
|
Install 3rd party libraries when making tarball. |
ON |
Verbose build¶
If you issue the ccmake
command t the advanced variables
will be shown. The most useful of these are:
Option |
Description |
---|---|
|
Shows commands used while building. Useful for debugging cmake. |
Though you can also make the build verbose at any time by adding
VERBOSE=1
to the command line:
$ make dataio-pybindings VERBOSE=1
The cmake cache CMakeCache.txt¶
These cache variables are stored in a file CMakeCache.txt
in the
build directory. You may modify this file directly instead of using
make edit_cache
or the ccmake
utility as above.
If you do so, cmake will detect that this file has been modified and automatically regenerate your makefiles. However if you add or remove files that a glob should match, e.g.:
i3_add_library(mylib private/mylib/*.cxx)
there is no way for cmake to know that a new file
(e.g. private/mylib/newfile.cxx
exists that should match
private/mylib/*.cxx
, as this regular expression no longer exists.
It has been expanded into e.g. ‘’private/mylib/file1.cxx
private/mylib/file2.cxx’’. There are two ways to handle this:
Don’t use globs: list the files explicitly, e.g.:
i3_add_library(mylib private/mylib/file1.cxx private/mylib/file2.cxx).
This way to add/remove files one edits a CMakeLists.txt and cmake will detect that the file has been modified, and regenerate the makefiles.
make rebuild_cache
: The make target rebuild_cache will cause the makefiles to be regenerated. During this process the globs from each CMakeLists.txt will again be expanded and things will work.