Difference between revisions of "ITK/Configuring and Building"

From KitwarePublic
< ITK
Jump to navigationJump to search
m (moved ITK Configuring and Building to ITK/Configuring and Building: Conform to naming convention)
m (STYLE: Fix typo)
 
(18 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Configuring And Building ==
== Configuring And Building ==


This page describes the various ways of configuring and building ITK in common configurations.  Recommended configurations are incldued for:
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.


* Linux
=== CMake ===
* Mac OS X
* Solaris
* AIX
* Windows


It is strongly recommended that you build ITK in a separate treeThis is described elsewhere (?).
ITK is configured with the cross-platform configuration tool, [http://cmake.org/ CMake].    CMake will create project files for your build system of choice, e.g. Makefile's, Visual Studio project files, KDevelop project files, etcThe 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.


=== CMake Configuration for Linux ===
There are three executables used to perform a CMake:


This configuration is the one used to build the packages for Debian GNU/Linux, but should work for any distribution just fine. It assumes that you already have certain libraries installed (which will almost always be the case), specifically:
# '''cmake''': A command line interface.
# '''ccmake''': An ncurses (terminal) GUI. (only available on Unix-like systems).
# '''cmake-gui''': A Qt-based GUI.


* libzlib
To perform a CMake configuration, we need three things:
* libjpg
* libtiff
* libpng


The <tt>rpath</tt> option is disabled, as it is only really needed if you install the libraries into someplace other than a standard directory that is on your <tt>LD_LIBRARY_PATH</tt>.
# [[ITK/Source | The source code directory]].
# A different directory to perform the build (make this directory manually).
# One of the three CMake executables.


You can either paste this into a <tt>CMakeCache.txt</tt> or change the settings manually by running <tt>ccmake</tt>.
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.


# This is the Kickstart CMakeCache file for the Debian build of ITK.
Persistent configuration variables are stored in a file called ''CMakeCache.txt'' that lives at the top level of the build directoryIt is possible to edit these variables by hand before re-running the CMake executableAny 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 configurationThis 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.
  # Only those settings that are changed from the default are specified.
  &nbsp;
  // For some reason it defaults to c++
  CMAKE_CXX_COMPILER:STRING=g++
  &nbsp;
// Don't build examples now (let the user later)
BUILD_EXAMPLES:BOOL=OFF
  &nbsp;
// Build ITK with shared libraries
BUILD_SHARED_LIBS:BOOL=ON
  &nbsp;
// Don't bother building the testing tree
BUILD_TESTING:BOOL=OFF
  &nbsp;
// Give us an optimised release build
  CMAKE_BUILD_TYPE:STRING=RELWITHDEBINFO
  &nbsp;
// Install path prefix, prepended onto install directories
CMAKE_INSTALL_PREFIX:PATH=/usr
  &nbsp;
// The code still uses the older #include <iostream.h> style
  CMAKE_CXX_FLAGS:STRING=-Wno-deprecated
  &nbsp;
// We do not want rpath enabled
CMAKE_SKIP_RPATH:BOOL=ON
  &nbsp;
// We haven't packaged this (yet)
  ITK_DATA_ROOT:PATH=ITK_DATA_ROOT_NOTFOUND
  &nbsp;
// Use the system libraries for these
ITK_USE_SYSTEM_JPEG:BOOL=ON
ITK_USE_SYSTEM_PNG:BOOL=ON
ITK_USE_SYSTEM_TIFF:BOOL=ON
ITK_USE_SYSTEM_ZLIB:BOOL=ON
  &nbsp;
//Build cswig Python wrapper support
ITK_CSWIG_PYTHON:BOOL=ON
  &nbsp;
//Build cswig Tcl wrapper support
ITK_CSWIG_TCL:BOOL=ON


==== Ebuild for Gentoo Linux ====
==== Configuration with the '''cmake''' executable ====


For Gentoo Linux you can use the ebuild found in the following [http://github.com/thewtex/portage/tree/thewtex/sci-libs/itk/ gentoo/funtoo git repository].
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,


==== Build for Ubuntu Linux ====
  cd ~/bin/ITK


Please see the detailed [[ITK Configuring and Building for Ubuntu Linux]] notes.
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 Configuration for Mac OS X ===
  cmake ~/src/ITK


This configuration has been tested on Mac OS X Panther 10.3, with XCode 1.1 and 1.2It presumes that [http://fink.sourceforge.net/ Fink] has been installed, with the following libraries in the default location under <tt>/sw</tt>:
Configuration variables can be specified with the ''-D'' optionFor instance,


* libjpeg
  cmake -DBUILD_SHARED_LIBS=ON ~/src/ITK
* libtiff
* libpng
* libzilb


//Name of build on the dashboard
Make sure configuration completes successfully without any errorsFix an errors and re-run
BUILDNAME:STRING=Darwin-g++
&nbsp;
//Build source documentation using doxygen
BUILD_DOXYGEN:BOOL=OFF
&nbsp;
//Build the Examples directory.
BUILD_EXAMPLES:BOOL=OFF
&nbsp;
//Build ITK with shared libraries.
BUILD_SHARED_LIBS:BOOL=ON
&nbsp;
//Build the testing tree.
BUILD_TESTING:BOOL=OFF
&nbsp;
//Choose the type of build, options are: None(CMAKE_CXX_FLAGS or
// CMAKE_C_FLAGS used) Debug Release RelWithDebInfo MinSizeRel.
//
CMAKE_BUILD_TYPE:STRING=RelWithDebInfo
&nbsp;
//C++ compiler
CMAKE_CXX_COMPILER:STRING=g++
&nbsp;
//Use the system's jpeg library.
ITK_USE_SYSTEM_JPEG:BOOL=ON
&nbsp;
//Use the system's png library.
ITK_USE_SYSTEM_PNG:BOOL=ON
&nbsp;
//Use the system's tiff library.
ITK_USE_SYSTEM_TIFF:BOOL=ON
&nbsp;
  //Use an outside build of VXL.
ITK_USE_SYSTEM_VXL:BOOL=OFF
&nbsp;
//Use the system's zlib library.
ITK_USE_SYSTEM_ZLIB:BOOL=ON
&nbsp;
//What is the path where the file jpeglib.h can be found
JPEG_INCLUDE_DIR:PATH=/sw/include
&nbsp;
//Where can the jpeg library be found
JPEG_LIBRARY:FILEPATH=/sw/lib/libjpeg.dylib
&nbsp;
//Where can the png library be found
PNG_LIBRARY:FILEPATH=/sw/lib/libpng.dylib
&nbsp;
//What is the path where the file png.h can be found
PNG_PNG_INCLUDE_DIR:PATH=/sw/include
&nbsp;
//What is the path where the file tiff.h can be found
TIFF_INCLUDE_DIR:PATH=/sw/include
&nbsp;
//Where can the tiff library be found
TIFF_LIBRARY:FILEPATH=/sw/lib/libtiff.dylib
&nbsp;
//What is the path where the file zlib.h can be found
ZLIB_INCLUDE_DIR:PATH=/usr/include
&nbsp;
//Where can the z library be found
ZLIB_LIBRARY:FILEPATH=/usr/lib/libz.dylib


=== CMake Configuration for Solaris ===
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''.


=== CMake Configuration for AIX ===
On Linux and Mac, the default generator is ''Unix Makefiles'', so the build can be started by invoking the ''make'' executable:


=== CMake Configuration for Windows ===
  make


== Using a predefined Configuration ==
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 <tt>CMakeLists.txt</tt>) and the user customises them.
CMake can be run interactively to configure a build, in which case all settings begin with system defaults (as determined by <tt>CMakeLists.txt</tt>) 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 <tt>CMakeCache.txt</tt> in the top level of the build directory, the settings defined therein will be used to override the default settings for the build.
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 <tt>CMakeCache.txt</tt> 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 ===
* [[ITK/Configuring_and_Building/VisualStudio|Visual Studio]]
* [[ITK/Configuring_and_Building/QtCreator|QtCreator]]
* [[ITK/Configuring_and_Building/MinGW|MinGW]]


== Wrapping ITK ==
== Wrapping ITK ==
Line 161: Line 127:
ITK can be wrapped for several different languages such as Python, Tcl and Java.  
ITK can be wrapped for several different languages such as Python, Tcl and Java.  


* [[ITK Java Wrapping|Java wrapping]] guide
* [[ITK/Java Wrapping|Java wrapping]] guide
* [[ITK Python Wrapping|Python wrapping]] guide
* [[ITK/Python Wrapping|Python wrapping]] guide
* [[ITK/WrapITK Status|WrapITK status]]


{{ITK/Template/Footer}}
{{ITK/Template/Footer}}

Latest revision as of 19:12, 28 April 2019

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:

  1. cmake: A command line interface.
  2. ccmake: An ncurses (terminal) GUI. (only available on Unix-like systems).
  3. cmake-gui: A Qt-based GUI.

To perform a CMake configuration, we need three things:

  1. The source code directory.
  2. A different directory to perform the build (make this directory manually).
  3. 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.



ITK: [Welcome | Site Map]