diff --git a/.github/workflows/ubuntu.yml b/.github/workflows/ubuntu.yml index 0f6956254..d8a467f29 100644 --- a/.github/workflows/ubuntu.yml +++ b/.github/workflows/ubuntu.yml @@ -25,7 +25,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -38,7 +38,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Check that Meson and pkg-config offer the CMake options run: make check_build_options - name: Install Meson @@ -92,7 +92,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -123,7 +123,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -142,7 +142,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -168,7 +168,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -244,7 +244,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: CXX=g++-${{ matrix.compiler }} cmake -S . -B build -DJSON_CI=On - name: Build @@ -262,7 +262,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -279,7 +279,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Disable filesystem support (std::filesystem is unusable) for clang 7 / 8 / 9 / 10 run: echo "JSON_FORCED_GLOBAL_COMPILE_OPTIONS=-DJSON_HAS_FILESYSTEM=0;-DJSON_HAS_EXPERIMENTAL_FILESYSTEM=0" >> "$GITHUB_ENV" if: ${{ matrix.compiler == '7' || matrix.compiler == '8' || matrix.compiler == '9' || matrix.compiler == '10' }} @@ -299,7 +299,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -319,7 +319,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build with libc++ @@ -346,7 +346,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -362,13 +362,16 @@ 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 - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + # get-cmake extracts the Ninja zip with the system unzip, which the Clang + # image lacks; other Clang jobs get away with it by hitting the cache. + - name: Install unzip (Clang) + if: matrix.container == 'silkeh/clang:latest' + run: apt-get update ; apt-get install -y unzip + # The module test uses `import std;`, which needs CMake 4.5 or newer. + - name: Get CMake 4.5+ and ninja + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 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. @@ -392,7 +395,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -409,7 +412,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -423,7 +426,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DJSON_CI=On - name: Build @@ -443,7 +446,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Run CMake run: cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=$EMSDK/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake -GNinja - name: Build @@ -484,7 +487,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Check that the job runs natively on arm64 run: uname -m && test "$(uname -m)" = aarch64 - name: Run CMake diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml index b9f9d0251..cbcd3f7d1 100644 --- a/.github/workflows/windows.yml +++ b/.github/workflows/windows.yml @@ -90,7 +90,7 @@ jobs: with: persist-credentials: false - name: Get latest CMake and ninja - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 - name: Set extra CXX_FLAGS for latest std_version # /wd5285 silences C5285 emitted by the bundled third-party doctest.h, which # specializes std::tuple (newly diagnosed by the VS2026 v145 toolset) @@ -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 - uses: lukka/get-cmake@f86dd60acae0d132056913e248bdabf0e0580b7a # v4.4.5 + # The module test uses `import std;`, which needs CMake 4.5 or newer. + - name: Get CMake 4.5+ and ninja + uses: lukka/get-cmake@16e8153a8b4918849d92aad131befe67a3705daa # v4.5.0 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/CMakeLists.txt b/tests/CMakeLists.txt index a20d92610..52d46f618 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -1,5 +1,12 @@ cmake_minimum_required(VERSION 3.13...4.0) +# The unit tests use no C++ modules. Without this, CMake 4.5 scans the C++20 and +# newer test targets and builds a `std` module for them, compiling the standard +# library's module sources with the test warning flags (which fails with +# -Werror) or failing to configure when the libc++ module sources are missing. +# The module test in tests/module_cpp20 is a separate project and unaffected. +set(CMAKE_CXX_SCAN_FOR_MODULES OFF) + option(JSON_Valgrind "Execute test suite with Valgrind." OFF) option(JSON_FastTests "Skip expensive/slow tests." OFF) option(JSON_TestSimdutf "Build the unit tests against the simdutf UTF-8 validation backend." OFF) 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