* 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> * Bump lukka/get-cmake from 4.4.5 to 4.5.0 get-cmake 4.4.5 does not know CMake 4.5.0, so the ci_module_cpp20 jobs that request '^4.5.0' failed in the setup step. Bump every pin so all jobs use the same action version. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Install unzip in the Clang module job before get-cmake The ^4.5.0 CMake/Ninja cache key is new, so get-cmake has to unzip the Ninja download, and silkeh/clang:latest has no unzip. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Disable C++ module scanning for the unit tests With CMake 4.5, every target that scans for C++ modules gets a synthesized std module target. For the C++20 and newer unit-test targets, this compiled libstdc++'s std.cc with the -Werror test flags and failed to configure with libc++ images that lack std.compat.cppm. The unit tests use no modules, so turn scanning off; the module test is a separate project. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
99 lines
5.0 KiB
Markdown
99 lines
5.0 KiB
Markdown
# 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](../integration/compile_times.md#use-c20-modules) 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`](../integration/cmake.md#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:
|
|
```cpp
|
|
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`](../api/macros/json_no_automatic_udls.md) is defined when building it.
|
|
|
|
Additionally, the following `nlohmann::detail` symbols are exported, solely to work around an MSVC compilation issue
|
|
([#3970](https://github.com/nlohmann/json/issues/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`](../api/macros/json_has_ranges.md).
|
|
|
|
!!! 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.
|
|
|
|
## See also
|
|
|
|
- [Supported Macros](macros.md) - macros are not exported by modules
|
|
- [Macros](../api/macros/index.md) - reference of all macros
|
|
- [`nlohmann` Namespace](namespace.md) - the library namespace
|
|
- [CMake](../integration/cmake.md) - enable the module build in CMake
|
|
- [Compile times](../integration/compile_times.md) - reduce compile times
|
|
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions
|