mirror of https://github.com/nlohmann/json.git synced 2026-09-30 14:05:18 +00:00

Files

Niels Lohmann 440383d20e Export json_document and json_view from the C++20 module

The nlohmann.json module includes json_view.hpp in its global module
fragment and exports basic_json_document, basic_json_view, and the four
aliases next to basic_json, json, and ordered_json. features/modules.md
lists them, and tests/module_cpp20 parses a document, so that a missing
export fails the ci_module_cpp20 job.

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

2026-09-30 15:07:19 +02:00

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

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), the macro NLOHMANN_JSON_BUILD_MODULES must be passed to the build system.

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 json = 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::json
nlohmann::json_document
nlohmann::json_pointer
nlohmann::json_view
nlohmann::ordered_json
nlohmann::ordered_json_document
nlohmann::ordered_json_view
nlohmann::ordered_map
nlohmann::to_string
nlohmann::literals::json_literals::operator""_json
nlohmann::literals::json_literals::operator""_json_pointer

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

Known issues

C++20 modules support is exercised in CI 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.

3.2 KiB Raw Blame History