From b7f741165b224fb798c3702e1975a005c2d8f489 Mon Sep 17 00:00:00 2001 From: Miko <110693261+mikomikotaishi@users.noreply.github.com> Date: Sun, 29 Jun 2025 16:02:31 -0400 Subject: [PATCH] Add proper C++20 module support (#4799) --- CMakeLists.txt | 12 ++++++++++ README.md | 13 +++++++++++ cmake/ci.cmake | 3 ++- docs/mkdocs/docs/features/modules.md | 33 ++++++++++++++++++++++++++++ docs/mkdocs/mkdocs.yml | 1 + src/modules/CMakeLists.txt | 27 +++++++++++++++++++++++ src/modules/json.cppm | 22 +++++++++++++++++++ tests/module_cpp20/CMakeLists.txt | 17 +++++++++----- tests/module_cpp20/json.cpp | 17 -------------- tests/module_cpp20/main.cpp | 2 +- 10 files changed, 123 insertions(+), 24 deletions(-) create mode 100644 docs/mkdocs/docs/features/modules.md create mode 100644 src/modules/CMakeLists.txt create mode 100644 src/modules/json.cppm delete mode 100644 tests/module_cpp20/json.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index 88ef6f661..6415b3838 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -22,6 +22,18 @@ endif() set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake ${CMAKE_MODULE_PATH}) include(ExternalProject) +# ---- C++ Modules Support (optional) ---- +option(NLOHMANN_JSON_BUILD_MODULES "Build C++ modules support" OFF) + +if(NLOHMANN_JSON_BUILD_MODULES) + if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.28) + message(STATUS "Building nlohmann.json C++ module") + add_subdirectory(src/modules) + else() + message(WARNING "Skipping nlohmann.json C++ module (requires CMake 3.28+, found ${CMAKE_VERSION})") + endif() +endif() + ## ## OPTIONS ## diff --git a/README.md b/README.md index 8a48d07c7..0ead1db6c 100644 --- a/README.md +++ b/README.md @@ -158,6 +158,19 @@ std::ifstream f("example.json"); json data = json::parse(f); ``` +If using modules (enabled with `NLOHMANN_JSON_BUILD_MODULES`), this example becomes: +```cpp +import std; +import nlohmann.json; + +using json = nlohmann::json; + +// ... + +std::ifstream f("example.json"); +json data = json::parse(f); +``` + ### Creating `json` objects from JSON literals Assume you want to create hard-code this literal JSON value in a file, as a `json` object: diff --git a/cmake/ci.cmake b/cmake/ci.cmake index 8c0d2106b..f71136864 100644 --- a/cmake/ci.cmake +++ b/cmake/ci.cmake @@ -665,7 +665,8 @@ add_custom_target(ci_cuda_example add_custom_target(ci_module_cpp20 COMMAND ${CMAKE_COMMAND} - -DCMAKE_BUILD_TYPE=Debug -GNinja + -DCMAKE_BUILD_TYPE=Debug -GNinja + -DJSON_CI=ON -DNLOHMANN_JSON_BUILD_MODULES=ON -DJSON_Install=ON -S${PROJECT_SOURCE_DIR}/tests/module_cpp20 -B${PROJECT_BINARY_DIR}/ci_module_cpp20 COMMAND ${CMAKE_COMMAND} --build ${PROJECT_BINARY_DIR}/ci_module_cpp20 ) diff --git a/docs/mkdocs/docs/features/modules.md b/docs/mkdocs/docs/features/modules.md new file mode 100644 index 000000000..884e9b07a --- /dev/null +++ b/docs/mkdocs/docs/features/modules.md @@ -0,0 +1,33 @@ +# 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 `. + +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: +```cpp +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, but rather only the following symbols: +- `nlohmann::adl_serializer` +- `nlohmann::basic_json` +- `nlohmann::json` +- `nlohmann::json_pointer` +- `nlohmann::ordered_map` +- `nlohmann::ordered_json` diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index 24588816a..57f7dd88d 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -77,6 +77,7 @@ nav: - features/json_pointer.md - features/json_patch.md - features/merge_patch.md + - features/modules.md - 'nlohmann Namespace': features/namespace.md - features/object_order.md - Parsing: diff --git a/src/modules/CMakeLists.txt b/src/modules/CMakeLists.txt new file mode 100644 index 000000000..f8b79d0ef --- /dev/null +++ b/src/modules/CMakeLists.txt @@ -0,0 +1,27 @@ +cmake_minimum_required(VERSION 3.28) + +add_library(nlohmann_json_modules) + +set(NLOHMANN_JSON_MODULES + json.cppm +) + +if(NOT COMMAND configure_cpp_module_target) + function(configure_cpp_module_target target) + target_sources(${target} PUBLIC FILE_SET CXX_MODULES FILES ${NLOHMANN_JSON_MODULES}) + endfunction() +endif() + +configure_cpp_module_target(nlohmann_json_modules) + +target_link_libraries(nlohmann_json_modules + PUBLIC + nlohmann_json::nlohmann_json +) + +target_include_directories(nlohmann_json_modules + PRIVATE + ${PROJECT_SOURCE_DIR}/include +) + +target_compile_features(nlohmann_json_modules PUBLIC cxx_std_20) diff --git a/src/modules/json.cppm b/src/modules/json.cppm new file mode 100644 index 000000000..71a4bd827 --- /dev/null +++ b/src/modules/json.cppm @@ -0,0 +1,22 @@ +module; + +#include + +export module nlohmann.json; + +export namespace nlohmann { + template + using adl_serializer = ::nlohmann::adl_serializer; + + using basic_json = ::nlohmann::basic_json<>; + + using json = ::nlohmann::json; + + template + using json_pointer = ::nlohmann::json_pointer; + + using ::nlohmann::ordered_json; + + template + using ordered_map = ::nlohmann::ordered_map; +} // namespace nlohmann diff --git a/tests/module_cpp20/CMakeLists.txt b/tests/module_cpp20/CMakeLists.txt index 23884342c..b6d395aaa 100644 --- a/tests/module_cpp20/CMakeLists.txt +++ b/tests/module_cpp20/CMakeLists.txt @@ -2,11 +2,18 @@ cmake_minimum_required(VERSION 3.28) project(json_test CXX) -add_executable(json_test) +set(NLOHMANN_JSON_BUILD_MODULES ON CACHE BOOL "Enable nlohmann.json module support") -target_sources(json_test - PRIVATE main.cpp - PUBLIC FILE_SET cxx_modules TYPE CXX_MODULES FILES json.cpp) +add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../.. ${CMAKE_CURRENT_BINARY_DIR}/tests) + +add_executable(json_test main.cpp) +target_link_libraries(json_test + PRIVATE + nlohmann_json_modules +) + +target_compile_definitions(json_test + PRIVATE NLOHMANN_JSON_BUILD_MODULES +) target_compile_features(json_test PUBLIC cxx_std_20) -target_include_directories(json_test PRIVATE ../../include) diff --git a/tests/module_cpp20/json.cpp b/tests/module_cpp20/json.cpp deleted file mode 100644 index 8d5cc9147..000000000 --- a/tests/module_cpp20/json.cpp +++ /dev/null @@ -1,17 +0,0 @@ -module; -#include -export module json; - -export namespace nlohmann -{ -using ::nlohmann::adl_serializer; - -using ::nlohmann::basic_json; -using ::nlohmann::json_pointer; - -using ::nlohmann::json; -using ::nlohmann::ordered_json; -using ::nlohmann::ordered_map; - -using ::nlohmann::json_pointer; -} // namespace nlohmann diff --git a/tests/module_cpp20/main.cpp b/tests/module_cpp20/main.cpp index ad7bd8b1a..ec4c2fb13 100644 --- a/tests/module_cpp20/main.cpp +++ b/tests/module_cpp20/main.cpp @@ -1,4 +1,4 @@ -import json; +import nlohmann.json; int main() {