Separate macro definitions and add cppm files

.github/workflows/bvt-appleclang.yml

@@ -20,7 +20,7 @@ jobs:
 
     - name: build and run test with AppleClang
       run: |
-        cmake -B build -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build -GNinja -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

.github/workflows/bvt-clang.yml

@@ -26,7 +26,7 @@ jobs:
 
     - name: build and run test with clang 20
       run: |
-        cmake -B build -DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build -GNinja -DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

.github/workflows/bvt-compatibility.yml

@@ -26,39 +26,39 @@ jobs:
         clang++-18 --version
         clang++-19 --version
 
-    - name: build and run test with gcc 13
-      run: |
-        cmake -B build-gcc-13 -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 -DCMAKE_BUILD_TYPE=Release
-        cmake --build build-gcc-13 -j
-        ctest --test-dir build-gcc-13 -j
-
     - name: build and run test with gcc 14
       run: |
-        cmake -B build-gcc-14 -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build-gcc-14 -GNinja -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
         cmake --build build-gcc-14 -j
         ctest --test-dir build-gcc-14 -j
 
-    # Note that libc++ in Clang 19 is not compatible with Clang 16. Therefore, we fallback to libstdc++.
-    - name: build and run test with clang 16
+    - name: build and run test with gcc 13
       run: |
-        cmake -B build-clang-16 -DCMAKE_C_COMPILER=clang-16 -DCMAKE_CXX_COMPILER=clang++-16 -DCMAKE_BUILD_TYPE=Release
-        cmake --build build-clang-16 -j
-        ctest --test-dir build-clang-16 -j
+        cmake -B build-gcc-13 -DCMAKE_C_COMPILER=gcc-13 -DCMAKE_CXX_COMPILER=g++-13 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
+        cmake --build build-gcc-13 -j
+        ctest --test-dir build-gcc-13 -j
 
-    - name: build and run test with clang 17
+    - name: build and run test with clang 19
       run: |
-        cmake -B build-clang-17 -DCMAKE_C_COMPILER=clang-17 -DCMAKE_CXX_COMPILER=clang++-17 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release
-        cmake --build build-clang-17 -j
-        ctest --test-dir build-clang-17 -j
+        cmake -B build-clang-19 -DCMAKE_C_COMPILER=clang-19 -DCMAKE_CXX_COMPILER=clang++-19 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
+        cmake --build build-clang-19 -j
+        ctest --test-dir build-clang-19 -j
 
     - name: build and run test with clang 18
       run: |
-        cmake -B build-clang-18 -DCMAKE_C_COMPILER=clang-18 -DCMAKE_CXX_COMPILER=clang++-18 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release
+        cmake -B build-clang-18 -DCMAKE_C_COMPILER=clang-18 -DCMAKE_CXX_COMPILER=clang++-18 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build-clang-18 -j
         ctest --test-dir build-clang-18 -j
 
-    - name: build and run test with clang 19
+    - name: build and run test with clang 17
       run: |
-        cmake -B build-clang-19 -DCMAKE_C_COMPILER=clang-19 -DCMAKE_CXX_COMPILER=clang++-19 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release
-        cmake --build build-clang-19 -j
-        ctest --test-dir build-clang-19 -j
+        cmake -B build-clang-17 -DCMAKE_C_COMPILER=clang-17 -DCMAKE_CXX_COMPILER=clang++-17 -DCMAKE_CXX_FLAGS="-stdlib=libc++" -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
+        cmake --build build-clang-17 -j
+        ctest --test-dir build-clang-17 -j
+
+    # Note that libc++ in Clang 19 is not compatible with Clang 16. Therefore, we fallback to libstdc++.
+    - name: build and run test with clang 16
+      run: |
+        cmake -B build-clang-16 -DCMAKE_C_COMPILER=clang-16 -DCMAKE_CXX_COMPILER=clang++-16 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
+        cmake --build build-clang-16 -j
+        ctest --test-dir build-clang-16 -j

.github/workflows/bvt-gcc.yml

