Build CamiTK from source

Step-by-step guide to build CamiTK from source and set up the C++ developer environment.

Build CamiTK from source

Whether you’re an end-user/extension developer looking for the latest version or a developer wanting to contribute, this guide will help you set up your environment and build CamiTK.

Do you need to build CamiTK from source?

If you are not sure, just answer a few quick questions to get the right setup and see if this page is for you.

1. What is your platform?

Build process overview

Three steps to build CamiTK from source

1. Setup environment

Install the toolchain and dependencies.

2. Choose version

Stable or development branch.

3. Build and install

Compile and install CamiTK.

1. Setup the development environment

Install toolchain and dependencies on your machine

The following systems are fully supported by the CamiTK team:

Debian 14 Forky (and derived)
Ubuntu 26.04 LTS - Resolute Raccoon (and derived)
Windows 11

CamiTK 6.0.0 can also be built easily on Debian 13 Trixie, Ubuntu 24.04 LTS - Noble Numbat and derived.

For details on the supported versions of the toolchain and dependencies, see the CamiTK support policy.

Click below for OS-specific setup instructions

Setup instructions for Debian/Ubuntu and derived

Thanks to the power of debian, in order to install everything you need to build CamiTK, just type:

sudo apt update
sudo apt-get build-dep camitk

Copy/paste code snippets

You can easily copy all the bash code from this documentation by clicking on the Copy button in the top right corner of each code snippets… You can then paste in your terminal.

How to fix E: You must put some 'source' URIs in your sources.list

The error appears when you try to ask the system to get information about the camitk source packages but no source packages information (deb-src entries) are configured, see the Debian documentation. Basically you just need to add the repositories that contains the source code of the packages (so that apt-get can deduce which packages to install).

A simple way of doing this:

