mirror of
https://github.com/Kitware/CMake.git
synced 2026-05-04 21:30:01 -05: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
+112
-49
@@ -14,77 +14,140 @@ Finds the DICOM ToolKit (DCMTK) libraries and applications:
|
|||||||
DCMTK is a set of libraries and applications implementing large parts of
|
DCMTK is a set of libraries and applications implementing large parts of
|
||||||
the DICOM Standard (Digital Imaging and Communications in Medicine).
|
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 since its version `3.6.1_20140617
|
||||||
DCMTK_LIBRARIES - Files to link against to use DCMTK
|
<https://git.dcmtk.org/?p=dcmtk.git;a=commit;h=662ae187c493c6b9a73dd5e3875372cebd0c11fe>`_
|
||||||
DCMTK_FOUND - If false, don't try to use DCMTK
|
supports and installs :ref:`package configuration file
|
||||||
DCMTK_DIR - (optional) Source directory for DCMTK
|
<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
|
* Step 1: Attempts to find DCMTK version providing a ``DCMTKConfig.cmake``
|
||||||
a ``DCMTKConfig.cmake`` file. It applies a two step process:
|
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.
|
Until all clients update to the more recent DCMTK, build systems will need
|
||||||
* Step 2: If step 1 failed, rely on ``FindDCMTK.cmake`` to set ``DCMTK_*``
|
to support different versions of DCMTK.
|
||||||
variables details below.
|
|
||||||
|
|
||||||
|
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>`_
|
Case System DCMTK Local DCMTK Supported?
|
||||||
provides a ``DCMTKConfig.cmake`` :manual:`package configuration file
|
===== ================== =================== ============
|
||||||
<cmake-packages(7)>`. To exclusively use the package configuration file
|
A N/A [ ] DCMTKConfig YES
|
||||||
(recommended when possible), pass the `NO_MODULE` option to
|
B N/A [X] DCMTKConfig YES
|
||||||
:command:`find_package`. For example, `find_package(DCMTK NO_MODULE)`.
|
C [ ] DCMTKConfig N/A YES
|
||||||
This requires official DCMTK snapshot *3.6.1_20140617* or newer.
|
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
|
N/A
|
||||||
considered:
|
DCMTK is not available.
|
||||||
|
|
||||||
+--------+---------------------+-----------------------+-------------------+
|
[ ] DCMTKConfig
|
||||||
| | SYSTEM DCMTK | LOCAL DCMTK | Supported ? |
|
DCMTK does NOT export a ``DCMTKConfig.cmake`` file.
|
||||||
+--------+---------------------+-----------------------+-------------------+
|
|
||||||
| 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 |
|
|
||||||
+--------+---------------------+-----------------------+-------------------+
|
|
||||||
|
|
||||||
(*) 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
|
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`
|
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