path: root/docs/handbook/json4cpp/building.md

# json4cpp — Building and Integration

## Header-Only Usage

json4cpp (nlohmann/json 3.12.0) is a header-only library. The simplest way
to use it is to copy the single amalgamated header and include it:

```cpp
#include "nlohmann/json.hpp"

using json = nlohmann::json;
```

### Single Header vs. Multi-Header

The library ships in two forms:

| Form | Location | Use Case |
|---|---|---|
| Single header | `single_include/nlohmann/json.hpp` | Simplest integration |
| Multi-header | `include/nlohmann/json.hpp` + `include/nlohmann/detail/` | Better IDE navigation, faster incremental builds |

The single header (`json.hpp`, ~25,000 lines) is generated by amalgamating
all the multi-header files. It also ships `json_fwd.hpp` for forward
declarations without pulling in the full implementation.

### Forward Declaration Header

```cpp
#include <nlohmann/json_fwd.hpp>

// Now you can declare functions accepting json parameters
void process(const nlohmann::json& data);
```

The forward header declares `basic_json`, `json`, `ordered_json`,
`json_pointer`, `ordered_map`, and `adl_serializer` without including
any implementation.

## CMake Integration

### As a Subdirectory

```cmake
add_subdirectory(json4cpp)  # or wherever the library lives

target_link_libraries(my_target PRIVATE nlohmann_json::nlohmann_json)
```

### Via `FetchContent`

```cmake
include(FetchContent)
FetchContent_Declare(
    json
    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/json4cpp
)
FetchContent_MakeAvailable(json)

target_link_libraries(my_target PRIVATE nlohmann_json::nlohmann_json)
```

### Via `find_package` (After Install)

```cmake
find_package(nlohmann_json 3.12.0 REQUIRED)
target_link_libraries(my_target PRIVATE nlohmann_json::nlohmann_json)
```

### Target Include Directories

For the simplest possible integration without CMake targets:

```cmake
target_include_directories(my_target PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/json4cpp/single_include
)
```

Or for multi-header:

```cmake
target_include_directories(my_target PRIVATE
    ${CMAKE_CURRENT_SOURCE_DIR}/json4cpp/include
)
```

## CMake Options Reference

The top-level `CMakeLists.txt` defines these options:

```cmake
cmake_minimum_required(VERSION 3.5...4.0)
project(nlohmann_json VERSION 3.12.0 LANGUAGES CXX)
```

### Build Options

| Option | Default | Description |
|---|---|---|
| `JSON_BuildTests` | `ON` (main project) | Build the test suite |
| `JSON_CI` | `OFF` | Enable CI build targets |
| `JSON_Diagnostics` | `OFF` | Extended diagnostic messages |
| `JSON_Diagnostic_Positions` | `OFF` | Track byte positions |
| `JSON_GlobalUDLs` | `ON` | Place UDLs in global namespace |
| `JSON_ImplicitConversions` | `ON` | Enable implicit `operator T()` |
| `JSON_DisableEnumSerialization` | `OFF` | Disable automatic enum conversion |
| `JSON_LegacyDiscardedValueComparison` | `OFF` | Legacy comparison behavior |
| `JSON_Install` | `ON` (main project) | Install CMake targets |
| `JSON_MultipleHeaders` | `ON` | Use multi-header tree |
| `JSON_SystemInclude` | `OFF` | Include as system headers |

### Configuration Variables

```cmake
NLOHMANN_JSON_TARGET_NAME          # Override target name (default: nlohmann_json)
NLOHMANN_JSON_CONFIG_INSTALL_DIR   # CMake config install dir
NLOHMANN_JSON_INCLUDE_INSTALL_DIR  # Header install dir
```

### Header Selection Logic

```cmake
if (JSON_MultipleHeaders)
    set(NLOHMANN_JSON_INCLUDE_BUILD_DIR "${PROJECT_SOURCE_DIR}/include/")
else()
    set(NLOHMANN_JSON_INCLUDE_BUILD_DIR "${PROJECT_SOURCE_DIR}/single_include/")
endif()
```

