Retire the deprecated COMPILE_DEPENDS from the 68 modules that still declare it

[hjmjohnson]

COMPILE_DEPENDS is marked (deprecated) in CMake/ITKModuleMacros.cmake:24, yet 68 modules still declare it. This issue proposes retiring the remaining uses, and asks for agreement on the method before anyone starts.

The immediate prompt is @blowekamp on #6881: "COMPILE_DEPENDS should is poorly defined and should not be used with the modern CMake interface libraries."

What is being asked

1. Is retiring COMPILE_DEPENDS across the remaining 68 modules wanted?
2. If so, is the classification rule below the right one, and should the keyword eventually be removed from itk_module() or left accepting-but-deprecated for external modules?

Why it is poorly defined (verified against current main)

itk_module() folds COMPILE_DEPENDS into two lists:

list(APPEND ITK_MODULE_${itk-module}_DEPENDS
  ${ITK_MODULE_${itk-module}_COMPILE_DEPENDS}
  ${ITK_MODULE_${itk-module}_PRIVATE_DEPENDS})

set(ITK_MODULE_${itk-module}_TRANSITIVE_DEPENDS
  ${ITK_MODULE_${itk-module}_PUBLIC_DEPENDS}
  ${ITK_MODULE_${itk-module}_COMPILE_DEPENDS})

It never reaches _PUBLIC_DEPENDS, _INTERFACE_DEPENDS or _PRIVATE_DEPENDS. The module's own library target links only from those three:

foreach(_link IN ITEMS PUBLIC INTERFACE PRIVATE)
  foreach(dep IN LISTS ITK_MODULE_${itk-module}_${_link}_DEPENDS)
    target_link_libraries(${itk-module} ${_link} ...)

So a COMPILE_DEPENDS entry establishes no link on the module's own target. It reaches consumers only through the ${itk-module}Module INTERFACE target via TRANSITIVE_DEPENDS. That is why it usually appears to work and fails in particular configurations rather than everywhere, which makes it harder to notice than an outright error.

DEPENDS and PRIVATE_DEPENDS map onto PUBLIC and PRIVATE usage requirements and say plainly whether consumers link the dependency. COMPILE_DEPENDS has no such equivalent.

Observed failures

System-library builds. #6097 (@blowekamp, merged 2026-04-21) converted ITKImageIntensity, ITKDenoising and ITKDiffusionTensorImage from COMPILE_DEPENDS to DEPENDS, reporting that with ITK_USE_SYSTEM_EIGEN=ON the Eigen3::Eigen include path was silently dropped and headers such as itkSymmetricEigenAnalysis.h failed to compile.

Wrapping builds. Three recent PRs are the same class of missing-include-path defect in modules that declare COMPILE_DEPENDS, each found by hand rather than by CI:

PR	Module	Symptom
#6880	BoneMorphometry	itkImageIOBase.h not found during castxml
#6881	IOMeshMZ3	itk_zlib.h not found during castxml
#6882	TextureFeatures	missing image-I/O dependency

Proposed classification rule

Decide by what the module's public headers need, not what its sources need:

The dependency appears in	Use
A public header	DEPENDS
Only .cxx sources, or an implementation class kept out of the header	PRIVATE_DEPENDS
Only the module's tests	TEST_DEPENDS

Where a private dependency has leaked into a public header, fix the header rather than promoting the dependency. Promoting to DEPENDS makes every consumer link something it does not use. #6881 is a worked example of both recurring leaks: a nested implementation class defined in the header holding a type from the dependency, and template methods whose in-header bodies call into it while being instantiated only from the module's own source file. Moving both to the .cxx removed the include and let the dependency stay private.

Suggested sequencing:

1. Batch by module group rather than one sweeping change; each module's header surgery can be wrong independently of the others.
2. Verify each module by building it with wrapping enabled, since the wrapping build is what exposes a missing include path.
3. Decide separately whether itk_module() should eventually reject the keyword, or keep accepting it for external modules that still pass it.

The 68 modules

Bridge/VtkGlue                     Filtering/ImageCompare
Core/Common                        Filtering/ImageCompose
Core/FiniteDifference              Filtering/ImageFeature
Core/GPUFiniteDifference           Filtering/ImageFilterBase
Core/ImageAdaptors                 Filtering/ImageFusion
Core/ImageFunction                 Filtering/ImageGradient
Core/QuadEdgeMesh                  Filtering/ImageGrid
Core/SpatialObjects                Filtering/ImageNoise
Core/TestKernel                    Filtering/ImageSources
Core/Transform                     Filtering/ImageStatistics
Filtering/AdaptiveDenoising        Filtering/LabelMap
Filtering/AnisotropicSmoothing     Filtering/MathematicalMorphology
Filtering/AntiAlias                Filtering/MeshToPolyData
Filtering/BiasCorrection           Filtering/Path
Filtering/BinaryMathematicalMorphology  Filtering/PolarTransform
Filtering/BoneEnhancement          Filtering/QuadEdgeMeshFiltering
Filtering/BoneMorphometry          Filtering/Smoothing
Filtering/BSplineGradient          Filtering/SpatialFunction
Filtering/Colormap                 Filtering/Thickness3D
Filtering/CurvatureFlow            Filtering/Thresholding
Filtering/Deconvolution            Filtering/TotalVariation
Filtering/DisplacementField        IO/IOMeshMZ3
Filtering/DistanceMap              IO/MeshBYU
Filtering/FastBilateral            IO/MeshFreeSurfer
Filtering/FastMarching             IO/MeshGifti
Filtering/FFT                      IO/MeshOBJ
Filtering/GPUAnisotropicSmoothing  IO/MeshOFF
Filtering/GPUImageFilterBase       IO/MeshVTK
Filtering/GPUThresholding          IO/SpatialObjects
IO/TransformBase                   Nonunit/Review
IO/TransformFactory                Numerics/Optimizers
IO/TransformMINC                   Numerics/Optimizersv4
Registration/FPFH                  Registration/RANSAC
Segmentation/LevelSets             Segmentation/SuperPixel

Regenerate with:

grep -rl COMPILE_DEPENDS --include=itk-module.cmake Modules/

[dzenanz]

itk_module() should eventually reject the keyword

Eventually, yes. There should be transition period with a warning, where it is mapped to public depends.

[blowekamp]

When refactoring, I left the COMPILE_DEPENDS because it was hard to determine the implications for wrapping and external modules. The current implementation is a little different than what was there before ITK v6's CMake interface libraries. This option seems somewhere between this dependency should be build before this module and this is a dependency for the "interface".

With the direct usage of CMake targets now between modules ( as opposed to the previous scoped files and variables without targets), the "build before" part above is taken care of by the CMake infrastructure.

The remaining point to consider or evaluate for the ITK module interface specification is if the "INTERFACE" option for target_link_libraries ( and ITK Modules ) would be useful per the target_link_libraries: ". Libraries following INTERFACE are appended to the link interface and are not used for linking ." Practically for ITK, if a dependency was only in a header file but not used in the compiled cxx library then it could fall into being an "INTERFACE" dependency.

The FFT Module may be a good one to analyze for these features.