ITK External Module GitHub builds for 4.X and 5.X

As described in the ITKModuleTemplate README, it is possible to build and develop ITK modules on GitHub. The ITKModuleTemplate creates a configuration with continuous integration testing to build and test the module on Linux and build Python packages for Linux, macOS, and Windows.

The builds, by default, use the latest released version of ITK, including the ITK 5.0 alpha tags. With the transition to C++11, the Python packages are not expected to be compatible between ITK 4 and ITK 5.

It is possible to develop and test the module against both 4.13 and 5.X. Here are the steps:

  • Create a branch, e.g. release or ITKv4. Push this branch to GitHub and develop for 4.13 on this branch, while 5.X development can occur on master.
  • In the build-and-test section of .circleci/config.yml, build with the insighttoolkit/module-ci:v4.13 instead of the insighttoolkit/module-ci:latest image.
  • In the package section of .circleci/config.yml, set export ITK_PACKAGE_VERSION=v4.13.0 before calling
  • In .travis.yml add - export ITK_PACKAGE_VERSION=v4.13.0 before calling
  • In appveyor.yml, set the build command to $env:ITK_PACKAGE_VERSION='v4.13.0'; .\windows-download-cache-and-build-module-wheels.ps1
  • In set install_requires to itk<5
  • On the 5.X development branch, set the version= value in to a pre-release version, i.e. X.YaN, X.YbN, or X.YrcN where X.Y are higher numbers than the versions on the 4.X branch. This will ensure that a user can install the 4.X-based package with pip install itk-mymodule or the 5.X-based package with pip install --pre itk-mymodule.

This patch provides as an example.


A caveat discovered by @blowekamp for Remote Modules:

To update an ITKv4 remote module that has move ITKv4 to a named branch, e.g. ITKv4 separate from master, call

git checkout master
git merge ITKv4 --strategy ours

To help the Git fetching system retrieve the desired history.

1 Like

Reporting my experience using this in:

So I am creating a ITKv4 branch for a module.
If I create a new branch ITKv4 from master, and use:

git checkout master
git merge ITKv4 --strategy ours

I got:

Already up to date.

Which makes sense.

So, I create a diverging commit in ITKv4:

git commit -m 'COMP: Change CI to use ITKv4'

You can push the branch in the module repo:

git push --set-upstream origin ITKv4 

And now the result of:

git checkout master
git merge ITKv4 --strategy ours

Creates a new commit in the master branch: Merge branch ITKv4

The log shows:

git diff HEAD~1 is empty, so master has not been changed with the changes in ITKv4.

And the last step is to push master branch: git checkout master ; git push

Let me know if this workflow can be improved. Thanks!

1 Like

Correct @phcerdan – thanks for sharing the additional information!

Another point to add to the steps in the first post is to keep minimun required version of cmake compatible with ITKv4:

  • ITKv5 upgraded the minimum required version of CMake to 3.10.2, but the ITKv4 branch in the module should avoid this upgrade and keep aligned with ITKv4. The top-level CMakeLists.txt in the ITKv4 branch should have:
    cmake_minimum_required(VERSION 2.8.12)
    This also avoids errors with the continuous integration scripts for ITKv4, that would fail if the required CMake version is very modern.
1 Like