@@ -23,7 +23,7 @@ jobs:
 
     - name: build and run test with gcc 14
       run: |
-        cmake -B build -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release
+        cmake -B build -GNinja -DCMAKE_C_COMPILER=gcc-14 -DCMAKE_CXX_COMPILER=g++-14 -DCMAKE_CXX_STANDARD=23 -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=TRUE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

.github/workflows/bvt-msvc.yml

@@ -18,7 +18,7 @@ jobs:
 
     - name: build and run test with MSVC
       run: |
-        cmake -B build -DCMAKE_CXX_STANDARD=23
+        cmake -B build -DCMAKE_CXX_STANDARD=23 -DPROXY_BUILD_MODULES=TRUE
         cmake --build build --config Release -j
         ctest --test-dir build -j
         mkdir build\drop > $null

.github/workflows/bvt-nvhpc.yml

@@ -23,7 +23,7 @@ jobs:
     - name: build and run test with NVHPC 24.9
       run: |
         PATH=/opt/nvidia/hpc_sdk/Linux_x86_64/24.9/compilers/bin:$PATH; export PATH
-        cmake -B build -DCMAKE_C_COMPILER=nvc -DCMAKE_CXX_COMPILER=nvc++ -DCMAKE_BUILD_TYPE=Release
+        cmake -B build -GNinja -DCMAKE_C_COMPILER=nvc -DCMAKE_CXX_COMPILER=nvc++ -DCMAKE_BUILD_TYPE=Release -DPROXY_BUILD_MODULES=FALSE
         cmake --build build -j
         ctest --test-dir build -j
         mkdir build/drop

CMakeLists.txt

@@ -1,29 +1,86 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.28)
 
 project(msft_proxy VERSION 3.3.0 LANGUAGES CXX)
 add_library(msft_proxy INTERFACE)
+
+# Do not enable building tests if proxy is consumed as
+# subdirectory (e.g. by CMake FetchContent_Declare).
+if(PROJECT_IS_TOP_LEVEL)
+  option(BUILD_TESTING "Build tests" ON)
+else()
+  option(BUILD_TESTING "Build tests" OFF)
+endif()
+
+if(PROJECT_IS_TOP_LEVEL)
+  option(
+    PROXY_BUILD_MODULES
+    "When this project is top level, build the docs and tests with C++ module support."
+    OFF
+  )
+endif()
+
+target_sources(msft_proxy
+  INTERFACE
+    FILE_SET public_headers
+    TYPE HEADERS 
+    BASE_DIRS include
+    FILES
+      include/proxy/proxy.h
+      include/proxy/proxy_macros.h
+      include/proxy/proxy_fmt.h
+      include/proxy/proxy.ixx
+)
+
 target_compile_features(msft_proxy INTERFACE cxx_std_20)
-target_include_directories(msft_proxy INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+target_include_directories(msft_proxy INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
                                                 $<INSTALL_INTERFACE:include>)
 
+# Do not set the module target if proxy is consumed as a subdirectory.
+if(PROJECT_IS_TOP_LEVEL)
+  set(proxy_INCLUDE_DIR include)
+  if(PROXY_BUILD_MODULES)
+    include(cmake/proxyModuleTargets.cmake)
+  endif()
+else()
+  # Propagate the variable to the parent project
+  set(proxy_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/include PARENT_SCOPE)
+endif()
+
 # install and export the project. project name - proxy
+
 include(GNUInstallDirs)
+
 install(TARGETS msft_proxy
-        EXPORT proxyConfig)
-install(FILES proxy.h proxy_fmt.h
-        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/proxy)
-install(EXPORT proxyConfig DESTINATION ${CMAKE_INSTALL_DATADIR}/proxy)
-export(TARGETS msft_proxy FILE proxyConfig.cmake)
+        EXPORT proxyTargets
+        FILE_SET public_headers DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+)
+
+install(EXPORT proxyTargets DESTINATION ${CMAKE_INSTALL_DATADIR}/proxy)
+export(TARGETS msft_proxy FILE proxyTargets.cmake)
+
 include(CMakePackageConfigHelpers)
