# 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)
```