Modernize ITK Module System with CMake Interface Libraries #5721

blowekamp · 2026-01-07T21:14:46Z

This PR introduces modern CMake interface libraries for ITK modules, enabling clean target-based linking and proper transitive dependency propagation.

Key Changes

CMake Interface Libraries - Created ${ModuleName}Module interface library for each ITK module with:
- Module-specific include directories using generator expressions
- Automatic transitive dependency linking
Target-Based Includes - Replaced directory-level include_directories() with target properties:
- Uses target_include_directories() with BUILD_INTERFACE/INSTALL_INTERFACE
- Proper PUBLIC propagation of includes and dependencies
- Fixed header-only module compilation

Example Modernization - Updated examples to use specific module targets:

target_link_libraries(MyExample
  PRIVATE
    ITK::ITKImageGradientModule
    ITK::ITKImageIO
)

Enhanced Tooling - Improved WhatModulesITK.py with --link option to generate updated target_link_libraries commands
Factory Registration - Properties part of factory meta-modules

Interface meta-modules for factories: ITKImageIO, ITKMeshIO, ITKTransformIO and FFTImageFilterInit factories. Factory modules will be added as dependencies to these meta-module. When itk_generate_factory_registration() is called, it adds the include directory containing the generated FactoryRegisterManager header file.

Example Usage:

find_package(ITK REQUIRED)
itk_generate_factory_registration()
 target_link_libraries(MyExample
     PRIVATE
       ITK::ITKCommonModule
       ITK::ITKImageIO
)

Benefits

Cleaner, more maintainable CMake code
Explicit module dependencies (no more monolithic ${ITK_LIBRARIES})
Faster builds with minimal linking
Modern CMake best practices

Compatibility

External modules should use itk_module_add_library() for automatic target properties
Directory level include may need to be added for some External ITK Modules
Legacy ${ITK_LIBRARIES} pattern still supported

dzenanz · 2026-01-07T21:28:14Z

PR description sounds amazing! Now diving into the review.

dzenanz

I am glad you are working on this! Does this work? What else is needed, besides changing the rest of the examples?

CMake/ITKModuleMacros.cmake

CMake/ITKModuleEnablement.cmake

hjmjohnson

@blowekamp AMAZING! Thank you for tackling this. It is long overdue!

dzenanz · 2026-01-08T15:48:49Z

f8488a7 configures and builds locally, in Debug and RelWithDebInfo modes, including examples. CMake 4.2.1, VS 2022. Tests in RelWithDebInfo mode succeed.

CMake/ITKModuleEnablement.cmake

CMake/ITKModuleMacros.cmake

thewtex · 2026-01-08T19:26:33Z

Woohoo!

Copilot

Pull request overview

This PR modernizes the ITK module system by introducing CMake interface libraries (${ModuleName}Module) that provide target-based dependency management and proper transitive propagation of include directories and dependencies. This replaces the legacy directory-level include_directories() approach with modern target-specific target_include_directories() calls using generator expressions.

Key Changes:

Created interface libraries for each ITK module with automatic transitive dependency linking
Migrated from directory-level includes to target-based includes using BUILD_INTERFACE/INSTALL_INTERFACE generator expressions
Updated 60+ filtering examples to explicitly link against specific module targets instead of the monolithic ${ITK_LIBRARIES}

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
Utilities/Maintenance/WhatModulesITK.py	Enhanced script with argparse and new --link option to generate target_link_libraries commands; improved regex pattern for module detection
CMake/ITKModuleMacros.cmake	Added interface library creation for modules, migrated to target-based include directories with generator expressions, added transitive dependency linking
CMake/ITKModuleInfo.cmake.in	Added INCLUDE2_DIRS variable to support generator expression-based include directories
CMake/ITKModuleHeaderTest.cmake	Updated header tests to use target-based include directories
CMake/ITKModuleEnablement.cmake	Created factory meta-module interface libraries (ITKImageIO, ITKMeshIO, ITKTransformIO)
CMake/ITKModuleAPI.cmake	Added INCLUDE2_DIRS propagation through module configuration
Modules/ThirdParty/MetaIO/src/CMakeLists.txt	Added directory-level includes as compatibility workaround for third-party modules
Modules/ThirdParty/HDF5/CMakeLists.txt	Added directory-level includes as compatibility workaround for third-party modules
Examples/Filtering/CMakeLists.txt	Converted all examples from `${ITK_LIBRARIES}` to explicit module targets with Module suffix and factory meta-modules

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Modules/ThirdParty/MetaIO/src/CMakeLists.txt

