FindDCMTK: Add reStructuredText formatting.

This commit is contained in:
Matt McCormick 2016-01-12 15:44:10 -05:00
parent d790f4feea
commit 361c199ff6
1 changed files with 51 additions and 47 deletions

View File

@ -1,32 +1,35 @@
#.rst:
# FindDCMTK
# ---------
# Find DCMTK libraries and applications
#
# - find DCMTK libraries and applications
# The module defines the following variables:
# The module defines the following variables::
#
# 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_DIR can be used to make it simpler to find the various include
# `DCMTK_DIR` can be used to make it simpler to find the various include
# directories and compiled libraries if you've just compiled it in the
# source tree. Just set it to the root of the tree where you extracted
# the source (default to /usr)
# the source (default to `/usr`)
#
#
# This file is able to find version of DCMTK that does or does not export
# a DCMTKConfig.cmake file.
# a *DCMTKConfig.cmake* file.
#
# IMPORTANT: A set of patches has been contributed to DCMTK
# maintainers and merged upstream. As soon as:
# (1) it has been integrated upstream so that it is available in
# .. important::
# A set of patches has been contributed to DCMTK
# maintainers and merged upstream. As soon as:
#
# 1) it has been integrated upstream so that it is available in
# an official release (for example X.Y.Z),
# (2) code bases have been updated to build against X.Y.Z
# This file could be removed.
# 2) code bases have been updated to build against X.Y.Z
#
# The set of patches is listed here: https://github.com/commontk/DCMTK/compare/79030ba...f461865
# This file could be removed.
#
# The set of patches is listed here: https://github.com/commontk/DCMTK/compare/79030ba...f461865
#
#
# Waiting for this to happen, build systems will have to be able
@ -35,24 +38,25 @@
# On any given system, the following combination of DCMTK version could be
# considered:
#
# | 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 |
# ---------------------------------------------------------------------------
# +--------+---------------------+-----------------------+-------------------+
# | | 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 |
# +--------+---------------------+-----------------------+-------------------+
#
# (*) See Troubleshooting section.
#
@ -67,31 +71,31 @@
#
# It is a two step process:
#
# * Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake file. This is done
# with the help of ''
# * Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_* variables details below.
# * Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake file. This is done with the help of `''`
# * Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_* variables details below.
#
# Troubleshooting
# ^^^^^^^^^^^^^^^
#
# What to do if my project finds a different version of DCMTK?
#
# Troubleshooting:
# Remove DCMTK entry from the CMake registry per :command:`find_package`
# documentation.
#
# What to do if my project finds a different version of DCMTK?
# Details
# ^^^^^^^
#
# Remove DCMTK entry from the CMake registry.
# Search for "CMake user package registry" on http://www.cmake.org/cmake/help/v2.8.9/cmake.html#command:find_package
# At some point, the DCMTK build tree was exported [1][2][3]. Indeed, before the set of
# patches discussed above has been contributed to upstream DCMTK, an initial implementation of
# a DCMTK build system exporting its build tree has been implemented and has been tested by some
# folks. This had the effect of populating the CMake registry.
#
# Details: As some point, the DCMTK build tree was exported [1][2][3]. Indeed, before the set of
# patches discussed above has been contributed to upstream DCMTK, an initial implementation of
# a DCMTK build system exporting its build tree has been implemented and has been tested by some
# folks. This had the effect of populating the CMake registry.
#
# Since Step1 does not exclude the CMake registry, when dealing with case E, the incorrect version of
# DCMTK could be found.
#
# [1] http://slicer-devel.65872.n3.nabble.com/Packaging-seems-to-work-again-tp4028121p4028134.html
# [2] https://www.assembla.com/spaces/slicerrt/tickets/244-dcmtk_dir-vs--dcmtkconfig-cmake?comment=267984263#comment:267984263
# [3] http://www.cmake.org/cmake/help/v2.8.11/cmake.html#command:export
# Since Step1 does not exclude the CMake registry, when dealing with case E, the incorrect version of
# DCMTK could be found.
#
# - [1] http://slicer-devel.65872.n3.nabble.com/Packaging-seems-to-work-again-tp4028121p4028134.html
# - [2] https://www.assembla.com/spaces/slicerrt/tickets/244-dcmtk_dir-vs--dcmtkconfig-cmake?comment=267984263#comment:267984263
# - [3] http://www.cmake.org/cmake/help/v2.8.11/cmake.html#command:export
#
#=============================================================================
# Copyright 2004-2009 Kitware, Inc.