microsoft · mingxwa · Jun 7, 2025 · Jun 6, 2025
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1,17 +1,40 @@
 cmake_minimum_required(VERSION 3.10)
 
-project(msft_proxy VERSION 3.3.0 LANGUAGES CXX)
+project(msft_proxy VERSION 3.4.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()
+
+target_sources(msft_proxy
+  INTERFACE
+    FILE_SET public_headers
+    TYPE HEADERS 
+    BASE_DIRS include
+    FILES
+      include/proxy/proxy.h
+)
+
 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>)
 
+set(proxy_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include")
+if(NOT PROJECT_IS_TOP_LEVEL)
+  set(proxy_INCLUDE_DIR "${proxy_INCLUDE_DIR}" PARENT_SCOPE)
+endif()
+
 # install and export the project. project name - proxy
 include(GNUInstallDirs)
 install(TARGETS msft_proxy
-        EXPORT proxyConfig)
-install(FILES proxy.h
-        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/proxy)
+        EXPORT proxyConfig
+        FILE_SET public_headers DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+)
 install(EXPORT proxyConfig DESTINATION ${CMAKE_INSTALL_DATADIR}/proxy)
 export(TARGETS msft_proxy FILE proxyConfig.cmake)
 include(CMakePackageConfigHelpers)
@@ -22,8 +45,8 @@ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/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)

diff --git a/README.md b/README.md
@@ -27,7 +27,20 @@ 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 3.4.0 # or above
+      GIT_REPOSITORY https://github.com/microsoft/proxy.git
+    )
+    target_link_libraries(main PRIVATE msft_proxy)
+    ```
 
 ### Hello World
 
@@ -38,7 +51,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_format
@@ -62,7 +75,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)).
@@ -87,7 +100,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 +121,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 +155,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 +200,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,

diff --git a/benchmarks/proxy_invocation_benchmark_context.h b/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);
 

diff --git a/benchmarks/proxy_management_benchmark.cpp b/benchmarks/proxy_management_benchmark.cpp
@@ -9,7 +9,7 @@
 
 #include <benchmark/benchmark.h>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 namespace {
 

diff --git a/docs/PRO_DEF_FREE_AS_MEM_DISPATCH.md b/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);
 

diff --git a/docs/PRO_DEF_FREE_DISPATCH.md b/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);
 

diff --git a/docs/PRO_DEF_MEM_DISPATCH.md b/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);
 

diff --git a/docs/PRO_DEF_WEAK_DISPATCH.md b/docs/PRO_DEF_WEAK_DISPATCH.md
@@ -39,7 +39,7 @@ In [Java](https://docs.oracle.com/javase/specs/jls/se23/html/jls-9.html#jls-9.4-
 #include <string>
 #include <vector>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct NotImplemented {
   explicit NotImplemented(auto&&...) { throw std::runtime_error{ "Not implemented!" }; }

diff --git a/docs/access_proxy.md b/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);
 

diff --git a/docs/allocate_proxy.md b/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`.

diff --git a/docs/allocate_proxy_shared.md b/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>

diff --git a/docs/basic_facade_builder.md b/docs/basic_facade_builder.md
@@ -115,7 +115,7 @@ struct CopyableCallable : pro::facade_builder
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 template <class... Overloads>
 struct MovableCallable : pro::facade_builder

diff --git a/docs/basic_facade_builder/add_convention.md b/docs/basic_facade_builder/add_convention.md
@@ -38,7 +38,7 @@ Adding duplicated combinations of some dispatch type and overload type is well-d
 #include <memory>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_FREE_DISPATCH(FreeToString, std::to_string, ToString);
 

diff --git a/docs/basic_facade_builder/add_facade.md b/docs/basic_facade_builder/add_facade.md
@@ -17,7 +17,7 @@ Adding a facade type that contains duplicated convention or reflection types alr
 #include <iostream>
 #include <unordered_map>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 PRO_DEF_MEM_DISPATCH(MemSize, size);
 PRO_DEF_MEM_DISPATCH(MemAt, at);

diff --git a/docs/basic_facade_builder/add_reflection.md b/docs/basic_facade_builder/add_reflection.md
@@ -35,7 +35,7 @@ Adding duplicate reflection types is well-defined, whether done directly via `ad
 #include <array>
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct LayoutReflector {
  public:

diff --git a/docs/basic_facade_builder/build.md b/docs/basic_facade_builder/build.md
@@ -57,7 +57,7 @@ The default values of the fields of [`proxiable_ptr_constraints`](../proxiable_p
 ```cpp
 #include <type_traits>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct DefaultBase : pro::facade_builder
     ::build {};