-write_basic_package_version_file(proxyConfigVersion.cmake
+configure_package_config_file(
+  cmake/proxyConfig.cmake.in
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake/proxyConfig.cmake
+  INSTALL_DESTINATION ${CMAKE_INSTALL_DATADIR}/proxy
+  PATH_VARS CMAKE_INSTALL_INCLUDEDIR
+)
+
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(cmake/proxyConfigVersion.cmake
                                  COMPATIBILITY SameMajorVersion
                                  ARCH_INDEPENDENT)
-install(FILES ${CMAKE_CURRENT_BINARY_DIR}/proxyConfigVersion.cmake
-        DESTINATION ${CMAKE_INSTALL_DATADIR}/proxy)
+
+install(
+  FILES 
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/proxyConfig.cmake
+    ${CMAKE_CURRENT_BINARY_DIR}/cmake/proxyConfigVersion.cmake
+  DESTINATION ${CMAKE_INSTALL_DATADIR}/proxy
+)
 
 # build tests if BUILD_TESTING is ON
-include(CTest)
 if (BUILD_TESTING)
+  include(CTest)
   add_subdirectory(tests)
   add_subdirectory(benchmarks)
   add_subdirectory(docs)

README.md

@@ -27,7 +27,21 @@ Please refer to the [Proxy's Frequently Asked Questions](https://microsoft.githu
 
 ## Quick Start
 
-"Proxy" is a header-only C++20 library. To use the library, make sure your compiler meets the [minimum requirements](#compiler-req) and just include the header file [proxy.h](https://github.com/microsoft/proxy/blob/main/proxy.h) in your source code. Alternatively, you can install the library via [vcpkg](https://learn.microsoft.com/en-us/vcpkg/get_started/overview) or [conan](https://conan.io/), by searching for "proxy" (see [vcpkg.io](https://vcpkg.io/en/package/proxy) and [conan.io](https://conan.io/center/recipes/proxy)).
+"Proxy" is a header-only C++20 library. To use the library, make sure your compiler meets the [minimum requirements](#compiler-req) and just put the [proxy](https://github.com/microsoft/proxy/tree/main/include/proxy) directory in your project's include directory. Alternatively, you can install the library via:
+
+- [vcpkg](https://learn.microsoft.com/en-us/vcpkg/get_started/overview): [proxy port on vcpkg.io](https://vcpkg.io/en/package/proxy)
+- [conan](https://conan.io/): [proxy recipe on conan.io](https://conan.io/center/recipes/proxy)
+- [CPM](https://github.com/cpm-cmake/CPM.cmake) / CMake [FetchContent_Declare](https://cmake.org/cmake/help/latest/module/FetchContent.html):
+
+    ```cmake
+    CPMAddPackage(
+      NAME proxy
+      GIT_TAG 4.0.0 # or above
+      GIT_REPOSITORY https://github.com/microsoft/proxy.git
+    )
+
+    target_link_libraries(main PRIVATE msft_proxy)
+    ```
 
 ### Hello World
 
@@ -38,7 +52,7 @@ Let's get started with the following "Hello World" example ([run](https://godbol
 #include <iostream>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Formattable : pro::facade_builder
     ::support<pro::skills::format>
@@ -62,7 +76,7 @@ Here is a step-by-step explanation:
 - `#include <format>`: For [`std::format`](https://en.cppreference.com/w/cpp/utility/format/format).
 - `#include <iostream>`: For [`std::cout`](https://en.cppreference.com/w/cpp/io/cout).
 - `#include <string>`: For [`std::string`](https://en.cppreference.com/w/cpp/string/basic_string).
-- `#include "proxy.h"`: For the "Proxy" library. Most of the facilities of the library are defined in namespace `pro`. If the library is consumed via [vcpkg](https://learn.microsoft.com/en-us/vcpkg/get_started/overview) or [conan](https://conan.io/), this line should be changed into `#include <proxy/proxy.h>`.
+- `#include <proxy/proxy.h>`: For the "Proxy" library. Most of the facilities of the library are defined in namespace `pro`.
 - `struct Formattable : pro::facade_builder ... ::build {}`: Defines a facade type `Formattable`. The term "facade", formally defined as the [*ProFacade* requirements](https://microsoft.github.io/proxy/docs/ProFacade.html), is how the "Proxy" library models runtime abstraction. Specifically,
   - [`pro::facade_builder`](https://microsoft.github.io/proxy/docs/basic_facade_builder.html): Provides capability to build a facade type at compile-time.
   - [`support_format`](https://microsoft.github.io/proxy/docs/basic_facade_builder/support_format.html): Specifies the capability of formatting (via [standard formatting functions](https://en.cppreference.com/w/cpp/utility/format)).
@@ -78,6 +92,8 @@ Here is a step-by-step explanation:
 - `std::format("p3 = {:.2f}\n", *p3)`: Formats `*p3` as "3.14" as per the [standard format specification](https://en.cppreference.com/w/cpp/utility/format/spec) with no surprises.
 - When `main` returns, `p2` and `p3` will destroy the underlying objects, while `p1` does nothing because it holds a raw pointer that does not have ownership of the underlying `std::string`.
 
+Note: If you prefer the library to be consumed as a (C++20) module, refer to [C++20 Modules support](https://microsoft.github.io/proxy/docs/cpp20_modules_support.html).
+
 ### Hello World (Stream Version)
 
 In the previous "Hello Word" example, we demonstrated how `proxy` could manage different types of objects and be formatted with `std::format`. While `std::format` is not the only option to print objects in C++, can we simply make `proxy` work with `std::cout`? The answer is "yes". The previous example is equivalent to the following implementation ([run](https://godbolt.org/z/q1b14WGff)):
@@ -87,7 +103,7 @@ In the previous "Hello Word" example, we demonstrated how `proxy` could manage d
 #include <iostream>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Streamable : pro::facade_builder
     ::add_convention<pro::operator_dispatch<"<<", true>, std::ostream&(std::ostream& out) const>
@@ -108,10 +124,10 @@ int main() {
 
 Here is a step-by-step explanation:
 
-- `#include <iostream>`: For [`std::setprecision`](https://en.cppreference.com/w/cpp/io/manip/setprecision).
+- `#include <iomanip>`: For [`std::setprecision`](https://en.cppreference.com/w/cpp/io/manip/setprecision).
 - `#include <iostream>`: For [`std::cout`](https://en.cppreference.com/w/cpp/io/cout).
 - `#include <string>`: For [`std::string`](https://en.cppreference.com/w/cpp/string/basic_string).
-- `#include "proxy.h"`: For the "Proxy" library.
+- `#include <proxy/proxy.h>`: For the "Proxy" library.
 - `struct Streamable : pro::facade_builder ... ::build {}`: Defines a facade type `Streamable`. Specifically,
   - [`pro::facade_builder`](https://microsoft.github.io/proxy/docs/basic_facade_builder.html): Gets prepared to build another facade.
   - [`add_convention`](https://microsoft.github.io/proxy/docs/basic_facade_builder/add_convention.html): Adds a generalized "calling convention", defined by a "dispatch" and several "overloads", to the build context.
@@ -142,7 +158,7 @@ Note that some facilities are provided as macro, because C++ templates today do
 #include <iostream>
 #include <sstream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_MEM_DISPATCH(MemDraw, Draw);
 PRO_DEF_MEM_DISPATCH(MemArea, Area);
@@ -187,7 +203,7 @@ Here is a step-by-step explanation:
 
 - `#include <iostream>`: For [`std::cout`](https://en.cppreference.com/w/cpp/io/cout).
 - `#include <sstream>`: For [`std::stringstream`](https://en.cppreference.com/w/cpp/io/basic_stringstream).
-- `#include "proxy.h"`: For the "Proxy" library.
+- `#include <proxy/proxy.h>`: For the "Proxy" library.
 - [`PRO_DEF_MEM_DISPATCH`](https://microsoft.github.io/proxy/docs/PRO_DEF_MEM_DISPATCH.html)`(MemDraw, Draw)`: Defines a dispatch type `MemDraw` for expressions of calling member function `Draw`.
 - [`PRO_DEF_MEM_DISPATCH`](https://microsoft.github.io/proxy/docs/PRO_DEF_MEM_DISPATCH.html)`(MemArea, Area)`: Defines a dispatch type `MemArea` for expressions of calling member function `Area`.
 - `struct Drawable : pro::facade_builder ... ::build {}`: Defines a facade type `Drawable`. Specifically,

benchmarks/proxy_invocation_benchmark_context.h

@@ -4,7 +4,7 @@
 #include <memory>
 #include <vector>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_MEM_DISPATCH(MemFun, Fun);
 

benchmarks/proxy_management_benchmark.cpp

@@ -9,7 +9,7 @@
 
 #include <benchmark/benchmark.h>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 namespace {
 

cmake/proxyConfig.cmake.in

@@ -0,0 +1,5 @@
+@PACKAGE_INIT@
+
+include("${CMAKE_CURRENT_LIST_DIR}/proxyTargets.cmake")
+
+set(proxy_INCLUDE_DIR "@PACKAGE_CMAKE_INSTALL_INCLUDEDIR@")

cmake/proxyModuleTargets.cmake

@@ -0,0 +1,25 @@
+
+if(NOT DEFINED proxy_INCLUDE_DIR)
+    message(FATAL_ERROR "proxy_INCLUDE_DIR must be defined to use this script.")
+endif()
+
+message(STATUS "Declaring `msft_proxy::module` target for include path ${proxy_INCLUDE_DIR}")
+
+add_library(msft_proxy_module)
+set_target_properties(
+  msft_proxy_module
+  PROPERTIES
+    SYSTEM TRUE
+    EXCLUDE_FROM_ALL TRUE
+)
+
+add_library(msft_proxy::module ALIAS msft_proxy_module)
+target_sources(msft_proxy_module PUBLIC
+  FILE_SET CXX_MODULES
+  BASE_DIRS ${proxy_INCLUDE_DIR}
+  FILES
+    ${proxy_INCLUDE_DIR}/proxy/proxy.ixx
+)
+target_compile_features(msft_proxy_module PUBLIC cxx_std_20)
+target_link_libraries(msft_proxy_module PUBLIC msft_proxy)
+

docs/PRO_DEF_FREE_AS_MEM_DISPATCH.md

@@ -51,7 +51,7 @@ struct dispatch_name {
 #include <iostream>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_FREE_AS_MEM_DISPATCH(FreeToString, std::to_string, ToString);
 

docs/PRO_DEF_FREE_DISPATCH.md

@@ -49,7 +49,7 @@ struct dispatch_name {
 #include <iostream>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_FREE_DISPATCH(FreeToString, std::to_string, ToString);
 

docs/PRO_DEF_MEM_DISPATCH.md

@@ -52,7 +52,7 @@ struct dispatch_name {
 #include <string>
 #include <vector>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_MEM_DISPATCH(MemAt, at);
 

docs/access_proxy.md

@@ -33,7 +33,7 @@ Similar to [`proxy_invoke`](proxy_invoke.md), this function can be used to imple
 #include <iostream>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_FREE_DISPATCH(FreeToString, std::to_string, ToString);
 

docs/allocate_proxy.md

@@ -41,7 +41,7 @@ The implementation of `allocated-ptr` may vary depending on the definition of `F
 ```cpp
 #include <array>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 // By default, the maximum pointer size defined by pro::facade_builder
 // is 2 * sizeof(void*). This value can be overridden by `restrict_layout`.

docs/allocate_proxy_shared.md

@@ -42,7 +42,7 @@ The implementation of `strong-compact-ptr` may vary depending on the definition
 #include <iostream>
 #include <memory_resource>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct RttiAware : pro::facade_builder
     ::support_copy<pro::constraint_level::nothrow>