mirror of
https://github.com/nlohmann/json.git
synced 2026-10-07 06:57:14 +00:00
223 lines
11 KiB
Markdown
223 lines
11 KiB
Markdown
# CMake
|
|
|
|
## Integration
|
|
|
|
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. Most [package managers](https://json.nlohmann.me/integration/package_managers/index.md) that provide a CMake package configuration for this library expose this same target.
|
|
|
|
### External
|
|
|
|
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:
|
|
|
|
Example
|
|
|
|
CMakeLists.txt
|
|
|
|
```
|
|
cmake_minimum_required(VERSION 3.5)
|
|
project(ExampleProject LANGUAGES CXX)
|
|
|
|
find_package(nlohmann_json 3.12.0 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.
|
|
|
|
Example
|
|
|
|
CMakeLists.txt
|
|
|
|
```
|
|
cmake_minimum_required(VERSION 3.5)
|
|
project(ExampleProject LANGUAGES CXX)
|
|
|
|
# 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)
|
|
|
|
add_executable(example example.cpp)
|
|
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
|
|
```
|
|
|
|
Note
|
|
|
|
Do not use `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 `include(...)` for pulling in other CMake projects anyways.
|
|
|
|
### 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.
|
|
|
|
Example
|
|
|
|
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)
|
|
```
|
|
|
|
thirdparty/CMakeLists.txt
|
|
|
|
```
|
|
if(EXAMPLE_USE_EXTERNAL_JSON)
|
|
find_package(nlohmann_json 3.12.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.
|
|
|
|
### FetchContent
|
|
|
|
Since CMake v3.11, [FetchContent](https://cmake.org/cmake/help/v3.11/module/FetchContent.html) can be used to automatically download a release as a dependency at configure time.
|
|
|
|
Example
|
|
|
|
CMakeLists.txt
|
|
|
|
```
|
|
cmake_minimum_required(VERSION 3.11)
|
|
project(ExampleProject LANGUAGES CXX)
|
|
|
|
include(FetchContent)
|
|
|
|
FetchContent_Declare(json URL https://github.com/nlohmann/json/releases/download/v3.12.0/json.tar.xz)
|
|
FetchContent_MakeAvailable(json)
|
|
|
|
add_executable(example example.cpp)
|
|
target_link_libraries(example PRIVATE nlohmann_json::nlohmann_json)
|
|
```
|
|
|
|
Note
|
|
|
|
It is recommended to use the URL approach described above which is supported as of version 3.10.0. It is also possible to pass the Git repository like
|
|
|
|
```
|
|
FetchContent_Declare(json
|
|
GIT_REPOSITORY https://github.com/nlohmann/json
|
|
GIT_TAG v3.12.0
|
|
)
|
|
```
|
|
|
|
However, the repository <https://github.com/nlohmann/json> download size is quite large.
|
|
|
|
## CMake Options
|
|
|
|
### `JSON_BuildTests`
|
|
|
|
Build the unit tests when [`BUILD_TESTING`](https://cmake.org/cmake/help/latest/command/enable_testing.html) is enabled. This option is `ON` by default if the library's CMake project is the top project and the `tests` directory exists (the release archive `json.tar.xz` does not contain it). That is, when integrating the library as described above, the test suite is not built unless explicitly switched on with this option.
|
|
|
|
### `JSON_CI`
|
|
|
|
Enable CI build targets. The exact targets are used during the several CI steps and are subject to change without notice. This option is `OFF` by default.
|
|
|
|
### `JSON_DeleteDeprecatedFunctions`
|
|
|
|
Delete the deprecated functions instead of only deprecating them by defining the macro [`JSON_DELETE_DEPRECATED_FUNCTIONS`](https://json.nlohmann.me/api/macros/json_delete_deprecated_functions/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_Diagnostics`
|
|
|
|
Enable [extended diagnostic messages](https://json.nlohmann.me/home/exceptions/#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md). This option is `OFF` by default.
|
|
|
|
Does not apply to a pre-installed package
|
|
|
|
This option only takes effect when building nlohmann/json from source as part of your own CMake project (e.g. via [`FetchContent`](#fetchcontent) or [`add_subdirectory`](#embedded)). It has **no effect** on a package that was already built and installed elsewhere (Homebrew, vcpkg, a system package, etc.) — the resulting compile definition is baked into the exported `nlohmann_jsonTargets.cmake` at install time, and `set(JSON_Diagnostics ON)` before `find_package()` does not change it (verified against the Homebrew-installed package: the exported target still carries a fixed `$<$<BOOL:OFF>:JSON_DIAGNOSTICS=1>`, regardless of any variable set in the consuming project).
|
|
|
|
To enable extended diagnostics for a pre-installed package, override the imported target's property directly after `find_package()`:
|
|
|
|
```
|
|
find_package(nlohmann_json REQUIRED)
|
|
set_target_properties(nlohmann_json::nlohmann_json PROPERTIES
|
|
INTERFACE_COMPILE_DEFINITIONS "JSON_DIAGNOSTICS=1")
|
|
```
|
|
|
|
This only works cleanly when your project is the sole consumer of that imported target. If nlohmann_json is pulled in from more than one place in your dependency graph with different `JSON_DIAGNOSTICS` values, you may see a `"JSON_DIAGNOSTICS" redefined` compiler error, since conflicting `-D` flags can end up on the same compile command line.
|
|
|
|
### `JSON_Diagnostic_Positions`
|
|
|
|
Enable position diagnostics by defining macro [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_DisableEnumSerialization`
|
|
|
|
Disable default `enum` serialization by defining the macro [`JSON_DISABLE_ENUM_SERIALIZATION`](https://json.nlohmann.me/api/macros/json_disable_enum_serialization/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_DisableTupleReferenceConversion`
|
|
|
|
Disable the conversion from a one-element `std::tuple` holding a reference to a JSON value by defining the macro [`JSON_DISABLE_TUPLE_REFERENCE_CONVERSION`](https://json.nlohmann.me/api/macros/json_disable_tuple_reference_conversion/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_FastTests`
|
|
|
|
Skip expensive/slow test suites. This option is `OFF` by default. Depends on `JSON_BuildTests`.
|
|
|
|
### `JSON_GlobalUDLs`
|
|
|
|
Place user-defined string literals in the global namespace by defining the macro [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md). This option is `ON` by default; see the [migration guide](https://json.nlohmann.me/integration/migration_guide/#import-namespace-literals-for-udls) for how to prepare code for the next major release, where the literals are removed from the global namespace.
|
|
|
|
### `JSON_ImplicitConversions`
|
|
|
|
Enable implicit conversions by defining macro [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md). This option is `ON` by default; see the [migration guide](https://json.nlohmann.me/integration/migration_guide/#replace-implicit-conversions) for how to prepare code for the next major release, where implicit conversions are switched off by default.
|
|
|
|
### `JSON_Install`
|
|
|
|
Install CMake targets during install step. This option is `ON` by default if the library's CMake project is the top project. Installing also generates a [pkg-config](https://json.nlohmann.me/integration/pkg-config/index.md) file for tools that rely on `pkg-config` instead of CMake.
|
|
|
|
### `JSON_LegacyDiscardedValueComparison`
|
|
|
|
Enable the (incorrect) legacy comparison behavior of discarded JSON values by defining macro [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](https://json.nlohmann.me/api/macros/json_use_legacy_discarded_value_comparison/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_MultipleHeaders`
|
|
|
|
Use the non-amalgamated version of the library. This option is `ON` by default.
|
|
|
|
### `JSON_SystemInclude`
|
|
|
|
Treat the library headers like system headers (i.e., adding `SYSTEM` to the [`target_include_directories`](https://cmake.org/cmake/help/latest/command/target_include_directories.html) call) to check for this library by tools like Clang-Tidy. This option is `OFF` by default.
|
|
|
|
### `JSON_StrictBinaryUTF8`
|
|
|
|
Check string values and object keys for valid UTF-8 in the CBOR, UBJSON, BJData, and BSON writers, by defining the macro [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_StrictNulHandling`
|
|
|
|
Reject a `'\0'` (NUL) byte in the input instead of treating it as end of input, by defining the macro [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md). This option is `OFF` by default.
|
|
|
|
### `JSON_TestSimdutf`
|
|
|
|
Build the unit tests against the [simdutf](https://github.com/simdutf/simdutf) UTF-8 validation backend by defining [`JSON_USE_SIMDUTF`](https://json.nlohmann.me/api/macros/json_use_simdutf/index.md) for every test target. simdutf is fetched during configuration; its version is set by the cache variable `JSON_SIMDUTF_VERSION`. This option is `OFF` by default. Depends on `JSON_BuildTests`.
|
|
|
|
### `JSON_Valgrind`
|
|
|
|
Execute the test suite with [Valgrind](https://valgrind.org). This option is `OFF` by default. Depends on `JSON_BuildTests`.
|
|
|
|
### `NLOHMANN_JSON_BUILD_MODULES`
|
|
|
|
Build the experimental [C++ module](https://json.nlohmann.me/features/modules/index.md) `nlohmann.json` (requires CMake 3.28 or later and C++20). This option is `OFF` by default.
|
|
|
|
A consuming project must link the dedicated `nlohmann_json_modules` CMake target (not just `nlohmann_json::nlohmann_json`) for `import nlohmann.json;` to resolve:
|
|
|
|
```
|
|
set(NLOHMANN_JSON_BUILD_MODULES ON)
|
|
add_subdirectory(path/to/json)
|
|
|
|
add_executable(myproject main.cpp)
|
|
target_link_libraries(myproject PRIVATE nlohmann_json_modules)
|
|
target_compile_definitions(myproject PRIVATE NLOHMANN_JSON_BUILD_MODULES)
|
|
```
|