### Compile Definitions Set by CMake

When options are toggled, CMake sets preprocessor definitions on the target:

```cmake
if (JSON_Diagnostics)
    target_compile_definitions(nlohmann_json INTERFACE JSON_DIAGNOSTICS=1)
endif()

if (NOT JSON_ImplicitConversions)
    target_compile_definitions(nlohmann_json INTERFACE JSON_USE_IMPLICIT_CONVERSIONS=0)
endif()

if (JSON_DisableEnumSerialization)
    target_compile_definitions(nlohmann_json INTERFACE JSON_DISABLE_ENUM_SERIALIZATION=1)
endif()

if (JSON_Diagnostic_Positions)
    target_compile_definitions(nlohmann_json INTERFACE JSON_DIAGNOSTIC_POSITIONS=1)
endif()

if (NOT JSON_GlobalUDLs)
    target_compile_definitions(nlohmann_json INTERFACE JSON_USE_GLOBAL_UDLS=0)
endif()

if (JSON_LegacyDiscardedValueComparison)
    target_compile_definitions(nlohmann_json INTERFACE JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1)
endif()
```

## Other Build Systems

### Bazel

```python
# BUILD.bazel is provided at the top level
cc_library(
    name = "json",
    hdrs = glob(["include/**/*.hpp"]),
    includes = ["include"],
)
```

A `MODULE.bazel` file is also provided for Bzlmod support.

### Meson

```meson
# meson.build is provided at the top level
nlohmann_json_dep = dependency('nlohmann_json', fallback: ['nlohmann_json', 'nlohmann_json_dep'])
```

### Swift Package Manager

```swift
// Package.swift is provided
.package(path: "json4cpp")
```

### pkg-config

After installation, a `nlohmann_json.pc` file is generated from
`cmake/pkg-config.pc.in`:

```
pkg-config --cflags nlohmann_json
```

## Preprocessor Configuration Macros

These macros can be defined before including the header or via compiler
flags to control library behavior:

### Core Behavior

| Macro | Values | Effect |
|---|---|---|
| `JSON_DIAGNOSTICS` | `0`/`1` | Extended error messages with parent-chain paths |
| `JSON_DIAGNOSTIC_POSITIONS` | `0`/`1` | Track byte positions in parsed values |
| `JSON_USE_IMPLICIT_CONVERSIONS` | `0`/`1` | Enable/disable implicit `operator T()` |
| `JSON_DISABLE_ENUM_SERIALIZATION` | `0`/`1` | Disable enum-to-integer serialization |
| `JSON_USE_GLOBAL_UDLS` | `0`/`1` | Place `_json` / `_json_pointer` UDLs in global scope |
| `JSON_NO_IO` | defined/undefined | Disable all stream-based I/O |
| `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON` | `0`/`1` | Legacy discarded value comparison |

### Assertion Customization

```cpp
// Override the assertion macro (default: assert())
#define JSON_ASSERT(x) my_assert(x)
```

### Exception Customization

```cpp
// Override throw behavior
#define JSON_THROW(exception) throw exception
#define JSON_TRY try
#define JSON_CATCH(exception) catch(exception)
#define JSON_INTERNAL_CATCH(exception) catch(exception)
```

To disable exceptions entirely:

```cpp
#define JSON_THROW(exception) std::abort()
#define JSON_TRY if(true)
#define JSON_CATCH(exception) if(false)
#define JSON_INTERNAL_CATCH(exception) if(false)
```

### Version Macros

```cpp
NLOHMANN_JSON_VERSION_MAJOR  // 3
NLOHMANN_JSON_VERSION_MINOR  // 12
NLOHMANN_JSON_VERSION_PATCH  // 0
```

### Standard Detection Macros

Set automatically based on the compiler:

```cpp
JSON_HAS_CPP_11  // always 1
JSON_HAS_CPP_14  // 1 if C++14 or higher
JSON_HAS_CPP_17  // 1 if C++17 or higher
JSON_HAS_CPP_20  // 1 if C++20 or higher
```

