From 0199b3fd17fca361bba4eec93209c0b74c0f7340 Mon Sep 17 00:00:00 2001
From: Charles Karney <charles@karney.com>
Date: Sat, 10 Feb 2018 17:17:27 -0500
Subject: 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.
---
 docs/source/development/cmake.rst | 30 ++++++++++++++++++++++++++++++
 docs/source/development/index.rst |  2 +-
 2 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/development/cmake.rst

(limited to 'docs/source/development')

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
-- 
cgit v1.2.3