docs: Add additional CMake documentation
This commit is contained in:
parent
c8231eff75
commit
4c617611e2
1 changed files with 57 additions and 2 deletions
59
README.md
59
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
|
||||
|
||||
|
|
Loading…
Reference in a new issue