json/integration/cmake.md

# 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](package_managers.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

    ```cmake title="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

    ```cmake title="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 `#!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.


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

    ```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.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

    ```cmake title="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

    ```cmake
    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`](../api/macros/json_delete_deprecated_functions.md). This option is `OFF` by
default.

### `JSON_Diagnostics`

Enable [extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) by defining macro [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This option is `OFF` by default.

!!! warning "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()`:

    ```cmake
    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`](../api/macros/json_diagnostic_positions.md). This option is `OFF` by default.

### `JSON_DisableEnumSerialization`

Disable default `enum` serialization by defining the macro
[`JSON_DISABLE_ENUM_SERIALIZATION`](../api/macros/json_disable_enum_serialization.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`](../api/macros/json_disable_tuple_reference_conversion.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`](../api/macros/json_use_global_udls.md). This option is `ON` by default; see the
[migration guide](migration_guide.md#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`](../api/macros/json_use_implicit_conversions.md). This option is `ON` by default; see
the [migration guide](migration_guide.md#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](pkg-config.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`](../api/macros/json_use_legacy_discarded_value_comparison.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`](../api/macros/json_strict_binary_utf8.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`](../api/macros/json_strict_nul_handling.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`](../api/macros/json_use_simdutf.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](../features/modules.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:

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