Add proper C++20 module support (#4799)

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
 ##

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:

cmake/ci.cmake

@@ -666,6 +666,7 @@ add_custom_target(ci_cuda_example
 add_custom_target(ci_module_cpp20
     COMMAND ${CMAKE_COMMAND}
         -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
 )

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 <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:
+```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`

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:

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)

src/modules/json.cppm

@@ -0,0 +1,22 @@
+module;
+
+#include <nlohmann/json.hpp>
+
+export module nlohmann.json;
+
+export namespace nlohmann {
+    template <typename T = void, typename SFINAE = void>
+    using adl_serializer = ::nlohmann::adl_serializer<T, SFINAE>;
+
+    using basic_json = ::nlohmann::basic_json<>;
+
+    using json = ::nlohmann::json;
+
+    template <typename RefStringType>
+    using json_pointer = ::nlohmann::json_pointer<RefStringType>;
+
+    using ::nlohmann::ordered_json;
+
+    template <class Key, class T, class IgnoredLess, class Allocator>
+    using ordered_map = ::nlohmann::ordered_map<Key, T, IgnoredLess, Allocator>;
+}  // namespace nlohmann

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)

tests/module_cpp20/json.cpp

@@ -1,17 +0,0 @@
-module;
-#include <nlohmann/json.hpp>
-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

tests/module_cpp20/main.cpp

@@ -1,4 +1,4 @@
-import json;
+import nlohmann.json;
 
 int main()
 {