mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-02 20:00:38 -06:00
FindDCMTK: Update documentation
- Synced module documentation with other similar find modules. - Moved "compatibility" section into a refactored note at the top, when the config mode was implemented in this module. - Added examples section.
This commit is contained in:
Peter Kokot
@@ -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)
|
||||
#]=======================================================================]
|
||||
|
||||
#
|
||||
|
||||
Reference in New Issue
Block a user