diff options
Diffstat (limited to 'docs/handbook/json4cpp/building.md')
| -rw-r--r-- | docs/handbook/json4cpp/building.md | 430 |
1 files changed, 430 insertions, 0 deletions
diff --git a/docs/handbook/json4cpp/building.md b/docs/handbook/json4cpp/building.md new file mode 100644 index 0000000000..73e29a65fc --- /dev/null +++ b/docs/handbook/json4cpp/building.md @@ -0,0 +1,430 @@ +# 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 | |