message: docs: Add additional CMake documentation
diff: - [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
  