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 directory 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. Fix an errors and re-run
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 opened and the build started.
Configuration with the ccmake executable
Again, the curses interface, ccmake, is only available on Linux on Mac. Command line arguments are largely the same as the cmake executable. After startup, though, a curses interface will present an interface to edit the CMake variables. Pressing h will show the following help:
CMake is used to configure and generate build files for software projects. The basic steps for configuring a project with ccmake are as follows:
1. Run ccmake in the directory where you want the object and executable files to be placed (build directory). If the source directory is not the same as this build directory, you have to specify it as an argument on the command line.
2. When ccmake is run, it will read the configuration files and display the current build options. If you have run CMake before and have updated the configuration files since then, any new entries will be displayed on top and will be marked with a *. On the other hand, the first time you run ccmake, all build options will be new and will be marked as such. At this point, you can modify any options (see keys below) you want to change. When you are satisfied with your changes, press 'c' to have CMake process the configuration files. Please note that changing some options may cause new ones to appear. These will be shown on top and will be marked with *. Repeat this procedure until you are satisfied with all the options and there are no new entries. At this point, a new command will appear: Generate and Exit. You can now hit 'g' to have CMake generate all the build files (i.e. makefiles or project files) and exit. At any point during the process, you can exit ccmake with 'q'. However, this will not generate/change any build files.
ccmake KEYS:
Navigation: You can use the arrow keys and page up, down to navigate the options. Alternatively, you can use the following keys:
- C-n : next option
- C-p : previous options
- C-d : down one page
- C-u : up one page
Editing options: To change an option press enter or return. If the current options is a boolean, this will toggle it's value. Otherwise, ccmake will enter edit mode. In this mode you can edit an option using arrow keys and backspace. Alternatively, you can use the following keys:
- C-b : back one character
- C-f : forward one character
- C-a : go to the beginning of the field
- C-e : go to the end of the field
- C-d : delete previous character
- C-k : kill the rest of the field
- Esc : Restore field (discard last changes)
- Enter : Leave edit mode
You can also delete an option by pressing 'd'
Commands:
- q : quit ccmake without generating build files
- h : help, shows this screen
- c : process the configuration files with the current options
- g : generate build files and exit, only available when there are no new options
and no errors have been detected during last configuration.
- l : shows last errors
- t : toggles advanced mode. In normal mode, only the most important options are
shown. In advanced mode, all options are shown. We recommend using normal mode unless you are an expert.
- / : search for a variable name.
Configuration with the cmake-gui executable
The cross-platform Qt GUI is a convenient platform for performing configuration. First, enter the location of the source and build directories. Next hit the Configure button. You will be prompted to choose the compiler and the program will perform the initial configuration. Configuration variables can be edited with the user interface. You may need to hit the Configure button multiple times as new configuration options may result from previous runs. Finally, hit the Generate button to produce the files for your build system of choice. Execute the project file or Makefile generated in the build directory.
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.
Platform Specific Guides
Windows
Wrapping ITK
ITK can be wrapped for several different languages such as Python, Tcl and Java.
- Java wrapping guide
- Python wrapping guide
- WrapITK status
