lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-29 23:01:16 +03:00
Code Activity

📝 overwork documentation

Browse Source
This commit is contained in:
Niels Lohmann
2022-01-09 14:32:38 +01:00
parent 6d8d043add
commit ef556019be
7 changed files with 265 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

174
doc/mkdocs/docs/integration/cmake.md
View File

@ -2,102 +2,124 @@
## Integration
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.
You can use the `nlohmann_json::nlohmann_json` interface target in CMake. This target populates the appropriate usage
requirements for [`INTERFACE_INCLUDE_DIRECTORIES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.html)
to point to the appropriate include directories and [`INTERFACE_COMPILE_FEATURES`](https://cmake.org/cmake/help/latest/prop_tgt/INTERFACE_COMPILE_FEATURES.html)
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:
To use this library from a CMake project, you can locate it directly with [`find_package()`](https://cmake.org/cmake/help/latest/command/find_package.html)
and use the namespaced imported target from the generated package configuration:
```cmake
# CMakeLists.txt
find_package(nlohmann_json 3.2.0 REQUIRED)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```
!!! example
The package configuration file, `nlohmann_jsonConfig.cmake`, can be used either from an install tree or directly out of the build tree.
```cmake title="CMakeLists.txt"
cmake_minimum_required(VERSION 3.1)
project(ExampleProject LANGUAGES CXX)
find_package(nlohmann_json 3.10.5 REQUIRED)
add_executable(example example.cpp)
target_link_libraries(example 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:
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
# If you only include this third party in PRIVATE source files, you do not
# need to install it when your main project gets installed.
# set(JSON_Install OFF CACHE INTERNAL "")
!!! example
# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
# unintended 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)
```
```cmake title="CMakeLists.txt"
cmake_minimum_required(VERSION 3.1)
project(ExampleProject LANGUAGES CXX)
### Embedded (FetchContent)
# If you only include this third party in PRIVATE source files, you do not need to install it
# when your main project gets installed.
set(JSON_Install OFF CACHE INTERNAL "")
add_subdirectory(nlohmann_json)
Since CMake v3.11,
[FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can
be used to automatically download the repository as a dependency at configure type.
add_executable(example example.cpp)
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
```
Example:
```cmake
include(FetchContent)
!!! note
FetchContent_Declare(json
GIT_REPOSITORY https://github.com/nlohmann/json
GIT_TAG v3.7.3)
Do not use `#!cmake include(nlohmann_json/CMakeLists.txt)`, since that carries with it unintended consequences that
will break the build. It is generally discouraged (although not necessarily well documented as such) to use
`#!cmake include(...)` for pulling in other CMake projects anyways.
FetchContent_GetProperties(json)
if(NOT json_POPULATED)
FetchContent_Populate(json)
add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)
```
!!! Note
The repository <https://github.com/nlohmann/json> download size is quite large.
You might want to depend on a smaller repository. For instance, you might want to replace the URL above by
<https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
### 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:
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()
...
```
!!! example
`thirdparty/nlohmann_json` is then a complete copy of this source tree.
```cmake title="CMakeLists.txt"
project(ExampleProject LANGUAGES CXX)
option(EXAMPLE_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
add_subdirectory(thirdparty)
add_executable(example example.cpp)
# Note that the namespaced target will always be available regardless of the import method
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
```
```cmake title="thirdparty/CMakeLists.txt"
if(EXAMPLE_USE_EXTERNAL_JSON)
find_package(nlohmann_json 3.10.5 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.
### FetchContent
Since CMake v3.11, [FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can be used to
automatically download the repository as a dependency at configure type.
!!! example
```cmake title="CMakeLists.txt"
cmake_minimum_required(VERSION 3.11)
project(ExampleProject LANGUAGES CXX)
include(FetchContent)
FetchContent_Declare(json
GIT_REPOSITORY https://github.com/nlohmann/json
GIT_TAG v3.10.5
)
FetchContent_GetProperties(json)
if(NOT json_POPULATED)
FetchContent_Populate(json)
add_subdirectory(${json_SOURCE_DIR} ${json_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
add_executable(example example.cpp)
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
```
!!! Note
The repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on a
smaller repository. For instance, you might want to replace the URL in the example by
<https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
## CMake Options