diff --git a/docs/basic_facade_builder/restrict_layout.md b/docs/basic_facade_builder/restrict_layout.md
@@ -18,7 +18,7 @@ If no layout restriction is applied before specifying [`build`](build.md), the d
 #include <array>
 #include <memory>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct DefaultFacade : pro::facade_builder::build {};
 

diff --git a/docs/basic_facade_builder/support_copy.md b/docs/basic_facade_builder/support_copy.md
@@ -16,7 +16,7 @@ If no copyability support is applied before specifying [`build`](build.md), the
 ```cpp
 #include <memory>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Movable : pro::facade_builder::build {};
 

diff --git a/docs/basic_facade_builder/support_destruction.md b/docs/basic_facade_builder/support_destruction.md
@@ -16,7 +16,7 @@ If no destructibility support is applied before specifying [`build`](build.md),
 ```cpp
 #include <type_traits>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Movable : pro::facade_builder::build {};
 

diff --git a/docs/basic_facade_builder/support_format.md b/docs/basic_facade_builder/support_format.md
@@ -16,7 +16,7 @@ The member types `support_format` and `support_wformat` of `basic_facade_builder
 #include <format>
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Formattable : pro::facade_builder
     ::support_format

diff --git a/docs/basic_facade_builder/support_relocation.md b/docs/basic_facade_builder/support_relocation.md
@@ -16,7 +16,7 @@ If no relocatability support is applied before specifying [`build`](build.md), t
 ```cpp
 #include <memory>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Movable : pro::facade_builder::build {};
 

diff --git a/docs/basic_facade_builder/support_rtti.md b/docs/basic_facade_builder/support_rtti.md
@@ -22,7 +22,7 @@ The member types `support_rtti`, `support_indirect_rtti` and `support_direct_rtt
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct RttiAware : pro::facade_builder
     ::support_rtti

diff --git a/docs/basic_facade_builder/support_rtti/proxy_cast.md b/docs/basic_facade_builder/support_rtti/proxy_cast.md
@@ -61,7 +61,7 @@ These functions are not visible to ordinary [unqualified](https://en.cppreferenc
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct RttiAware : pro::facade_builder
     ::support_rtti

diff --git a/docs/basic_facade_builder/support_rtti/proxy_typeid.md b/docs/basic_facade_builder/support_rtti/proxy_typeid.md
@@ -20,7 +20,7 @@ These functions are not visible to ordinary [unqualified](https://en.cppreferenc
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct RttiAware : pro::facade_builder
     ::support_rtti

diff --git a/docs/basic_facade_builder/support_view.md b/docs/basic_facade_builder/support_view.md
@@ -17,7 +17,7 @@ Let `p` be a value of type `proxy<F>`, `ptr` be the contained value of `p` (if a
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct RttiAware : pro::facade_builder
     ::support_rtti

diff --git a/docs/basic_facade_builder/support_weak.md b/docs/basic_facade_builder/support_weak.md
@@ -17,7 +17,7 @@ Let `p` be a value of type `proxy<F>`, `ptr` of type `P` be the contained value
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Formattable : pro::facade_builder
     ::support_format

diff --git a/docs/explicit_conversion_dispatch.md b/docs/explicit_conversion_dispatch.md
@@ -26,7 +26,7 @@ Class `explicit_conversion_dispatch` models a [dispatch](ProDispatch.md) type fo
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct IntConvertible : pro::facade_builder
     ::add_convention<pro::conversion_dispatch, int() const>

diff --git a/docs/facade_aware_overload_t.md b/docs/facade_aware_overload_t.md
@@ -16,7 +16,7 @@ Class template `facade_aware_overload_t<O>` specifies a facade-aware overload te
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 template <class F>
 using BinaryOverload = pro::proxy<F>(const pro::proxy_indirect_accessor<F>& rhs) const;

diff --git a/docs/implicit_conversion_dispatch.md b/docs/implicit_conversion_dispatch.md
@@ -24,7 +24,7 @@ Class `implicit_conversion_dispatch` models a [dispatch](ProDispatch.md) type fo
 ```cpp
 #include <iostream>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Runnable : pro::facade_builder
     ::add_convention<pro::operator_dispatch<"()">, void()>

diff --git a/docs/inplace_proxiable_target.md b/docs/inplace_proxiable_target.md
@@ -12,7 +12,7 @@ See [`make_proxy_inplace`](make_proxy_inplace.md) for the definition of the expo
 ```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`.

diff --git a/docs/make_proxy.md b/docs/make_proxy.md
@@ -50,7 +50,7 @@ Throws any exception thrown by allocation and the constructor of `T`.
 #include <iostream>
 #include <string>
 
-#include "proxy.h"
+#include <proxy/proxy.h>
 
 struct Printable : pro::facade_builder
     ::add_convention<pro::operator_dispatch<"<<", true>, std::ostream&(std::ostream&) const>