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

Example

CMakeLists.txt
cmake_minimum_required(VERSION 3.1)
project(ExampleProject LANGUAGES CXX)

find_package(nlohmann_json 3.10.5 REQUIRED)



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.1)
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 "")



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)

# Note that the namespaced target will always be available regardless of the import method

thirdparty/CMakeLists.txt
if(EXAMPLE_USE_EXTERNAL_JSON)
find_package(nlohmann_json 3.10.5 REQUIRED)
else()
set(JSON_BuildTests OFF CACHE INTERNAL "")
endif()


thirdparty/nlohmann_json is then a complete copy of this source tree.

### FetchContent¶

Since CMake v3.11, FetchContent can be used to automatically download a release as a dependency at configure type.

Example

CMakeLists.txt
cmake_minimum_required(VERSION 3.11)
project(ExampleProject LANGUAGES CXX)

include(FetchContent)

FetchContent_MakeAvailable(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.10.5
)


However, 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¶

### JSON_BuildTests¶

Build the unit tests when BUILD_TESTING is enabled. This option is ON by default if the library's CMake project is the top project. 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_Diagnostics¶

Enable extended diagnostic messages by defining macro JSON_DIAGNOSTICS. This option is OFF by default.

### JSON_FastTests¶

Skip expensive/slow test suites. This option is OFF by default. Depends on JSON_BuildTests.

### JSON_ImplicitConversions¶

Enable implicit conversions by defining macro JSON_USE_IMPLICIT_CONVERSIONS. This option is ON 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.

### JSON_MultipleHeaders¶

Use non-amalgamated version of the library. This option is OFF by default.

### JSON_SystemInclude¶

Treat the library headers like system headers (i.e., adding SYSTEM to the target_include_directories call) to checks for this library by tools like Clang-Tidy. This option is OFF by default.

### JSON_Valgrind¶

Execute test suite with Valgrind. This option is OFF by default. Depends on JSON_BuildTests.

Last update: May 1, 2022