Ensure CTK_INSTALL_QTPLUGIN_DIR is properly set

When configuring the inner project, the variable was
passed without making sure it was defined or set to a
non empty value.

This commit ensure that the variable is passed only
if it's set to a non empty value. That way the
macro ctkMacroBuildQtPlugin will properly default
to "CTK_INSTALL_LIB_DIR"

See issue #65
Ensure "CMAKE_INSTALL_PREFIX" is properly passed to inner project.

The value of "ep_install_dir" is reserved for regular
external project. The user should still be able to set
CMAKE_INSTALL_PREFIX when configuring CTK and have it
installed when he expects.

See issue #65
By default, do not install application headers

See issue #65
Install CTK's *.cmake files

See issue #65
Merge branch '65-packaging-support' into 403-relocatable-ctkconfig-usectk

* 65-packaging-support:
  Install CTK's *.cmake files
  By default, do not install application headers
  Ensure "CMAKE_INSTALL_PREFIX" is properly passed to inner project.
  Ensure CTK_INSTALL_QTPLUGIN_DIR is properly set
Set plugin install rules for target and include files

Location of both  plugin libraries and headers can be changed by
configuring CTK with CTK_INSTALL_PLUGIN_DIR and CTK_INSTALL_PLUGIN_INCLUDE_DIR.

Plugin headers will always be installed into:

    CTK_INSTALL_PLUGIN_INCLUDE_DIR/<Plugin-SymbolicName>

where <Plugin-SymbolicName> is of the form "org.commontk.foo".

See #65 and #158
Remove commented code and unused vars from CTKConfig / CTKGenerateCTKConfig

See #403
Explicitly set default value for CTK_INSTALL_QTPLUGIN_DIR

See #403
Remove explicit setting of CMake policies.

According to the documentation, calling "cmake_minimum_required(VERSION X.Y.Z)
is sufficient to have all policies implemented for version of CMake <= X.Y.Z
set to NEW.

See http://www.cmake.org/cmake/help/v2.8.4/cmake.html#command:cmake_minimum_required

See #403
Improve FindDCMTK.cmake documentation

Also added a troubleshooting section addressing issue #382
Add DCMTK 3.6.0 support to ctkDICOMUtil.cpp

This commit implements a try_compile checking if DCMTK provides
'dcmtk::log4cplus::Logger', if not fallback to 'log4cplus::Logger'.

Indeed, following DCMTK-3.6.1_20110519 (commit e39d190), log4cplus has
been moved into dcmtk::log4cplus namespace.

See #405
Ensure DCMTK libraries can be found on system without setting DCMTK_DIR

See inlined comment for more details.

See #382
FindDCMTK - Workaround bug in packaging of DCMTK 3.6.0 on Debian.

See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=637687

See inlined comment for more details.

See #382
Add support for install-able and relocatable package.

Since CMake 2.8.8, there is convenient module named "CMakePackageConfigHelpers"
that provided the helper macros "configure_package_config_file" and
"write_basic_package_version_file" allowing to easily configure
relocatable packages.
See http://www.cmake.org/cmake/help/v2.8.8/cmake.html#module:CMakePackageConfigHelpers

Considering that we still would like to support the CMake version 2.8.7
being provided into the Ubuntu 12.04 LTS, simply bumping up the minimum
CMake required version wouldn't work. Instead, the CMake
module CMakePackageConfigHelpers (corresponding to CMake kitware/CMake@f051814) has been
copied into CTK source tree and is included only if it is not already
provided by the CMake version being used to configure CTK. At configure
time status message will allow to understand which version of the module
is included. For example:

-- Including CMake built-in module CMakePackageConfigHelpers
-- Including CMake built-in module CMakePackageConfigHelpers - failed
-- Including CTK module CMakePackageConfigHelpers
-- Including CTK module CMakePackageConfigHelpers - ok


The CTKConfigVersion file is automatically generated with the
help of "write_basic_package_version_file" and is identical for both the
build and the install tree.


From CTKConfig availables in either the built or installed tree, remove
the following variables:
  CTK_EXECUTABLE_DIRS
  CTK_RUNTIME_LIBRARY_DIRS
  CTK_QT_RCC_EXECUTABLE
  CTK_QT_MOC_EXECUTABLE
  CTK_QT_UIC_EXECUTABLE
  CTK_MAJOR_VERSION
  CTK_MINOR_VERSION
  CTK_PATCH_VERSION

