Re-do pull request #451 export CMake targets with PROJ4:: namespace

This version takes to add the include path to the target definition for
cmake 2.8.11 and later.  Also the documentation sticks to the existing
convention of using cmake variables ${PROJ4_LIBRARIES} and
${PROJ4_INCLUDE_DIRS}.  However, the namespace variables are still being
included.

Here's the roll-out plan

(0) Version 4.9.x: The target is proj and PROJ4_LIBRARIES is set to
this.

(1) Version 5.0.x: Two targets, proj and PROJ4::proj, are defined;
PROJ4_LIBRARIES = proj.

(2) In a year or two: Two targets, proj and PROJ4::proj, are defined;
PROJ4_LIBRARIES = PROJ4::proj.

(3) With a change in the library which breaks backwards compatibility:
The target is PROJ4::proj and PROJ4_LIBRARIES = PROJ4::proj.

5 files changed, 40 insertions, 1 deletions

diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index 0fcde0ca..7073b7b4 100644
--- a/cmake/CMakeLists.txt
+++ b/cmake/CMakeLists.txt
@@ -21,3 +21,7 @@ install (FILES
 install (EXPORT targets
   FILE ${PROJECT_NAME_LOWER}-targets.cmake
   DESTINATION "${CMAKECONFIGDIR}")
+install (EXPORT targets
+  NAMESPACE ${PROJECT_NAME}::
+  FILE ${PROJECT_NAME_LOWER}-namespace-targets.cmake
+  DESTINATION "${CMAKECONFIGDIR}")
diff --git a/cmake/project-config.cmake.in b/cmake/project-config.cmake.in
index 9a52b3b5..57445463 100644
--- a/cmake/project-config.cmake.in
+++ b/cmake/project-config.cmake.in
@@ -23,6 +23,7 @@ set (@PROJECT_NAME@_BINARY_DIRS "${_ROOT}/@BINDIR@")
 set (@PROJECT_NAME@_LIBRARIES proj)
 # Read in the exported definition of the library
 include ("${_DIR}/@PROJECT_NAME_LOWER@-targets.cmake")
+include ("${_DIR}/@PROJECT_NAME_LOWER@-namespace-targets.cmake")
 
 unset (_ROOT)
 unset (_DIR)
diff --git a/docs/source/development/cmake.rst b/docs/source/development/cmake.rst
new file mode 100644
index 00000000..1429ae88
--- /dev/null
+++ b/docs/source/development/cmake.rst
@@ -0,0 +1,30 @@
+.. _cmake:
+
+********************************************************************************
+Using Proj.4 in CMake projects
+********************************************************************************
+
+The recommended way to use the Proj.4 library in a CMake project is to
+link to the imported library target ``${PROJ4_LIBRARIES}`` provided by
+the CMake configuration which comes with the library. Typical usage is:
+
+.. code::
+
+    find_package(PROJ4)
+
+    target_link_libraries(MyApp ${PROJ4_LIBRARIES})
+
+By adding the imported library target ``${PROJ4_LIBRARIES}`` to the
+target link libraries, CMake will also pass the include directories to
+the compiler.  This requires that you use CMake version 2.8.11 or later.
+If you are using an older version of CMake, then add
+
+.. code::
+
+    include_directories(${PROJ4_INCLUDE_DIRS})
+
+The CMake command ``find_package`` will look for the configuration in a
+number of places. The lookup can be adjusted for all packages by setting
+the cache variable or environment variable ``CMAKE_PREFIX_PATH``. In
+particular, CMake will consult (and set) the cache variable
+``PROJ4_DIR``.
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
index 2e6e5622..712bbdfe 100644
--- a/docs/source/development/index.rst
+++ b/docs/source/development/index.rst
@@ -14,4 +14,4 @@ proj.4 project or using the library in their own software.
    api
    threads
    bindings
-
+   cmake
diff --git a/src/lib_proj.cmake b/src/lib_proj.cmake
index f1337a54..c9e4d9e6 100644
--- a/src/lib_proj.cmake
+++ b/src/lib_proj.cmake
@@ -284,6 +284,10 @@ add_library( ${PROJ_CORE_TARGET}
                     ${ALL_LIBPROJ_HEADERS}
                     ${PROJ_RESOURCES}  )
 
+if (NOT CMAKE_VERSION VERSION_LESS 2.8.11)
+  target_include_directories (${PROJ_CORE_TARGET} INTERFACE
+    $<INSTALL_INTERFACE:${INCLUDEDIR}>)
+endif ()
 
 if(WIN32)
   set_target_properties(${PROJ_CORE_TARGET}