### RTTI Detection

```cpp
JSON_HAS_STATIC_RTTI  // 1 if RTTI is available
```

### Three-Way Comparison Detection

```cpp
JSON_HAS_THREE_WAY_COMPARISON  // 1 if <=> is available
```

## C++20 Module Support

The library includes experimental C++20 module support:

```cmake
option(NLOHMANN_JSON_BUILD_MODULES "Build C++ modules support" OFF)
```

When enabled and CMake >= 3.28 is available, the module is built from
`src/modules/`. Usage:

```cpp
import nlohmann.json;
```

## Compiler-Specific Notes

### GCC

The `cmake/gcc_flags.cmake` file configures GCC-specific warning flags.
GCC 4.8 support requires workarounds (user-defined literal spacing).

### Clang

`cmake/clang_flags.cmake` handles Clang warning configuration. The
`-Wweak-vtables` warning is suppressed in `detail/exceptions.hpp`
since header-only libraries cannot have out-of-line vtables.

### MSVC

MSVC receives specific warning suppressions. The `nlohmann_json.natvis`
file provides Visual Studio debugger visualization:

```xml
<!-- nlohmann_json.natvis provides structured views in the VS debugger -->
```

## Installation

### Default Installation Layout

```bash
cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build
cmake --install build
```

This installs:

```
/usr/local/include/nlohmann/           # Headers
/usr/local/share/cmake/nlohmann_json/  # CMake config files
/usr/local/share/pkgconfig/            # pkg-config file
```

### Controlling Installation

```cmake
set(JSON_Install OFF)  # Disable installation entirely
```

### Version Compatibility

The installed `nlohmann_jsonConfigVersion.cmake` file supports version
range checking, allowing consumers to request minimum versions:

```cmake
find_package(nlohmann_json 3.11.0 REQUIRED)  # any 3.x >= 3.11.0
```

## Integration Patterns

### Pattern 1: Copy Single Header

```bash
cp json4cpp/single_include/nlohmann/json.hpp my_project/third_party/
```

```cpp
#include "third_party/json.hpp"
```

### Pattern 2: Git Submodule + CMake

```bash
git submodule add <url> third_party/json
```

```cmake
add_subdirectory(third_party/json)
target_link_libraries(my_target PRIVATE nlohmann_json::nlohmann_json)
```

### Pattern 3: System Package

Most Linux distributions package nlohmann/json:

```bash
# Debian/Ubuntu
apt install nlohmann-json3-dev

# Fedora
dnf install json-devel

# Arch
pacman -S nlohmann-json

# macOS
brew install nlohmann-json
```

### Pattern 4: Header-Only with Forward Declarations

For faster compilation, use the forward declaration header in headers
and the full header only in implementation files:

```cpp
// my_class.hpp
#include <nlohmann/json_fwd.hpp>
class MyClass {
    void process(const nlohmann::json& j);
};

// my_class.cpp
#include <nlohmann/json.hpp>
#include "my_class.hpp"
void MyClass::process(const nlohmann::json& j) { ... }
```

## Compilation Speed Tips

1. **Use `json_fwd.hpp`** in headers to avoid pulling the full
   implementation into every translation unit.

2. **Precompiled headers** — add `nlohmann/json.hpp` to your PCH:
   ```cmake
   target_precompile_headers(my_target PRIVATE <nlohmann/json.hpp>)
   ```

3. **Unity builds** work naturally since the library is header-only.

4. **Multi-header mode** with `JSON_MultipleHeaders=ON` can improve
   incremental rebuild times since changes to one detail header don't
   invalidate the entire amalgamated file.

5. **`JSON_NO_IO`** — define this if you don't need stream operators,
   reducing the include chain.

## Minimum Requirements

| Requirement | Minimum |
|---|---|
| C++ Standard | C++11 |
| CMake | 3.5 (3.28 for modules) |
| GCC | 4.8 |
| Clang | 3.4 |
| MSVC | 2015 (19.0) |
| Intel C++ | 2017 |