-
-
Notifications
You must be signed in to change notification settings - Fork 381
Compiling ANTs on Linux and Mac OS
This installation guide is for Linux and Mac users. Windows users who wish to install using the Linux subsystem will need CMake and Git, and can then clone ANTs and compile using the instructions on this page.
The instructions here will perform a "SuperBuild", which will automatically build the correct versions of ITK (required) and VTK (optional) for ANTs. Most ANTs users will find it easiest to use the SuperBuild. Advanced users can use system ITK or VTK.
If you navigated directly to this page, you might be interested in other options for installing ANTs without needing to compile from source.
A downloadable script to build and install ANTs locally is available here.
Here is a very minimal example. This example works if you have all the necessary tools, including CMake and a supported compiler. The system requirements and installation steps are discussed in more detail below.
workingDir=${PWD}
git clone https://github.com/ANTsX/ANTs.git
mkdir build install
cd build
cmake \
-DCMAKE_INSTALL_PREFIX=${workingDir}/install \
-DBUILD_TESTING=OFF \
-DRUN_LONG_TESTS=OFF \
-DRUN_SHORT_TESTS=OFF \
../ANTs 2>&1 | tee cmake.log
make -j 4 2>&1 | tee build.log
cd ANTS-build
make install 2>&1 | tee install.log
ANTs requires a compiler that is able to compile ITK. The compilers used by the developers are usually GCC and Apple clang. If compilation fails on a very new or old version of these compilers, try GCC 7 or Apple clang 12.0.0, which are known to work as of March 2022.
CMake is available as source or a binary package from
You can also install it through a package manager for your system such as yum, apt, or Homebrew.
The supported CMake versions usually mirror those for ITK. Configuration of ANTs will fail immediately if the CMake version is not supported.
First install XCode, then get the command line tools from the Terminal with
xcode-select --install
The developer tools are usually installed in Linux. If not, there are several routes to install the required tools, depending on the Linux installation. Look for "developer tools" packages for your Linux distribution.
git clone https://github.com/ANTsX/ANTs.git
You can also download code snapshots as a ZIP file from Github, but you will still need git installed for the SuperBuild to work.
The build directory must be outside the source tree. Make a build directory, cd to it, then run cmake with command line options or ccmake for the GUI. The build directory is not the final install location. You will set the prefix in CMake where you want to install the executables and libraries, but that is a separate command after the build completes.
# make a build and install dir
mkdir build install
cd build
ccmake ../ANTs
In the GUI, hit 'c' to do an initial configuration. CMake will do some checking and then present options for review. You should set CMAKE_INSTALL_PREFIX to where you want to install ANTs. This needs to be somewhere that you have write access. Set any other options you need here as well.
Hit 'c' again to do another round of configuration. If there are no errors, you're ready to generate the make files by pressing 'g'.
Now you are back at the command line, it's time to compile.
make 2>&1 | tee build.log
The last part of the command here records the terminal output to a file build.log. This is optional, but you must do this if you need to report an issue. If you don't have the tee command installed, you can do
make > build.log 2>&1
but you will not see output to the terminal.
To speed up compilation, you can use multiple threads, for example:
make -j 2 2>&1 | tee build.log
will use two threads. Note that multiple threads will require more RAM as well as CPU resources. If your build seems slow for the number of threads, exits with errors, or hangs up entirely, try building with a single thread. You can also save time by turning off RUN_LONG_TESTS in CMake, or by turning off testing entirely.
If all went well, make will exit with code 0, after printing
[100%] Built target ANTS
You can also check for the empty file CMakeFiles/ANTS-complete under the build directory.
After compilation completes, you will see a subdirectory ANTS-build. This is the location from which you will run the install.
cd ANTS-build
make install 2>&1 | tee install.log
This will copy the binaries and libraries to bin/ and lib/ under CMAKE_INSTALL_PREFIX.
Set the PATH to include the bin directory under whatever you used for CMAKE_INSTALL_PREFIX. For example, if your install prefix was /opt/ants, there will now be a binary directory /opt/ants/bin, containing the ANTs executables and scripts.
export PATH=/opt/ants/bin:$PATH
Now check this worked correctly:
which antsRegistration
should print out the full path to antsRegistration, and
antsRegistrationSyN.sh
should print out the usage for that script. You can put the above variable definitions in your shell initialization file, so future sessions will have them set automatically. On a Mac, this is usually ~/.profile, on Linux ~/.bash_profile.
ANTs scripts prior to v2.5.0 require ANTSPATH as well as PATH, where ANTSPATH points to the bin directory including a trailing slash.
export ANTSPATH=/opt/ants/bin/
export PATH=${ANTSPATH}:$PATH
Many ANTs programs use multi-threading. By default, one thread will be generated for every CPU core on the system. This might be acceptable on a single-user machine but in a cluster environment, you will need to restrict the number of threads to be no more than the number of cores you have reserved for use.
Set the environment variable
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS
to control the number of threads ANTs will use.
On a desktop computer, a sensible value for this is the number of physical cores. For example, on an iMac with a quad-core CPU (8 virtual cores), set this variable to 4, or less than 4 if you want to save more CPU time for other processes.
Github has made some changes to its connection protocols that might cause the build to fail.
Older ANTs code used the deprecated unencrypted git:// protocol by default. This can be changed by setting the option SuperBuild_ANTS_USE_GIT_PROTOCOL OFF in CMake or ccmake. The latest code should use https:// consistently.
CMake Error: install(EXPORT "ITKTargets" ...) includes target "gdcmjpeg8" more than once in the export set.
This is a known issue with CMake 3.19.0 and 3.19.1.
https://gitlab.kitware.com/cmake/cmake/-/issues/21529
Compile with CMake 3.19.2 or later.
If the build hangs during compilation of some code, it may be because the build is running out of RAM. You can reduce memory burden by compiling with fewer threads. Disabling testing may also help, set BUILD_TESTING to OFF in CMake. Alternatively, you can increase the memory available to the build process.
If you have multiple compilers, or CMake can't find the right one for some reason, set variables before building:
export CC=/usr/bin/cc
export CXX=/usr/bin/c++
ccmake ~/code/ANTs
-
Try building with a single thread. Resource limits or timeouts can lead to incomplete compilation, resulting in errors.
-
Ensure that you have a compiler that can build ANTs. If using a brand new or very old compiler, try one that is known to build ITK.
-
If using system ITK or VTK, try a SuperBuild. Through the efforts of developers and contributors, ANTs tries to keep up with the innovations and C++ implementation updates in ITK. This means the ITK version required by ANTs changes fairly frequently and is often not backwards compatible.
-
If building with testing on, there can be difficulties reaching the servers to download test data. ANTs prior to 2.4.0 will not work with testing on, because it uses deprecated MD5 hashes to identify the test data.
This is a result of the compiler using instruction sets that are not supported by some CPUs. By default, the target architecture is "corei7", which works for most modern PCs and Macs. But some users may need to change the compiler architecture options used by CMake by adding
-DSuperBuild_ANTS_C_OPTIMIZATION_FLAGS="-mtune=native -march=native" \
-DSuperBuild_ANTS_CXX_OPTIMIZATION_FLAGS="-mtune=native -march=native"
to the cmake call. This will target the build to the machine used to compile ANTs. To make a more portable build, replace -march=native with "-march=x86-64".
Related issue: 764.
If you see something like
CMake Error at cmake_install.cmake:37 (file):
file cannot create directory: /opt/ants/bin. Maybe need administrative
privileges.
make: *** [install] Error 1
The fastest way to fix this is with the DESTDIR variable:
make install DESTDIR=/new/install/dir
This will install the binaries under ${DESTDIR}/${CMAKE_INSTALL_PREFIX}, which by default is ${DESTDIR}/opt/ants/bin. Alternatively, you can reconfigure the install directory with CMake:
cmake -DCMAKE_INSTALL_PREFIX=/new/install/dir .
make install
CMake may incorrectly report the system architecture.
On Apple Silicon hosts, the architecture printed by uname -m may vary based on CMake's own architecture and that of the invoking process tree.
See documentation for CMAKE_HOST_SYSTEM_PROCESSOR. This results in a failure to build anything (including ITK) with the error unknown target CPU 'apple-m1'.
You can check your cmake architecture with file, eg file /usr/local/bin/cmake.
If the problem persists, add -DCMAKE_OSX_ARCHITECTURES=arm64 to the cmake call.
If you still have problems, try searching the ANTs issues here on Github.
You may open an issue to report the error and seek help from the ANTs community. Please see the issue template for build issues, and include all the relevant attachments.
For developers and advanced users who are not using the default Superbuild.
VTK is required for the antsSurf program. VTK can be downloaded and built as part of the Superbuild, by setting USE_VTK=ON in CMake.
If you wish to use a pre-compiled system version of either ITK or VTK, it must be a compatible version for the ANTs source you are working from. The ITK version changes most frequently. The required ITK version can be found in the ANTs source here and the VTK version here. These files also show the required modules for building ITK and VTK for compatibility with ANTs.