if ls /etc/apt/sources.list.d/*.sources >/dev/null 2>&1; then
    # Modern APT format (.sources)
    sudo cp -a /etc/apt/sources.list.d /etc/apt/sources.list.d.bak
    sudo sed -i 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/*.sources
else
    # Legacy APT format (sources.list)
    sudo cp -a /etc/apt/sources.list{,.bak}
    sudo sed -i 's/^#\s*deb-src/deb-src/' /etc/apt/sources.list
fi

And then try again:

sudo apt update
sudo apt-get build-dep camitk

How to fix E: You must put some 'deb-src' URIs in your sources.list

The error appears when you try to ask the system to get information about the camitk source package but no source packages information (deb-src entries) are configured, see the Debian documentation. Basically you just need to add the repositories that contains the source code of the packages (so that apt-get can deduce which packages to install).

A simple way of doing this:

if ls /etc/apt/sources.list.d/*.sources >/dev/null 2>&1; then
    # Modern APT format (.sources)
    sudo cp -a /etc/apt/sources.list.d /etc/apt/sources.list.d.bak
    sudo sed -i 's/^Types: deb$/Types: deb deb-src/' /etc/apt/sources.list.d/*.sources
else
    # Legacy APT format (sources.list)
    sudo cp -a /etc/apt/sources.list{,.bak}
    sudo sed -i 's/^#\s*deb-src/deb-src/' /etc/apt/sources.list
fi

And then try again:

sudo apt update
sudo apt-get build-dep camitk

How to fix E: Unable to find a source package for camitk

Your distribution cannot automatically find the list of dependencies as it does not have any camitk source package (camitk was not included in the official repository). You have to specify the correct and precise list of dependency names on the command line by entering:

For Linux distributions derived from Debian 14 Forky or Ubuntu 26.04 LTS - Resolute Raccoon:

# Using Qt6
sudo apt install git build-essential cmake libvtk9-dev qt6-base-dev qt6-tools-dev qt6-scxml-dev xsdcxx libinsighttoolkit5-dev libfftw3-dev libgdcm-dev libgdcm-tools libvtkgdcm-dev libpython3-dev python3-dev python3-pip python3-venv pybind11-dev python3-pyside6.qtwidgets python3-vtk9

For Linux distributions derived from Debian 13 Trixie, Ubuntu 24.04 LTS - Noble Numbat:

# Using Qt6
sudo apt install git build-essential cmake libvtk9-dev qt6-base-dev qt6-tools-dev qt6-scxml-dev xsdcxx libinsighttoolkit5-dev libfftw3-dev libgdcm-dev libgdcm-tools libvtkgdcm-dev libpython3-dev python3-dev python3-pip python3-venv pybind11-dev python3-pyside6.qtwidgets python3-vtk9

Additional packages required for Debian 13 Trixie, Ubuntu 24.04 LTS - Noble Numbat and derived

If sudo apt-get build-dep camitk worked on your OS, you will also need to install the following additional packages:

# Installing python binding requirements
sudo apt install libpython3-dev python3-dev python3-pip python3-venv pybind11-dev python3-pyside2.qtwidgets python3-vtk9

Cleanup a previously installed version

If you had previously installed a CamiTK stable development environment, please uninstall the package first. Make sure also that you have nothing installed locally in your user $HOME/.config/CamiTK directory.

Setup instructions for Windows 11

⚠ PATH on Windows and bloated machines

Warning

If there are already too many other software installed on your Windows machine, things can get difficult.

You have to be especially careful about the PATH environment variable. Some software will add path to their own installation directory where incompatible version of dependencies (for instance incompatible version Qt, which is a very popular library) will avoid you to setup the CamiTK development environment properly.

Another problem may arise when the PATH environment variable is already quite full. There is a limit to the length of this variable (or more exactly in the tool that modifies the variable value). If this limit is reached, setup the CamiTK development environment might not be done properly.

On Windows 11, it is therefore recommended:

if possible, to start from a fresh Windows 11 install (or a machine that does not already zillions of software installed)
check the value of the PATH environment variable to make sure:
- there is no older/other dependency DLL accessible through the path (e.g. older/other version of Qt)
- its length is not too close to the limit of 1023 characters (setx limit)

Windows 11 setup overview

Setting up a development environment requires that all the tool chain and dependencies from scratch should be installed on your machine. The dependencies will be compiled from the source most of the time, as they are not available as pre-compiled/installable packages.

We provide installation scripts that have to be run from a command shell with the admin privilege and will install chocolatey (a sort of application manager on Windows). This will take a little bit of time, but it is worth the trouble!

Check the support policy document for the currently supported/working version of the dependencies.

About the installation scripts

The installation scripts are the one we used to setup the CamiTK continuous integration. It should work out of the box, but it is given with no guarantee as there are a multiple of situations that depends on your machine, your machine history and the software already installed on your machine.

About chocolatey

In order to simplify everything for you, we recommend that you use chocolatey (a package manager for Windows). That’s what we are using ourself to install application and the toolchain on Windows.

It will help you have a greater control of what is installed on your machine (and where). Everything you install with chocolatey can be easily updated or uninstalled.

We also strongly suggest that you also use chocolatey to install any other available software on your Windows machine. It’s robust and you will get a simple way to update or uninstall the software.

⚠ Developer machine

If you already have some of the toolchain or library installed, and you know what you are doing, just check the installation scripts and cherry-pick the part you need.

To avoid multiple versions of the same tool or lib, we strongly recommend you start from scratch. The DLL hell is never far away…

① Download the setup scripts

Download the installation scripts archive and unzip it. sha256sum: dc521afc5bddcecfe1c63267691a2c0d5df09c9e1dc52b4f6adf98543cefdb41

② Open a command shell with elevated privilege

Launch a cmd shell with admin privilege.

How to start a terminal with admin privilege

You can read the official Microsoft documentation, which can be summarized to:

Click Start (also shown as the circular Windows logo in the Start menu).
Type Command Prompt and right-click Command Prompt when it appears in the Start menu. From the resulting context menu, click Run as administrator.

③ Run the setup scripts

The scripts should do everything for you automatically if you run them in the right order (hint: the script names have an index!). In the terminal with admin privilege:

cd c:\where\you\unzip\the\scripts
setup0-choco.bat
setup1-toolchain.bat
setup2-builddep.bat

Copy/paste code snippets

You can easily copy all the bash code from this documentation by clicking on the Copy button in the top right corner of each code snippets… You can then paste in your terminal.

Installation and build time

Each script might take a looooong time to run (some scripts are downloading package from the internet and others are building dependencies from source). It might take a while to complete, be patient, we promise it’s worth it!

Description of the installation scripts

util-vars.bat contains the default recommended installation directories. It defines the installation path as C:\camitk and the working setup directory as C:\setup.
util-dnd.bat contains the commands to download the dependencies’ source tarball
util-build.bat contains the commands to build a dependency from source
setup0-choco.bat installs chocolatey
setup1-toolchain.bat setups the environment variables, use chocolatey to install git, curl, 7zip, pedeps, python, visual studio 2022 buildtools, cmake, ninja and finally use aqtinstall to install Qt
setup2-builddep.bat downloads, configures, builds and patches (if needed) all the required dependencies (xercesc, xsdcxx, vtk, gdcm, and itk).

Results

setup1-toolchain.bat scripts should have configured your environment so that everything is ready for the next step.

C:\camitk contains the final development environment.
C:\setup contains all the intermediary files required for the installation (downloaded sources, extracted sources, build directories).

→ Only C:\camitk directory is required to build CamiTK from source after this stage.

Rebooting your machine now might be a good idea.

Setup instructions for other Linux distributions and Mac OSX

If you are not using a Debian-based distribution (Debian, Ubuntu, Mint, Pop! Linux…) or Windows, you will have to build or install the required packages manually.

The following packages are required to build CamiTK 6.0.0

g++ (or llvm C++ compiler)
cmake
vtk9
Qt6 base and tools as well as the scxml features (qtscxml in Homebrew)
xsdcxx (xsd in Homebrew)
gdcm 3
itk (insight toolkit)
python3, python venv and pip
pybind11

For details on the supported versions of the toolchain and dependencies, see the CamiTK support policy.

On both other Linux and Mac OSX, we strongly recommend to use Homebrew, which should have all these dependencies already available.

2. Choose the CamiTK version you need

Stable vs. Development versions (click to choose)

Stable Version (CamiTK 6.0.0)

Pros

Stable API
No breaking changes

Cons

No new features
Only critical bug fixes

Current version status: CamiTK 6.0.0

Development Version (CamiTK develop)

Pros

Latest features
Recent bug fixes

Cons

API may change
Less stable (but guaranteed to build)

Current continuous integration status: Develop branch pipeline status

Still not sure?

Use the development version if one of this is true:

You need a feature that is not yet in the stable version.
You want the latest updates.
You need the latest bug fixes not yet in the stable version.
You want to contribute to CamiTK development.
You’re curious and want to test new features.

See what’s new in CamiTK develop since the latest release version

Click on the version of your choice above, and then click on your OS to get the download instructions for the chosen version

Download CamiTK 6.0.0 source tarball (latest stable)

In the terminal:

# download the source tarball (~160Mb)
mkdir src
curl -L https://gricad-gitlab.univ-grenoble-alpes.fr/CamiTK/CamiTK/-/archive/6.0.0/CamiTK-6.0.0.tar.bz2 --output src/CamiTK-6.0.0.tar.bz2

# check download: this must print "CamiTK-6.0.0.tar.bz2: OK"
echo "09729dd0af747637bba6f1caf9172bd3f45710294c31373e193b6243227f7e47 src/CamiTK-6.0.0.tar.bz2" | sha256sum --check

# extract
tar -x --directory src -f src/CamiTK-6.0.0.tar.bz2

# set this CAMITK_SOURCE_DIR (it will be useful in the next step)
export CAMITK_SOURCE_DIR=$(pwd)/src/CamiTK-6.0.0

Download CamiTK develop

For the develop version, we recommend to clone the CamiTK git repository and switch to the develop branch. From the terminal:

# Clone and switch to the develop branch
git clone https://gricad-gitlab.univ-grenoble-alpes.fr/CamiTK/CamiTK.git src/CamiTK-git
git -C src/CamiTK-git checkout develop

# set this CAMITK_SOURCE_DIR (it will be useful in the next steps)
export CAMITK_SOURCE_DIR="$(pwd)/src/CamiTK-git"

Update regularly

Use git pull in the source $CAMITK_SOURCE_DIR directory to update the code every so often in order to get the most recent develop version. It provides the latest bug fixes and new features!

Download CamiTK 6.0.0 source tarball (latest stable)

Now that you have done all the hard work of installing the toolchain and dependencies, this step will be very easy!

In a command shell with elevated privilege:

set SETUP_DIR=C:\setup
set DND_DIR=%SETUP_DIR%\download
set SOURCE_DIR=%SETUP_DIR%\src
curl -L https://gricad-gitlab.univ-grenoble-alpes.fr/CamiTK/CamiTK/-/archive/6.0.0/CamiTK-6.0.0.tar.bz2 --output %DND_DIR%\CamiTK-6.0.0.tar.bz2
certutil -hashfile %DND_DIR%\CamiTK-6.0.0.tar.bz2 sha256
7z x "%DND_DIR%\CamiTK-6.0.0.tar.bz2" -so | 7z x -aoa -si -ttar -o"%SOURCE_DIR%"
move "%SOURCE_DIR%\CamiTK-6.0.0" "%SOURCE_DIR%\camitk"

Checksum

The command

certutil -hashfile %DND_DIR%\CamiTK-6.0.0.tar.bz2 sha256

must print

09729dd0af747637bba6f1caf9172bd3f45710294c31373e193b6243227f7e47

⚠ Re-installing CamiTK

If you had an existing installation of CamiTK, you may still have some files in AppData (usually ̀C:\Users\<username>\AppData\Roaming\CamiTK or %APPDATA%\CamiTK). Remove this CamiTK directory if it exists, as it might contain erroneous paths that will interfere with the next steps.

Download CamiTK develop

Now that you have done all the hard work of installing the toolchain and dependencies, this step will be very easy!

In a command shell with elevated privilege:

set SETUP_DIR=C:\setup
set SOURCE_DIR=%SETUP_DIR%\src
git clone https://gricad-gitlab.univ-grenoble-alpes.fr/CamiTK/CamiTK.git %SOURCE_DIR%/camitk
git -C %SOURCE_DIR%/camitk checkout develop

⚠ Re-installing CamiTK

Download CamiTK 6.0.0 source tarball (latest stable)

In the terminal:

# download the source tarball (~160Mb)
mkdir src
curl -L https://gricad-gitlab.univ-grenoble-alpes.fr/CamiTK/CamiTK/-/archive/6.0.0/CamiTK-6.0.0.tar.bz2 --output src/CamiTK-6.0.0.tar.bz2

# check download: this must print "CamiTK-6.0.0.tar.bz2: OK"
echo "09729dd0af747637bba6f1caf9172bd3f45710294c31373e193b6243227f7e47 src/CamiTK-6.0.0.tar.bz2" | sha256sum --check

# extract
tar -x --directory src -f src/CamiTK-6.0.0.tar.bz2

# set this CAMITK_SOURCE_DIR (it will be useful in the next step)
export CAMITK_SOURCE_DIR=$(pwd)/src/CamiTK-6.0.0

Download CamiTK develop

For the develop version, we recommend to clone the CamiTK git repository and switch to the develop branch. From the terminal:

# Clone and switch to the develop branch
git clone https://gricad-gitlab.univ-grenoble-alpes.fr/CamiTK/CamiTK.git src/CamiTK-git
git -C src/CamiTK-git checkout develop

# set this CAMITK_SOURCE_DIR (it will be useful in the next steps)
export CAMITK_SOURCE_DIR="$(pwd)/src/CamiTK-git"

Update regularly

Use git pull in the source $CAMITK_SOURCE_DIR directory to update the code every so often in order to get the most recent develop version. It provides the latest bug fixes and new features!

3. Build and install CamiTK

Build and install the CamiTK chosen version

Follow the instructions for your platform

Build and install CamiTK

Building CamiTK from source is very easy thanks to the power of CMake.

# set the installation directory (change to wherever you want)
export CAMITK_INSTALL_DIR="$(pwd)/install"
mkdir $CAMITK_INSTALL_DIR

# configure ($CAMITK_SOURCE_DIR is the CamiTK source code directory, see step 2)
cmake -S $CAMITK_SOURCE_DIR \
      -B build \
      -DCMAKE_INSTALL_PREFIX=$CAMITK_INSTALL_DIR \
      -DCEP_IMAGING=TRUE \
      -DCEP_MODELING=TRUE \
      -DCEP_TUTORIALS=TRUE \
      -DPYTHON_BINDING=TRUE 

# parallel build (with 6 parallel process, requires ~5Gb or RAM and 6+ cores)
cmake --build build --target install --parallel 6

How to fix: Could not find a package configuration file provided by 'pybind11'

On Debian 13 Trixie, Ubuntu 24.04 LTS - Noble Numbat and any Linux distributions derived from them, you need to install the following additional packages (see note “Additional packages required…” in the first step):

# Installing python binding requirements
sudo apt install libpython3-dev python3-dev python3-pip python3-venv pybind11-dev python3-pyside2.qtwidgets python3-vtk9

How to fix build freeze/out of memory during build

If you run out of memory or your system hanged during build, lower the number of parallel process.

In the line above, this can be done by replacing the 6 in --parallel 6 by an integer X, where X is a number lower that your number of CPU (with a margin) and where the amount of available RAM on your system divided by X is greater than 3 (to reserve a maximum 3Gb of RAM for each parallel process).

Check the installation

Type this in the terminal:

$CAMITK_INSTALL_DIR/bin/camitk-config --config

This should print details information about camitk version, the line Global Installation Directory is equal to $CAMITK_INSTALL_DIR (where you installed CamiTK).

Run camitk-imp

You can run camitk-imp by (double) clicking on the executable in your favorite file browser (in the bin directory) or by typing this in the terminal:

$CAMITK_INSTALL_DIR/bin/camitk-imp

Build and install CamiTK

In the terminal with admin privilege:

cd c:\where\you\unzip\the\scripts\in\step\1
setup3-buildcamitk.bat

This will configure and build the downloaded CamiTK version.

Check the installation

Run camitk-imp

After the compilation and installation, you can use CamiTK as a user (run an application provided by the community edition) or a developer (to develop your own CEP). Binary executables are located in C:\camitk\bin. Just double-click on camitk-imp.exe or any other provided application (note that you need a command prompt to run camitk-config.exe which is a console application, see below).

Run camitk-config

Launch a new command shell and type:

cd C:\camitk\install\bin
camitk-config --config

This should print details information about camitk version, where camitk is looking for extensions (aka the extension repository), and the default installed extensions.

Build and install CamiTK

Building CamiTK from source is very easy thanks to the power of CMake.

# set the installation directory (change to wherever you want)
export CAMITK_INSTALL_DIR="$(pwd)/install"
mkdir $CAMITK_INSTALL_DIR

# configure ($CAMITK_SOURCE_DIR is the CamiTK source code directory, see step 2)
cmake -S $CAMITK_SOURCE_DIR \
      -B build \
      -DCMAKE_INSTALL_PREFIX=$CAMITK_INSTALL_DIR \
      -DCEP_IMAGING=TRUE \
      -DCEP_MODELING=TRUE \
      -DCEP_TUTORIALS=TRUE \
      -DPYTHON_BINDING=TRUE 

# parallel build (with 6 parallel process, requires ~5Gb or RAM and 6+ cores)
cmake --build build --target install --parallel 6

How to fix: Could not find a package configuration file provided by 'pybind11'

# Installing python binding requirements
sudo apt install libpython3-dev python3-dev python3-pip python3-venv pybind11-dev python3-pyside2.qtwidgets python3-vtk9

How to fix build freeze/out of memory during build

If you run out of memory or your system hanged during build, lower the number of parallel process.

Check the installation

Type this in the terminal:

$CAMITK_INSTALL_DIR/bin/camitk-config --config

This should print details information about camitk version, the line Global Installation Directory is equal to $CAMITK_INSTALL_DIR (where you installed CamiTK).

Run camitk-imp

You can run camitk-imp by (double) clicking on the executable in your favorite file browser (in the bin directory) or by typing this in the terminal:

$CAMITK_INSTALL_DIR/bin/camitk-imp

Next Steps

Develop your own extension

Extension Developer Documentation

Dive deeper into CamiTK framework

CamiTK Architecture

Extensions Overview

Frames and Transformations

Medical Image Anatomical Orientation

Log System

Automatic Test (for C++)

Build CamiTK from source

Do you need to build CamiTK from source?

1. What is your platform?

2. What do you want to do?

3. Development type?

4. Which features do you need?

5. Is the available version of the package in your distribution ≥ 6.0.0 ?

Build process overview

Three steps to build CamiTK from source

1. Setup environment

2. Choose version

3. Build and install

1. Setup the development environment

Install toolchain and dependencies on your machine

Setup instructions for Debian/Ubuntu and derived

Cleanup a previously installed version

Setup instructions for Windows 11

Windows 11 setup overview

① Download the setup scripts

② Open a command shell with elevated privilege

③ Run the setup scripts

Results

Setup instructions for other Linux distributions and Mac OSX

2. Choose the CamiTK version you need

Stable vs. Development versions (click to choose)

Stable Version (CamiTK 6.0.0)

Pros

Cons

Development Version (CamiTK develop)

Pros

Cons

Download CamiTK 6.0.0 source tarball (latest stable)

Download CamiTK develop

Download CamiTK 6.0.0 source tarball (latest stable)

Download CamiTK develop

Download CamiTK 6.0.0 source tarball (latest stable)

Download CamiTK develop

3. Build and install CamiTK

Build and install the CamiTK chosen version

Build and install CamiTK

Check the installation

Run camitk-imp

Build and install CamiTK

Check the installation

Run camitk-imp

Run camitk-config

Build and install CamiTK

Check the installation

Run camitk-imp

Next Steps

Develop your own extension

Dive deeper into CamiTK framework