Building SimpleITK¶
In many cases a user does not need to build SimpleITK because of the available pre-built binaries (see Downloading the binaries). However there are several reasons a user might prefer to build SimpleITK from source code:
- The binary files for your programming language of choice are not (yet) distributed
- You want the live on the bleeding edge by using the latest-and-greatest version of SimpleITK
- You want to wrap your own filters using the SimpleITK infrastructure
- You want to contribute to the development of SimpleITK
- To use the SimpleITK’s C++ interface and/or use ITK directly
Prerequisites¶
To build SimpleITK you need:
- A recent version of CMake >= 3.10 with SSL support for https.
- A supported compiler.
- To use the latest developmental version, source code can be
downloaded with git >= 1.65
- Git is required if building SimpleITK using “SuperBuild” (see below) to automatically download the matching version of ITK, SWIG, etc…
- Windows users may prefer msysGit
- It is recommended to have numpy installed when testing Python bindings
- The R package requires R version 3.3 or greater.
- The Lua package requires Lua version 5.1 or greater.
Recipes / Formulas / Short cuts¶
Before you start please make sure you have the required Prerequisites installed.
For some environments we have short cuts, scripts, for automated building of SimpleITK (see their repository for more details):
- For Python: The scikit-build based distutils based setup.py frontend can be used to build, install, and package SimpleITK for Python.
- For the Anaconda Python distribution: The recipe and instructions for the SimpleITK build are in this GitHub repository.
- For the R language (version 3.3 or greater): A devtools installer and instructions are available from this GitHub repository.
- On the Mac, with the Homebrew package manager, a SimpleITK formula is available: https://github.com/Homebrew/homebrew-science/blob/master/simpleitk.rb for multiple language wrappings.
- For the Lua language with the Luarocks module deployment system, a SimpleITK rockspec is available at the Luarocks repository or from this GitHub repository.
Source code¶
If one of the above language specific front-ends are not used then SimpleITK must be built directly.
Before you start please make sure you have the required Prerequisites installed.
All of the instructions assume you are working on the command line.
Words of caution for building on the Windows operating system:
- Windows has issues with long directory paths. We recommend cloning the source code near the root (e.g. C:\src).
- To avoid potential issues do not clone the source into a path which has spaces in the directory name (e.g. C:\Users\SimpleITK Source).
First obtain the SimpleITK source code:
- Download the latest development version using git
git clone https://itk.org/SimpleITK.git
Building using SuperBuild¶
After downloading SimpleITK’s source code we STRONGLY recommend running cmake on the SuperBuild subdirectory of SimpleITK. Execute the following commands in the parent of the SimpleITK source directory to configure the SuperBuild:
mkdir SimpleITK-build
cd SimpleITK-build
cmake ../SimpleITK/SuperBuild
The SuperBuild will automatically download and build the matching versions of ITK, SWIG, Lua, and GTest (if testing is enabled) needed to compile SimpleITK.
If you get an error message saying that ITK_DIR is not set then, you did not correctly point cmake to the SuperBuild sub-directory. Please erase your binary directory, and point cmake to the SimpleITK/SuperBuild sub-directory.
The CMake configuration process should automatically find supported languages and enable SimpleITK wrapping for them. To manually enable a language toggle the appropriate WRAP_LANGUAGE cmake variable to ON. Verify and correct the advanced cmake variables for the language specific executable, libraries and include directories. For example if you have multiple Python installations ensure that all related Python variables refer to the same versions.
Then use your make utility or your cmake chosen build utility to build SimpleITK. As the SimpleITK build process may take a while, it is important to use the appropriate flags to enable multi-process compilation i.e. “-j” for make, “/MP” for Visual Studio, or use the CMake Ninja generator.
Building Manually¶
By not using the superbuild, you must manually specify all dependencies used during the building of SimpleITK instead of using the known working versions provided by the superbuild as external projects. This may be useful if you are providing a system package of SimpleITK or tightly integrating it into another build system. The versions of external projects used and tested by SimpleITK can be found by examining the External CMake files in the Superbuild sub-directory.
Additional Prerequisites¶
The following are dependencies you will need when not using the SuperBuild:
- Setup the prerequisites as described above (i.e. CMake and supported compiler)
- Insight Toolkit (ITK) the version specified in the External_ITK.cmake file is the version of ITK used for the binary release. This can be seen as the minimum version of ITK to be used with SimpleITK, as future ITK versions are generally backwards compatible.
- Lua 5.1
- SWIG >= 3.0.11
- GTest or Google >= 1.0.8 is needed if testing is enabled.
Configuration and Building¶
After the source code is obtained, SimpleITK can be configured on Unix-like systems like so:
mkdir SimpleITK-build
cd SimpleITK-build
cmake ../SimpleITK
If all the dependencies are installed in standard places, then the CMake configuration should detect them properly. Otherwise, if there are configuration errors, the proper CMake variable should be set. CMake variables can be either set with a CMake interactive GUI such as ccmake or cmake-qt, as arguments on the command line by using the following format: -D<var>=<value>, or by editing the CMakeCache.txt file.
After proper configuration, SimpleITK can be built:
make -j$(nproc)
Advanced Build Options¶
SimpleITK is aware of the modularity of ITK and automatically enables and disables filters based on which modules are available from the ITK build which SimpleITK is compiled against. This makes it possible to customize SimpleITK to be a small library or to wrap additional ITK remote modules simply by configuring ITK with the desired modules enabled.
For example, the CoherenceEnhancingDiffusionImageFilter is an optional filter in SimpleITK as it’s part of the ITK remote module AnisotropicDiffusionLBR. This remote module is not enabled by default when building ITK and SimpleITK. To enable it when using SimpleITK’s Superbuild add -DModule_AnisotropicDiffusionLBR:BOOL=ON to the command line or in the CMake GUI press the “Add Entry” button to define the variable as above.
SimpleITK has a very flexible and robust build system utilizing CMake. It enables packagers to build SimpleITK in a variety of ways to suit their requirements and minimize recompilation of SimpleITK so that it can be wrapped for many different languages. Each of the language wrapping sub-directories e.g. “Wrapping/Python” can be configured and built as an independent project which is dependent on SimpleITK as an installed package of its libraries and header filers.
Testing¶
After compilation the prudent thing to do is to test SimpleITK to ensure that your build is stable and suitable for installation and use. The following commands execute the SimpleITK tests.
cd SimpleITK-build/SimpleITK-build
ctest .
On Windows you will need to specify configuration. Typically that would be the Release configuration, as such:
cd SimpleITK-build/SimpleITK-build
ctest -C Release
Installation from Build Tree¶
Python Installation¶
To install a built python package into the system Python, as root run:
cd SimpleITK-build/Wrapping/Python
python Packaging/setup.py install
Alternatively, a Python virtual environment can be created and the distribution installed there.
A Python Wheel file (.whl) can be created in the “Wrapping/Python/dist” directory, by building the “dist” target. If you have used the Superbuild with the “make” generator then issue the following command:
make -C SimpleITK-build dist
R Installation¶
To install a built R package:
cd SimpleITK-build/Wrapping/R/Packaging
R CMD INSTALL SimpleITK
This will install the R package “SimpleITK” in /usr/local as root or your local R installation directory.
If you are working in a multi-user environment, and are considerate of your fellow users you can install the package in a local directory:
- Create a local directory where you will install your R packages
mkdir my_R_libs
- Add an environment variable to your .bashrc
export R_LIBS="/path_to/my_R_libs"
- source your .bashrc and check the R library path, in an R shell
.libPaths()
- install
cd SimpleITK-build/Wrapping/R/Packaging
R CMD INSTALL -l /path_to/my_R_libs SimpleITK