Merge topic 'patch-FindDCMTK'

7578837ce7 FindDCMTK: Update documentation

Acked-by: Kitware Robot <[email protected]>
Merge-request: !11102

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
+  <https://git.dcmtk.org/?p=dcmtk.git;a=commit;h=662ae187c493c6b9a73dd5e3875372cebd0c11fe>`_
+  supports and installs :ref:`package configuration file
+  <Config File Packages>` (``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
-<https://git.dcmtk.org/?p=dcmtk.git;a=commit;h=662ae187c493c6b9a73dd5e3875372cebd0c11fe>`_
-provides a ``DCMTKConfig.cmake`` :manual:`package configuration file
-<cmake-packages(7)>`. 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 <Imported Targets>` 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)
 #]=======================================================================]
 
 #