The following variables will now be specific to only the CTKConfig file
available in the *build* tree:
  CTK_QTDESIGNERPLUGINS_DIR
  CTK_DGRAPH_EXECUTABLE
  CTK_QT_QMAKE_EXECUTABLE
  CTK_EXTERNAL_LIBRARIES
  CTK_EXTERNAL_LIBRARY_DIRS

Add install rules for:
  UseCTK.cmake
  ctkConfig.h
  CTKPluginUseFile.cmake
  CTK targets
  CTKConfig.cmake
  CTKConfigVersion.cmake

Note that there are still issues with file "CTKPluginUseFile.cmake"
not being usable from an install tree, these ones will be addressed
later. See #406

See #403
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
Merge branch '403-relocatable-ctkconfig-usectk'

* 403-relocatable-ctkconfig-usectk:
  Add support for install-able and relocatable package.
  Remove explicit setting of CMake policies.
  Explicitly set default value for CTK_INSTALL_QTPLUGIN_DIR
  Remove commented code and unused vars from CTKConfig / CTKGenerateCTKConfig
  Set plugin install rules for target and include files
  Install CTK's *.cmake files
  By default, do not install application headers
  Ensure "CMAKE_INSTALL_PREFIX" is properly passed to inner project.
  Ensure CTK_INSTALL_QTPLUGIN_DIR is properly set
Merge branch '405-support-dcmtk-360'

* 405-support-dcmtk-360:
  Add DCMTK 3.6.0 support to ctkDICOMUtil.cpp
Fix -Wunused-but-set-variable in transfer function tests

Since the tests only exercise the method to make sure there is no
crash, adding "Q_UNUSED" is good enough.

Fixes #209
Merge branch '209-fix-vtk-transfer-function-test-warnings'

* 209-fix-vtk-transfer-function-test-warnings:
  Fix -Wunused-but-set-variable in transfer function tests
Fix linking of VTKCoreCppTest by adding a check for linker capabilities

This commit is based on the work of Sankhesh Jhaveri and Bill Hoffman. It
has been adapted to (1) be re-usable by project depending on CTK and
(2) execute the try_compile test only if needed.

It checks whether the linker will be able to resolve all symbols. If the
check fails, another test takes place to make sure the linker is not
lazy-linking. If it is, the flag --no-as-needed is added to
CMAKE_EXE_LINKER_FLAGS.

The link error was:

// ---------------
Linking CXX executable ../../../../../../bin/CTKVisualizationVTKCoreCppTests
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyNumber_Divmod'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyDict_SetItem'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyExc_ValueError'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyNumber_And'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyDict_SetItemString'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyNumber_Absolute'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyExc_OverflowError'
/home/jchris/Projects/Slicer-1-SuperBuild-Release-Qt485/VTK-build/bin/libvtkPythonCore.so.5.10.1: undefined reference to `PyType_IsSubtype'
[...]
// ---------------

While working on Slicer bug #2321, Sankhesh and Bill figured out the
solution:

"Okay, finally with some awesome help from Bill Hoffman we could figure
out what was the root cause of this problem.

Turns out, the shared library libvtkPythonCore.so uses python symbols
but is not linked to libpython.so [1].
Moreover, the test in question - qSlicerDataModuleWidgetsCxxTest does not
reference any python symbols directly. This makes the linker "not link"
the executable to libpython. However, since libvtkPythonCore depends on
libpython without a direct link between the two, we have to suffer with
this bug. :-(

In essence, if there is a shared library "A" that depends on a shared
library "B" but is not linked directly to it and an executable "C"
depends only on shared library "A", linker fails to link to library "B"
and cannot resolve symbols in "A".

Now, you would expect the linker to resolve the dependency up the
toolchain and link the two shared libraries together. This would have
made it much easier. But, Ubuntu package maintainers decided to add a
linker flag "--as-needed" [2] to the default gcc toolchain starting
Ubuntu 12.04.
There is some discussion on this [3].

[1] https://github.com/Kitware/VTK/blob/v5.10.0/Wrapping/Python/CMakeLists.txt#L50
[2] http://linux.die.net/man/1/ld
[3] http://stackoverflow.com/questions/12693624/references-to-fftw-not-resolved-when-linking-with-as-needed
"
Source: http://na-mic.org/Mantis/view.php?id=2321#c6403

Co-authored-by: Sankhesh Jhaveri <sankhesh.jhaveri@kitware.com>
Co-authored-by: Bill Hoffman <bill.hoffman@kitware.com>