ITK/Configuring and Building
Configuring And Building
This page describes the various ways of configuring and building ITK in common configurations. The build instructions are generally the same across platforms. Nuances will be noted.
CMake
ITK is configured with the cross-platform configuration tool, CMake. CMake will create project files for your build system of choice, e.g. Makefile's, Visual Studio project files, KDevelop project files, etc. The content of these project files is based on a domain specific language kept in CMakeLists.txt files distributed with the source code, the results of introspecting of the software and hardware features available on a system, and the preferences of the user building the system.
There are three executables used to perform a CMake:
- cmake: A command line interface.
- ccmake: An ncurses (terminal) GUI. (only available on Unix-like systems).
- cmake-gui: A Qt-based GUI.
To perform a CMake configuration, we need three things:
- The source code directory.
- A different to perform the build (make this directory manually).
- One of the three CMake executables.
Configuration variables can have different types, e.g. a boolean, a string, a filepath, etc. By convention, most persistent configuration variable names are composed of all capital letters and underscores such as BUILD_SHARED_LIBS. For this reason, they may resemble environmental variables, but they are not environmental variables.
Persistent configuration variables are stored in a file called CMakeCache.txt that lives at the top level of the build directory. It is possible to edit these variables by hand before re-running the CMake executable. Any variable can be changed at any time except the path to the C and C++ compiler. Since changing compiler in the middle of a build will often result in an unusable build, this is not allowed. To specify a different compiler other than the first one that is found by the system, it must be specified at the initial CMake configuration. This is performed with the dialog box that pops up when the build tree is empty for cmake-gui. The paths to the desired C compiler and C++ compiler can be specified with the CC and CXX environmental variables for the cmake and ccmake executables.
Configuration with the cmake executable
The cmake executable is the simplest executable, and it is appropriate for shell use or scripting. To use the executable, first change your current working directory to the build directory. For example,
cd ~/bin/ITK
Next, run the cmake executable. For a first time configuration, the required argument is the path to the top level of the source tree. For example,
cmake ~/src/ITK
Configuration variables can be specified with the -D option. For instance,
cmake -DBUILD_SHARED_LIBS=ON ~/src/ITK
Make sure configuration completes successfully without any errors.
Once the project has been configured, it can be built with your build system of choice. For a list of build systems available, see the list of "Generators" at the end of the cmake --help output. A different generator can be specified with the -G flag to cmake.
On Linux and Mac, the default generator is Unix Makefiles, so the build can be started by invoking the make executable:
make
On Windows, the default generator is a Visual Studio project file, so this file can be open and the build started.
Using a predefined Configuration
CMake can be run interactively to configure a build, in which case all settings begin with system defaults (as determined by CMakeLists.txt) and the user customises them.
Alternatively, a predefined configuration (such as those shown above) can be provided, which will provide initial settings for the build (also known as priming). By creating a file called CMakeCache.txt in the top level of the build directory, the settings defined therein will be used to override the default settings for the build.
Wrapping ITK
ITK can be wrapped for several different languages such as Python, Tcl and Java.
- Java wrapping guide
- Python wrapping guide
