Merge branch '382-fix-find-dcmtk-issue'

* 382-fix-find-dcmtk-issue:
  FindDCMTK - Workaround bug in packaging of DCMTK 3.6.0 on Debian.
  Ensure DCMTK libraries can be found on system without setting DCMTK_DIR
  Improve FindDCMTK.cmake documentation

Utilities/CMake/FindDCMTK.cmake

@@ -1,9 +1,7 @@
-# adapted version of FindDCMTK, better suited for super-builds
-
 # - find DCMTK libraries and applications
+# The module defines the following variables:
 #
-
-#  DCMTK_INCLUDE_DIRS   - Directories to include to use DCMTK
+#  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
@@ -11,8 +9,91 @@
 # 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/include/dcmtk/)
-
+# the source (default to /usr)
+#
+#
+# This file is able to find version of DCMTK that do or do not export
+# a DCMTKConfig.cmake file.
+#
+# IMPORTANT: A set of patches has been contributed to DCMTK
+# maintainers, 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.
+#
+# 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
+# to support different versions of DCMTK.
+#
+# 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       |
+# ---------------------------------------------------------------------------
+#
+#  (*) See Troubleshooting section.
+#
+# Legend:
+#
+#   NA ...............: Means that no System or Local DCMTK is available
+#
+#   [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export a DCMTKConfig.cmake file.
+#
+#   [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTKConfig.cmake file.
+#
+#
+#
+# In CTK commits 52d953 and 74b4b07, the FindDCMTK.cmake module has been updated to be able
+# to find both version of DCMTK ([ ] DCMTKConfig and [X] DCMTKConfig).
+#
+# It is a two steps 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.
+#
+#
+#
+# Troubleshooting:
+#
+#    What to do if my project find a different version of DCMTK ?
+#
+#    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
+#
+#    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
+#
+#
 #=============================================================================
 # Copyright 2004-2009 Kitware, Inc.
 # Copyright 2009-2010 Mathieu Malaterre <mathieu.malaterre@gmail.com>
@@ -34,10 +115,22 @@
 # Modified for EasyViz by Thomas Sondergaard.
 #
 
+set(_dcmtk_dir_description "The directory of DCMTK build or install tree.")
+
+# Ensure that DCMTK_DIR is set to a reasonable default value
+# so that DCMTK libraries can be found on a standard Unix distribution.
+# It also overwrite the value of DCMTK_DIR after this one has been
+# set by a successful discovery of DCMTK by the unpatched FindDCMTK.cmake module
+# distributed with CMake (as of 0167cea)
+if(NOT DCMTK_DIR OR DCMTK_DIR STREQUAL "/usr/include/dcmtk")
+  set(DCMTK_DIR "/usr" CACHE PATH ${_dcmtk_dir_description} FORCE)
+endif()
+
 set(_SAVED_DCMTK_DIR ${DCMTK_DIR})
 
 #
-# First, try to use NO_MODULE
+# Step1: Attempt to find a version of DCMTK providing a DCMTKConfig.cmake file.
+#
 message(STATUS "Trying to find DCMTK expecting DCMTKConfig.cmake")
 find_package(DCMTK QUIET NO_MODULE)
 if(DCMTK_FOUND
@@ -52,7 +145,12 @@ endif()
 message(STATUS "Trying to find DCMTK relying on FindDCMTK.cmake")
 
 # Restore the value reset by the previous call to 'find_package(DCMTK QUIET NO_MODULE)'
-set(DCMTK_DIR ${_SAVED_DCMTK_DIR} CACHE PATH "The directory containing a CMake configuration file for DCMTK." FORCE) 
+set(DCMTK_DIR ${_SAVED_DCMTK_DIR} CACHE PATH ${_dcmtk_dir_description} FORCE)
+
+
+#
+# Step2: Attempt to find a version of DCMTK that does NOT provide a DCMTKConfig.cmake file.
+#
 
 # prefer DCMTK_DIR over default system paths like /usr/lib
 if(DCMTK_DIR)
@@ -229,5 +327,28 @@ find_package_handle_standard_args(DCMTK
   REQUIRED_VARS ${DCMTK_INCLUDE_DIR_NAMES} DCMTK_LIBRARIES
   FAIL_MESSAGE "Please set DCMTK_DIR and re-run configure")
 
+# Workaround bug in packaging of DCMTK 3.6.0 on Debian.
+# See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=637687
+#
+# By setting 'DCMTK_FIND_PACKAGE_SKIP_ADD_DEFINITIONS' to '1' before
+# calling 'find_package(DCMTK)', the variable 'DCMTK_DEFINITIONS' will be set
+# appropriately.
+if(DCMTK_FOUND AND UNIX AND NOT APPLE)
+  include(CheckCXXSourceCompiles)
+  set(CMAKE_REQUIRED_FLAGS )
+  set(CMAKE_REQUIRED_DEFINITIONS )
+  set(CMAKE_REQUIRED_INCLUDES ${DCMTK_INCLUDE_DIRS})
+  set(CMAKE_REQUIRED_LIBRARIES ${DCMTK_LIBRARIES})
+  check_cxx_source_compiles("#include <dcmtk/config/osconfig.h>\n#include <dcmtk/ofstd/ofstream.h>\nint main(int,char*[]){return 0;}"
+    DCMTK_HAVE_CONFIG_H_OPTIONAL
+    )
+  if(NOT DCMTK_HAVE_CONFIG_H_OPTIONAL)
+    set(DCMTK_DEFINITIONS "-DHAVE_CONFIG_H")
+  endif()
+  if(NOT DCMTK_HAVE_CONFIG_H_OPTIONAL AND NOT DCMTK_FIND_PACKAGE_SKIP_ADD_DEFINITIONS)
+    add_definitions(${DCMTK_DEFINITIONS})
+  endif()
+endif()
+
 message(STATUS "Trying to find DCMTK relying on FindDCMTK.cmake - ok")