amorfo77/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-11-13 15:35:23 +00:00

Files

T

Niels Lohmann 3004829134 Use CMake 4.5's stable import std support in the module test

CMake 4.5 makes `import std` available to every target that scans for
C++ modules and drops the experimental CMAKE_EXPERIMENTAL_CXX_IMPORT_STD
gate and the CXX_MODULE_STD property. The module test no longer needs the
version-specific opt-in token, so the ci_module_cpp20 jobs no longer have
to pin CMake 4.3.4 and now request CMake ^4.5.0.

The modules, CMake and README documentation now list the CMake, generator
and toolchain requirements for building the module and for `import std;`.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-11-13 09:36:55 +01:00

5.0 KiB

Raw Blame History

Modules

This library has experimental support for C++ modules, introduced in C++20. The library can be imported by writing import nlohmann.json; instead of #include <nlohmann/json.hpp>.

Please be aware that the module is experimental and a full test is outstanding, and the exported symbols are subject to change.

Importing the module instead of including the header reduces the compile time of every translation unit that uses the library, at the price of building the module once. The Compile times page has measurements and the one-off cost.

Requirements

The nlohmann.json module requires that the build system is configured to build and resolve modules when imported. Obviously, as modules were introduced in C++20, this feature can only be used in C++20 and subsequent versions.

To enable building the nlohmann.json module (which is not done by default), set the CMake option NLOHMANN_JSON_BUILD_MODULES and link the nlohmann_json_modules target.

With CMake, building the module needs:

CMake 3.28 or newer, and
a generator that scans for modules: Ninja (1.11 or newer), Ninja Multi-Config, or Visual Studio 2022 or newer.

The example below also uses import std;. CMake supports it without experimental opt-in since version 4.5, and then only with the Ninja generators and these toolchains: Clang 18.1.2 or newer (with libc++ or libstdc++), MSVC toolset 14.36 (Visual Studio 17.6) or newer, and GCC 15 or newer (GCC 16 on macOS). With older CMake versions, import std; needs CMake's version-specific experimental opt-in.

Example

When using modules rather than headers, the previous example for creating a json object through a JSON file, would instead be:

import std;
import nlohmann.json;

using nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

Modules do not export macros

It should be noted that as modules do not export macros, the nlohmann.json module will not export any macros.

Exported symbols

Only the following symbols are exported from nlohmann.json:

nlohmann::adl_serializer
nlohmann::basic_json
nlohmann::basic_json_document
nlohmann::basic_json_view
nlohmann::is_json_view
nlohmann::json
nlohmann::json_document
nlohmann::json_editable_document
nlohmann::json_editable_view
nlohmann::json_pointer
nlohmann::json_view
nlohmann::ordered_json
nlohmann::ordered_json_document
nlohmann::ordered_json_editable_document
nlohmann::ordered_json_editable_view
nlohmann::ordered_json_view
nlohmann::ordered_map
nlohmann::to_string
nlohmann::view_mode
nlohmann::literals::json_literals::operator""_json
nlohmann::literals::json_literals::operator""_json_pointer

The module always exports the two user-defined string literals, even if JSON_NO_AUTOMATIC_UDLS is defined when building it.

Additionally, the following nlohmann::detail symbols are exported, solely to work around an MSVC compilation issue (#3970). They are implementation details, not part of the public API, and should not be used directly:

nlohmann::detail::json_sax_dom_callback_parser
nlohmann::detail::json_sax_dom_parser
nlohmann::detail::unknown_size

Known issues

C++20 modules support is exercised in CI with CMake 4.5 and import std; against current GCC and Clang on Ubuntu, and the default MSVC toolset on Windows Server 2022 — there is no documented minimum compiler version, unlike feature-test-macro-gated features such as JSON_HAS_RANGES.

!!! info "Known compiler issues"

- **GCC** may emit "redefinition" errors when `#include <nlohmann/json.hpp>` appears in a module preamble together with other imports. This is an upstream GCC bug, not yet resolved as of GCC 16. Workarounds: include `nlohmann/json.hpp` before other `#include`s, use `import nlohmann.json;` instead, or upgrade GCC. ([issue #5103](https://github.com/nlohmann/json/issues/5103))
- **MSVC** could fail with `C2039: 'json_sax_dom_callback_parser' is not a member of ... detail`; fixed by exporting the required internal symbols from `json.cppm` (see [Exported symbols](#exported-symbols) above). ([issue #3970](https://github.com/nlohmann/json/issues/3970))

If you hit a different module-related build failure, search [existing issues](https://github.com/nlohmann/json/issues?q=is%3Aissue+modules) before filing a new one.

5.0 KiB Raw Blame History