diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml index 0f6956254..7aad52787 100644 --- a/.github/workflows/ubuntu.yml +++ b/.github/workflows/ubuntu.yml @@ -362,13 +362,11 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - # The module test uses `import std;`, which needs CMake's experimental - # import-std support. Its opt-in token is CMake-version-specific, so pin - # CMake to the version whose token is set in tests/module_cpp20/CMakeLists.txt. - - name: Get pinned CMake and ninja + # The module test uses `import std;`, which needs CMake 4.5 or newer. + - name: Get CMake 4.5+ and ninja uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 with: - cmakeVersion: 4.3.4 + cmakeVersion: '^4.5.0' # Clang: the std library module is provided by libc++ (the image's libstdc++ # ships none), and the image's libc++ module manifest has a broken relative # path — repoint it at the real module sources. diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index b9f9d0251..0643b002f 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -212,13 +212,11 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - # The module test uses `import std;`, which needs CMake's experimental - # import-std support. Its opt-in token is CMake-version-specific, so pin - # CMake to the version whose token is set in tests/module_cpp20/CMakeLists.txt. - - name: Get pinned CMake and ninja + # The module test uses `import std;`, which needs CMake 4.5 or newer. + - name: Get CMake 4.5+ and ninja uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 with: - cmakeVersion: 4.3.4 + cmakeVersion: '^4.5.0' # CMAKE_CXX_FLAGS replaces CMake's MSVC defaults (which include /EHsc), and # ci_module_cpp20 forwards it to the module build, so list /EHsc explicitly - name: Run CMake (Debug) diff --git a/README.md b/README.md index aedd7e69c..bfcd841eb 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,8 @@ std::ifstream f("example.json"); json data = json::parse(f); ``` -If using modules (enabled with `NLOHMANN_JSON_BUILD_MODULES`), this example becomes: +If using modules (enabled with `NLOHMANN_JSON_BUILD_MODULES`; `import std;` needs CMake 4.5 or newer, see the +[modules documentation](https://json.nlohmann.me/features/modules/)), this example becomes: ```cpp import std; import nlohmann.json; diff --git a/docs/mkdocs/docs/features/modules.md b/docs/mkdocs/docs/features/modules.md index 9b3b7acd0..7556cc6f2 100644 --- a/docs/mkdocs/docs/features/modules.md +++ b/docs/mkdocs/docs/features/modules.md @@ -9,7 +9,19 @@ Importing the module instead of including the header reduces the compile time of ## 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. +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: @@ -67,7 +79,7 @@ and should not be used directly: ## 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`](../api/macros/json_has_ranges.md). +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" diff --git a/docs/mkdocs/docs/integration/cmake.md b/docs/mkdocs/docs/integration/cmake.md index c693e971f..f6ac44fd3 100644 --- a/docs/mkdocs/docs/integration/cmake.md +++ b/docs/mkdocs/docs/integration/cmake.md @@ -269,6 +269,9 @@ target_link_libraries(myproject PRIVATE nlohmann_json_modules) target_compile_definitions(myproject PRIVATE NLOHMANN_JSON_BUILD_MODULES) ``` +If `main.cpp` also uses `import std;`, the project needs CMake 4.5 or newer and a Ninja generator; see +[Modules](../features/modules.md#requirements) for the supported toolchains. + ## See also - [Macros](../api/macros/index.md) - reference of all macros diff --git a/tests/module_cpp20/CMakeLists.txt b/tests/module_cpp20/CMakeLists.txt index 92d4b27e0..bd4394854 100644 --- a/tests/module_cpp20/CMakeLists.txt +++ b/tests/module_cpp20/CMakeLists.txt @@ -1,11 +1,6 @@ -cmake_minimum_required(VERSION 3.30) - -# `import std;` (used by main.cpp) needs CMake's experimental C++ import-std -# support. The accepted token is CMake-version-specific; this value matches the -# CMake version pinned in the ci_module_cpp20 CI jobs (4.3.x). If that pin is -# bumped, this token must be updated to match (configuration fails loudly -# otherwise). -set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "451f2fe2-a8a2-47c3-bc32-94786d8fc91b") +# `import std;` (used by main.cpp) is supported without experimental opt-in +# since CMake 4.5: it is available to every target that scans for C++ modules. +cmake_minimum_required(VERSION 4.5) project(json_test CXX) @@ -13,7 +8,6 @@ project(json_test CXX) set(CMAKE_CXX_STANDARD 23) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_EXTENSIONS OFF) -set(CMAKE_CXX_MODULE_STD ON) set(NLOHMANN_JSON_BUILD_MODULES ON CACHE BOOL "Enable nlohmann.json module support") diff --git a/tests/module_cpp20/main.cpp b/tests/module_cpp20/main.cpp index a475c8bff..1d9d36a0a 100644 --- a/tests/module_cpp20/main.cpp +++ b/tests/module_cpp20/main.cpp @@ -17,8 +17,8 @@ using namespace nlohmann::literals; // Standard-library facilities are pulled in via `import std;` rather than // textual `#include`s: mixing `import` with textual standard headers does not // compile under GCC's C++20 modules implementation, whereas `import std;` works -// across GCC, Clang, and MSVC. This requires C++23 and CMake's (experimental) -// import-std support; see CMakeLists.txt. +// across GCC, Clang, and MSVC. This requires C++23 and CMake 4.5 or newer; +// see CMakeLists.txt. int main() { // basic_json / json: parsing and value access