Modules/ThirdParty/HDF5/CMakeLists.txt

CMake/ITKModuleMacros.cmake

Utilities/Maintenance/WhatModulesITK.py

blowekamp · 2026-01-08T20:36:42Z

Thank you @copilot for the thorough review! I've addressed the actionable feedback in the latest commit:

Fixed:

✅ Removed the commented-out include_directories() and link_directories() blocks
✅ Removed the if(TRUE) conditional wrapper around the ${itk-module}Module creation
✅ Removed trailing space in itk_module_target_install(${itk-module}Module)
✅ Removed commented-out debug messages
✅ Fixed the module count bug in WhatModulesITK.py where len(allModules) was reported after base modules were discarded in --link mode

Regarding directory-level includes in third-party modules (MetaIO/HDF5):
These include_directories() calls are intentional compatibility exceptions for third-party code that doesn't use modern CMake target-based practices. Adding explanatory comments is a good suggestion - I can add those in a follow-up commit if the maintainers would like, though they're not critical to this PR's main goal.

blowekamp · 2026-01-08T20:44:15Z

In SimpleITK the PR SimpleITK/SimpleITK#2475 is using this branch along with cmake FetchContent with ITK. Additionally it is build ITK in a super build and separate build are using ITK from the source or from the build tree. They seem to be working.

The one exception is the build with Elastic, which is encountering a Sobel filter related error 😸

Copilot

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 13 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Examples/DataRepresentation/Mesh/CMakeLists.txt

Modules/ThirdParty/MetaIO/src/CMakeLists.txt

Examples/IO/XML/CMakeLists.txt

Examples/SpatialObjects/CMakeLists.txt

Examples/Statistics/CMakeLists.txt

Utilities/Maintenance/WhatModulesITK.py

Modules/ThirdParty/HDF5/CMakeLists.txt

Examples/IO/test/CMakeLists.txt

Examples/SpatialObjects/CMakeLists.txt

Examples/Iterators/CMakeLists.txt

blowekamp · 2026-01-09T13:33:40Z

@bradking Would you be able to provide feedback on this PR?

mathstuf

Some high-level recommendations based on VTK module experience:

