diff --git a/Modules/FindDCMTK.cmake b/Modules/FindDCMTK.cmake index 17515d161c..710fac83b7 100644 --- a/Modules/FindDCMTK.cmake +++ b/Modules/FindDCMTK.cmake @@ -14,77 +14,140 @@ Finds the DICOM ToolKit (DCMTK) libraries and applications: DCMTK is a set of libraries and applications implementing large parts of the DICOM Standard (Digital Imaging and Communications in Medicine). -The module defines the following variables:: +.. versionadded:: 3.5 + This module is now able to find a version of DCMTK that does or does not + export a ``DCMTKConfig.cmake`` file. - DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK - DCMTK_LIBRARIES - Files to link against to use DCMTK - DCMTK_FOUND - If false, don't try to use DCMTK - DCMTK_DIR - (optional) Source directory for DCMTK + DCMTK since its version `3.6.1_20140617 + `_ + supports and installs :ref:`package configuration file + ` (``DCMTKConfig.cmake``) for use with the + :command:`find_package` command in *config mode*. -Compatibility -^^^^^^^^^^^^^ + This module now applies a two-step process: -This module is able to find a version of DCMTK that does or does not export -a ``DCMTKConfig.cmake`` file. It applies a two step process: + * Step 1: Attempts to find DCMTK version providing a ``DCMTKConfig.cmake`` + file and, if found, returns the results without further action. + * Step 2: If step 1 failed, this module falls back to *module mode* + (it searches standard locations) and sets the ``DCMTK_*`` result + variables. -* Step 1: Attempt to find DCMTK version providing a ``DCMTKConfig.cmake`` file. -* Step 2: If step 1 failed, rely on ``FindDCMTK.cmake`` to set ``DCMTK_*`` - variables details below. + Until all clients update to the more recent DCMTK, build systems will need + to support different versions of DCMTK. + On any given system, the following combinations of DCMTK versions could + be considered for the DCMTK installed on the system (for example, via a + system package manager), or locally (for example, a custom installation, + or through the :module:`FetchContent` module): -`Recent DCMTK -`_ -provides a ``DCMTKConfig.cmake`` :manual:`package configuration file -`. To exclusively use the package configuration file -(recommended when possible), pass the `NO_MODULE` option to -:command:`find_package`. For example, `find_package(DCMTK NO_MODULE)`. -This requires official DCMTK snapshot *3.6.1_20140617* or newer. + ===== ================== =================== ============ + Case System DCMTK Local DCMTK Supported? + ===== ================== =================== ============ + A N/A [ ] DCMTKConfig YES + B N/A [X] DCMTKConfig YES + C [ ] DCMTKConfig N/A YES + D [X] DCMTKConfig N/A YES + E [ ] DCMTKConfig [ ] DCMTKConfig YES (*) + F [X] DCMTKConfig [ ] DCMTKConfig NO + G [ ] DCMTKConfig [X] DCMTKConfig YES + H [X] DCMTKConfig [X] DCMTKConfig YES + ===== ================== =================== ============ + Legend: -Until all clients update to the more recent DCMTK, build systems will need -to support different versions of DCMTK. + (*) + See the `Troubleshooting`_ section. -On any given system, the following combinations of DCMTK versions could be -considered: + N/A + DCMTK is not available. -+--------+---------------------+-----------------------+-------------------+ -| | SYSTEM DCMTK | LOCAL DCMTK | Supported ? | -+--------+---------------------+-----------------------+-------------------+ -| Case A | NA | [ ] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case B | NA | [X] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case C | [ ] DCMTKConfig | NA | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case D | [X] DCMTKConfig | NA | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case E | [ ] DCMTKConfig | [ ] DCMTKConfig | YES (*) | -+--------+---------------------+-----------------------+-------------------+ -| Case F | [X] DCMTKConfig | [ ] DCMTKConfig | NO | -+--------+---------------------+-----------------------+-------------------+ -| Case G | [ ] DCMTKConfig | [X] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ -| Case H | [X] DCMTKConfig | [X] DCMTKConfig | YES | -+--------+---------------------+-----------------------+-------------------+ + [ ] DCMTKConfig + DCMTK does NOT export a ``DCMTKConfig.cmake`` file. - (*) See Troubleshooting section. + [X] DCMTKConfig + DCMTK exports a ``DCMTKConfig.cmake`` file. -Legend: +Result Variables +^^^^^^^^^^^^^^^^ - NA ...............: Means that no System or Local DCMTK is available +This module defines the following variables: - [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export a DCMTKConfig.cmake file. +``DCMTK_FOUND`` + Boolean indicating whether DCMTK is found. - [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTKConfig.cmake file. +``DCMTK_INCLUDE_DIRS`` + Include directories containing headers needed to use DCMTK. +``DCMTK_LIBRARIES`` + Libraries needed to link against to use DCMTK. + +Hints +^^^^^ + +This module accepts the following variables: + +``DCMTK_DIR`` + (optional) Source directory for DCMTK. Troubleshooting ^^^^^^^^^^^^^^^ -What to do if my project finds a different version of DCMTK? +.. rubric:: What to do if project finds a different version of DCMTK? Remove DCMTK entry from the CMake cache per :command:`find_package` -documentation. +documentation, and re-run configuration. To find DCMTK on custom location +use variables such as :variable:`CMAKE_PREFIX_PATH`, or ``DCMTK_DIR``. + +Examples +^^^^^^^^ + +Example: Finding DCMTK +"""""""""""""""""""""" + +Finding DCMTK with this module: + +.. code-block:: cmake + + find_package(DCMTK) + +Example: Finding DCMTK Without This Module +"""""""""""""""""""""""""""""""""""""""""" + +To explicitly use the ``DCMTKConfig.cmake`` package configuration file +(recommended when possible) and find DCMTK in *config mode* without using +this module, the ``NO_MODULE`` option can be given to +:command:`find_package`: + +.. code-block:: cmake + + find_package(DCMTK NO_MODULE) + +Example: Creating Imported Target +""""""""""""""""""""""""""""""""" + +In the following example, DCMTK is searched with this module and +an :ref:`imported target ` is conditionally created to +provide DCMTK usage requirements which can be easily linked to project +targets. For example, if DCMTK is found in *config mode*, the +``DCMTK::DCMTK`` imported target will be available through the found config +files instead: + +.. code-block:: cmake + + find_package(DCMTK) + + # Upstream DCMTKConfig.cmake already provides DCMTK::DCMTK imported target + if(DCMTK_FOUND AND NOT TARGET DCMTK::DCMTK) + add_library(DCMTK::DCMTK INTERFACE IMPORTED) + set_target_properties( + DCMTK:DCMTK + PROPERTIES + INTERFACE_LINK_LIBRARIES "${DCMTK_LIBRARIES}" + INTERFACE_INCLUDE_DIRECTORIES "${DCMTK_INCLUDE_DIRS}" + ) + endif() + + target_link_libraries(example PRIVATE DCMTK::DCMTK) #]=======================================================================] #