Modernize ITK Module System with CMake Interface Libraries by blowekamp · Pull Request #5721 · InsightSoftwareConsortium/ITK

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
)

or

find_package(ITK REQUIRED)
itk_generate_factory_registration()
 target_link_libraries(MyExample
     PRIVATE
       ${ITK_INTERFACE_LIBRARIES}
)

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.

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.

For a Module's Libraries, detect non-target library file with an "EXISTS" check. This will detect full paths, but not library only filenames with library search path usages.

Update the example usage of ITK to remove "UseITK" to use the ITK's module interface libraries with the library properties.

Each time itk_generate_factory_registration, the include directories for the meta factory module is called the include paths are reset to the latest.

blowekamp · 2026-01-31T12:10:56Z

Please approve or review so we can hopefully merge tomorrow.

dzenanz

Still looks good to me.

hjmjohnson

This is a very welcome update!

blowekamp · 2026-02-02T14:50:52Z

Thanks Hans!

dzenanz · 2026-02-03T14:12:20Z

This was the only PR merged yesterday. There are a few new errors and warnings, e.g.

Modules/Bridge/VtkGlue/src/QuickView.cxx:18:10: fatal error: QuickView.h: No such file or directory 18 | #include "QuickView.h" - This causes a cascade of build failures. I guess VTKGlue module needs some attention.
CMake/UseITK.cmake is deprecated - I guess we need to update dashboard scripts to account for new recommendations.
The link interface of target "ITKDCMTKModule" contains: ITK::dcmdata but the target was not found. - I am not sure whether changes need to be made in DCMTK module, or SimpleITK.

blowekamp · 2026-02-03T14:16:49Z

@dzenanz Could you please create a GH issue for these?

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 added 10 commits January 31, 2026 07:07

ENH: Configure factory meta-modules with registration properties

056d0a6

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

01971b7

BUG: Fix detection of loading current module

0aae137

BUG: Modular interface support for third-party library files

2b96aa4

For a Module's Libraries, detect non-target library file with an "EXISTS" check. This will detect full paths, but not library only filenames with library search path usages.

ENH: Update Installation Example to use ITK Interface libraries

377423f

Update the example usage of ITK to remove "UseITK" to use the ITK's module interface libraries with the library properties.

BUG: Fix PhilipsREC module to use standard ITK module macros

bf8090d

ENH: enable multiple call to itk_generate_factory_registration

bf53198

Each time itk_generate_factory_registration, the include directories for the meta factory module is called the include paths are reset to the latest.

DOC: Add migration guide for new CMake Interface Libraries

93df383

ENH: Add deprecation warning to UseITK usage.

14665e6

blowekamp force-pushed the cmake_interface_module branch from 040a7be to 14665e6 Compare January 31, 2026 12:09

blowekamp requested review from hjmjohnson, phcerdan, seanm and thewtex January 31, 2026 12:11

dzenanz approved these changes Jan 31, 2026

View reviewed changes

hjmjohnson approved these changes Feb 1, 2026

View reviewed changes

hjmjohnson merged commit 6ae9cc6 into InsightSoftwareConsortium:main Feb 2, 2026
17 checks passed

blowekamp mentioned this pull request Feb 2, 2026

When building with the bundled HDF5 - its targets are exported #5755

Open

thewtex mentioned this pull request Feb 3, 2026

Python pixi build fails with INTERFACE_INCLUDE_DIRECTORIES error #5756

Closed

Copilot AI mentioned this pull request Feb 3, 2026

ENH: Use BUILD_INTERFACE generator expression for Python includes #5757

Closed

7 tasks

SimonRit mentioned this pull request Feb 3, 2026

Configuration fails with FFTW #5759

Open

SimonRit mentioned this pull request Feb 3, 2026

IO factories in external module fails at configuration #5760

Closed

This was referenced Feb 3, 2026

QuickView.h: No such file or directory #5761

Closed

Update testing scripts to account for CMake code revamp #5762

Open

"ITKDCMTKModule" contains: ITK::dcmdata but the target was not found SimpleITK/SimpleITK#2513

Open

Uh oh!

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!

mathstuf Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

mathstuf commented Jan 9, 2026

Uh oh!

blowekamp commented Jan 31, 2026

Uh oh!

dzenanz left a comment

Choose a reason for hiding this comment

Uh oh!

hjmjohnson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

blowekamp commented Jan 7, 2026 •

edited

Loading

blowekamp commented Jan 8, 2026 •

edited

Loading