add alias targets for all targets that match what find_package(ITK) users see
highly recommend exporting with ITK:: namespace (it will help with CPS support in the future)
use EXPORT_NAME property to name the post-:: install target rather than the core target name (a mistake from VTK's module system because I was unaware of the property)
use FILE_SET source listings so that you don't even need target_include_directories and header installation Just Works™ even with subdirectories (VTK opportunistically does it, but still supports even CMake 3.12(!))

CMake/ITKFactoryRegistration.cmake

CMake/ITKModuleAPI.cmake

CMake/ITKModuleHeaderTest.cmake

CMake/ITKModuleMacros.cmake

mathstuf · 2026-01-09T14:39:31Z

CMake/ITKModuleMacros.cmake

+    set(
+      itk-module-RUNTIME_LIBRARY_DIRS-install2
+      "$<INSTALL_INTERFACE:\${ITK_INSTALL_PREFIX}/${ITK_INSTALL_RUNTIME_DIR}>"
+    )


There's an open CMake feature request for runtime usage requirements like this. But it's not implemented yet.

mathstuf · 2026-01-09T14:44:00Z

Some of those recommendations might be out-of-scope for this PR.

blowekamp · 2026-01-09T20:05:29Z

Thank you @mathstuf. You comments have lead me to clean thing up significantly and still finding more things to remove too.

mathstuf

Looks much cleaner. Some more cleanups are still available though.

mathstuf · 2026-01-10T05:22:41Z

CMake/ITKModuleEnablement.cmake

+      ${itk_module}
+      PROPERTIES
+        EXPORT_NAME
+          ITK::${itk_module}


This should just be ${itk_module} and the namespace come from the install(EXPORT) and export(EXPORT) calls.

CMake/ITKModuleEnablement.cmake

CMake/ITKModuleMacros.cmake

mathstuf · 2026-01-10T05:25:38Z

CMake/ITKModuleMacros.cmake

+    ${itk-module}Module
+    PROPERT
+    EXPORT_NAME
+    ITK::${itk-module}Module


Same stuff as above.

CMake/ITKModuleMacros.cmake

Examples/DataRepresentation/Image/CMakeLists.txt

dzenanz · 2026-01-13T16:38:13Z

Did you close the PR intentionally?

blowekamp · 2026-01-13T16:41:49Z

The current install and export in ITK are done on a per target basis, so changing that would be a separate effort.

With the current set of target property EXPORT_NAME only the selected targets are getting the ITK:: namespace. This is appealing because it only add a namespace to the new ITK interface libraries. However, if one call to export() contains the NAMESPACE keyword to a select target, then ALL export ITK targets get prefixed with the ITK:: namespace. This was unexpected.

I am not sure how adding the ITK:: namespace to all exported and install components would be for compatibility for ITK. I'd expected it to be disruptive and not favored by the community. There may need to be some compatibility flags to disable the namespace or customize the namespace. I am unsure of the expectations and best practices here.

dzenanz · 2026-01-13T16:45:11Z

Maybe the namespace customization effort can be combined with, or otherwise benefit from the work done in Slicer's fork?

mathstuf · 2026-01-13T17:07:14Z

For compat, make IMPORTED INTERFACE targets that forward to the "real" name from the "old" name. These targets can then get DEPRECATION properties so that CMake warns when they're used.

Replace directory-level include_directories() with target-based include properties to enable modern CMake practices and support proper transitive include propagation. Changes: 1. Created ${itk-module}_INCLUDE2_DIRS and ${itk-module}_SYSTEM_INCLUDE2_DIRS - Use generator expressions for BUILD_INTERFACE and INSTALL_INTERFACE paths - Variables produced in each module's CMake configuration file - Enables proper include path handling in build and install trees 2. Modified itk_module_add_library() to apply target properties - Uses target_include_directories() instead of directory-level includes - Uses target_link_directories() for system library directories - Ensures proper PUBLIC include propagation 3. Updated ITKModuleHeaderTest.cmake - Added module include directories to header test targets - Fixes compilation errors for header-only modules 4. Fixed specific module CMakeLists.txt - IO/MINC, IO/TransformMINC: Removed directory-level includes - Nonunit/Review: Updated for target-based includes - ThirdParty modules: Added necessary include_directories where needed Compatibility Notes: - Modules not using itk_module_add_library() may need directory-level include_directories() added explicitly - External modules should update to use itk_module_add_library()

Each ITK CMake interface module includes properties of the module, include the libraries, include directories, and other ITK interface modules that are dependecies. Example usage: target_link_libraries( GradientMagnitudeRecursiveGaussianImageFilter PRIVATE ITK::ITKImageGradientModule ITK::ITKImageIntensityModule ITK::ITKImageIO ) This approach uses target specific requirements and properties to avoid the need for the directory level properies.

Update all examples to use specific ITK CMake interface module targets instead of ${ITK_LIBRARIES}. Examples now link to minimal required modules with PRIVATE visibility and ITKImageIO for I/O. Enhanced WhatModulesITK.py script with --link option to output target_link_libraries commands. Fixed regex to parse module names across multiple lines. AI was use to generate a script to run WhatModules.py and update the CMakeLists.txt, then manual assisted corrections were made.

Add ITK_*_FACTORY_REGISTER_MANAGER compile definitions and factory registration header includes to factory meta-module interface targets. Use itk_generate_factory_registration in Examples to register factories.

Introduce ITK_INTERFACE_LIBRARIES variable to allow users to link to the interface libraries with properties. Add ITK_LIBRARY_NAMESPACE configuration (defaults to 'ITK') that enables namespaced targets for all ITK modules (e.g., ITK::ITKCommonModule). Introduce LIBRARIES_DEPRECATED variable alongside LIBRARIES to maintain backward compatibility. Create INTERFACE IMPORTED wrappers for old target names that link to new namespaced targets with DEPRECATION property set. Update module system to use ${module-targets-namespace} throughout: - itk_module_impl builds both deprecated and namespaced library lists - itk_module_link_dependencies uses namespaced targets - itk_module_test uses namespaced targets - Factory meta-modules use namespaced targets Update external itk_modile_config api to use ITK interface module libraries. Add init_module_vars() macro to set per-module namespace configuration. Add documentation for itk_module_target_export() explaining export mechanism and namespace handling for library targets.

hjmjohnson · 2026-01-16T13:16:54Z

CMake/ITKModuleInfo.cmake.in

 set(@itk-module@_FACTORY_NAMES "@itk-module-FACTORY_NAMES@")
+
+# Create deprecated library interface wrappers
+# TODO


@blowekamp AWESOME WORK!!!

I think that this TODO should be removed. Either we need the deprecated library interface wrappers for backwards compatibility not at all moving forward.

Thanks.

This PR add a namespace (optional) to the libraries. So for example ITKCommon is now ITK::ITKCommon. Do you think we need to go through the effort to create another interface library linking to the namespaces library with a deprecation property?

For example:

add_library(ITKCommon INTERFACE IMPORTED) set_target_properties(ITKCommon PROPERTIES INTERFACE_LINK_LIBRARIES ITK::ITKCommon DEPRECATION "Use ITK::ITKCommon instead")

The users directly specifying the library files without using the ITK configuration would likely not be effected and this depreciate would not help them. Only users who manually specified libraries through CMake , but not using the produce variables might be affected.

manually specified libraries through CMake

Does this hold for remote modules? Will we have to update all the remote modules to keep them working?

If a remote module is using itk_module to specify dependencies on ITK modules, setting {module{_LIBRARIES, and using itk_module_add_library as expected of a module then the namespace and Module interface library should all be created as expected.

There were a couple ITK internal modules that were doing manual creation of libraries that needed to be updated e.g. #5720

blowekamp · 2026-01-16T14:13:46Z

CMake/ITKModuleMacros.cmake

+    set(_libraries "")
+    foreach(dep IN LISTS ${itk-module}_LIBRARIES)
+      # check if dep already has namespace and Module suffix
+      if("${dep}" MATCHES "^(.*)::(.*)$")


@seanm @phcerdan The Eigen3 library was the one library in ITK already with a CMake library namespace. Any thoughts on if that should remain as a separate namespace of if it should take on ITK_LIBRARY_NAMESPACE?

Alas I know next to nothing about cmake.

if(ITK_USE_SYSTEM_EIGEN) set(_eigen_itk_target Eigen3::Eigen) set(_Eigen3_SYSTEM_OR_INTERNAL "Eigen3") else() set(_eigen_itk_target ITKInternalEigen3::Eigen) set(_Eigen3_SYSTEM_OR_INTERNAL "ITKInternalEigen3") endif()

I think we can switch the ITKInternalEigen3 namespace to the new one.
The eigen module exports the variable:

set(${_Eigen3_SYSTEM_OR_INTERNAL}_DIR \"${Eigen3_DIR_INSTALL}\")

i.e "ITKInternalEigen3_DIR" is a variable that should not be modified. Used for example in https://github.com/InsightSoftwareConsortium/ITKTotalVariation/blob/94b85b4890bfad16a9861d76eb25563d034c328a/CMakeLists.txt

But the namespace itself, it should be fine to switch it.

VTK does it by always using VTK::eigen as the target. This is then either the vendored copy or it links to the external package's target.

dzenanz reviewed Jan 7, 2026

View reviewed changes

CMake/ITKModuleMacros.cmake Outdated Show resolved Hide resolved

CMake/ITKModuleMacros.cmake Outdated Show resolved Hide resolved

CMake/ITKModuleEnablement.cmake Outdated Show resolved Hide resolved

hjmjohnson reviewed Jan 8, 2026

View reviewed changes

dzenanz requested a review from thewtex January 8, 2026 15:49

dzenanz approved these changes Jan 8, 2026

View reviewed changes

blowekamp commented Jan 8, 2026

View reviewed changes

CMake/ITKModuleEnablement.cmake Outdated Show resolved Hide resolved

blowekamp commented Jan 8, 2026

View reviewed changes

CMake/ITKModuleMacros.cmake Outdated Show resolved Hide resolved

blowekamp force-pushed the cmake_interface_module branch from f8488a7 to e648c27 Compare January 8, 2026 17:13

github-actions bot removed the area:IO Issues affecting the IO module label Jan 8, 2026

thewtex requested a review from Copilot January 8, 2026 19:26

Copilot started reviewing on behalf of thewtex January 8, 2026 19:26 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

blowekamp force-pushed the cmake_interface_module branch from e648c27 to 4b20ef5 Compare January 8, 2026 20:35

thewtex requested a review from Copilot January 8, 2026 20:59

Copilot started reviewing on behalf of thewtex January 8, 2026 21:00 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

blowekamp force-pushed the cmake_interface_module branch from 4b20ef5 to ea12c51 Compare January 9, 2026 00:10

mathstuf suggested changes Jan 9, 2026

View reviewed changes

blowekamp force-pushed the cmake_interface_module branch from ea12c51 to 5f1281c Compare January 9, 2026 19:41

blowekamp force-pushed the cmake_interface_module branch from 5f1281c to 384da23 Compare January 9, 2026 19:56

mathstuf suggested changes Jan 10, 2026

View reviewed changes

blowekamp force-pushed the cmake_interface_module branch from bc17e0b to 4b56f7a Compare January 13, 2026 16:09

blowekamp closed this Jan 13, 2026

blowekamp reopened this Jan 13, 2026

blowekamp force-pushed the cmake_interface_module branch from 47c0501 to 65f3c4d Compare January 14, 2026 21:23

blowekamp added 7 commits January 15, 2026 15:55

ENH: Remove unneeded check for empty list before sort

0a52abe

ENH: Configure factory meta-modules with registration properties

eb0e2d3

Add ITK_*_FACTORY_REGISTER_MANAGER compile definitions and factory registration header includes to factory meta-module interface targets. Use itk_generate_factory_registration in Examples to register factories.

ENH: Link module libraries to interface modules libraries

ff11ba7

blowekamp force-pushed the cmake_interface_module branch from 65f3c4d to f0f88cb Compare January 15, 2026 20:04

blowekamp marked this pull request as ready for review January 16, 2026 00:44

hjmjohnson reviewed Jan 16, 2026

View reviewed changes

blowekamp commented Jan 16, 2026

View reviewed changes

Uh oh!

Modernize ITK Module System with CMake Interface Libraries #5721

Are you sure you want to change the base?

Modernize ITK Module System with CMake Interface Libraries #5721

Conversation

blowekamp commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Benefits

Compatibility

Uh oh!

dzenanz commented Jan 7, 2026

Uh oh!

dzenanz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hjmjohnson left a comment

Choose a reason for hiding this comment

Uh oh!

dzenanz commented Jan 8, 2026

Uh oh!

Uh oh!

Uh oh!

thewtex commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blowekamp commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blowekamp commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blowekamp commented Jan 9, 2026

Uh oh!

mathstuf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mathstuf commented Jan 9, 2026

Uh oh!

blowekamp commented Jan 9, 2026

Uh oh!

mathstuf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blowekamp commented Jan 7, 2026 •

edited

Loading

blowekamp commented Jan 8, 2026 •

edited

Loading

blowekamp Jan 16, 2026 •

edited

Loading