From 4c617611e2bdf8614be9a0f7a96dd45cbbddb56e Mon Sep 17 00:00:00 2001
From: Chuck Atkins <chuck.atkins@kitware.com>
Date: Mon, 1 Oct 2018 14:09:31 -0400
Subject: [PATCH] docs: Add additional CMake documentation

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 57 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 013db618..83a6b562 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,8 @@
 
 - [Design goals](#design-goals)
 - [Integration](#integration)
+  - [CMake](#cmake)
+  - [Package Managers](#package-managers)
 - [Examples](#examples)
   - [JSON as first-class data type](#json-as-first-class-data-type)
   - [Serialization / Deserialization](#serialization--deserialization)
@@ -69,10 +71,16 @@ to the files you want to process JSON and set the necessary switches to enable C
 
 You can further use file [`include/nlohmann/json_fwd.hpp`](https://github.com/nlohmann/json/blob/develop/include/nlohmann/json_fwd.hpp) for forward-declarations. The installation of json_fwd.hpp (as part of cmake's install step), can be achieved by setting `-DJSON_MultipleHeaders=ON`.
 
-If this library was built with CMake then you can consume it from another CMake project by using the namespaced imported target from the generated package configuration:
+### CMake
+
+You can also use the `nlohmann_json::nlohmann_json` interface target in CMake.  This target populates the appropriate usage requirements for `INTERFACE_INCLUDE_DIRECTORIES` to point to the appropriate include directories and `INTERFACE_COMPILE_FEATURES` for the necessary C++11 flags.
+
+#### External
+
+To use this library from a CMake project, you can locate it directly with `find_package()` and use the namespaced imported target from the generated package configuration:
 ```cmake
 # CMakeLists.txt
-find_package(nlohmann_json REQUIRED)
+find_package(nlohmann_json 3.2.0 REQUIRED)
 ...
 add_library(foo ...)
 ...
@@ -80,6 +88,53 @@ target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
 ```
 The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of the build tree.
 
+#### Embedded
+
+To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call `add_subdirectory()` in your `CMakeLists.txt` file:
+```cmake
+# Typically you don't care so much for a third party library's tests to be
+# run from your own project's code.
+set(JSON_BuildTests OFF CACHE INTERNAL "")
+
+# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
+# inintended consequences that will break the build.  It's generally
+# discouraged (although not necessarily well documented as such) to use
+# include(...) for pulling in other CMake projects anyways.
+add_subdirectory(nlohmann_json)
+...
+add_library(foo ...)
+...
+target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
+```
+
+#### Supporting Both
+To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:
+``` cmake
+# Top level CMakeLists.txt
+project(FOO)
+...
+option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
+...
+add_subdirectory(thirdparty)
+...
+add_library(foo ...)
+...
+# Note that the namespaced target will always be available regardless of the
+# import method
+target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
+```
+```cmake
+# thirdparty/CMakeLists.txt
+...
+if(FOO_USE_EXTERNAL_JSON)
+  find_package(nlohmann_json 3.2.0 REQUIRED)
+else()
+  set(JSON_BuildTests OFF CACHE INTERNAL "")
+  add_subdirectory(nlohmann_json)
+endif()
+...
+```
+`thirdparty/nlohmann_json` is then a complete copy of this source tree.
 
 ### Package Managers