WINRT_IMPL_SKIP_INCLUDES is finally gone

Author: DefaultRyan

.github/instructions/modules.instructions.md

@@ -31,9 +31,10 @@ targets (or manually for non-NuGet projects).
 
 ### .g.h (component base template)
 - `#ifdef WINRT_MODULE`: emits `#include "winrt/base_macros.h"` for macros,
-  conditional `import std;`, `import winrt;`, locally sets `WINRT_IMPL_SKIP_INCLUDES`
-- Always includes component's own headers (platform SDK deps skipped by the
-  local `WINRT_IMPL_SKIP_INCLUDES`, but cross-namespace component deps are NOT)
+  conditional `import std;`, `import winrt;`
+- Always includes component's own headers. Platform deps are skipped by
+  per-namespace `WINRT_MODULE_NS_*` guards; component cross-namespace deps
+  are included normally.
 
 ### .g.cpp (factory + optimized constructors)
 - Always emits the `winrt_make_*` factory function
@@ -42,42 +43,47 @@ targets (or manually for non-NuGet projects).
 
 ## Macro Scoping
 
-Three macros with distinct scopes control module behavior:
+Two project-level macros and one set of per-namespace macros control behavior:
 
 - `WINRT_BUILD_MODULE` — Defined by cppwinrt inside winrt.ixx's global module
-  fragment. Controls base.h skip in version assert. Also `#undef`s
-  `WINRT_IMPL_SKIP_INCLUDES` so cross-namespace deps work inside the ixx.
+  fragment. Controls base.h skip in version assert. Does NOT include
+  `winrt_module_namespaces.h` (inside the ixx, all deps must resolve).
   Never set by users or NuGet targets.
 - `WINRT_MODULE` — Defined project-wide by NuGet targets. Controls .g.h/.g.cpp
-  behavior AND version assert base.h skip. Does NOT suppress cross-namespace
-  deps between component namespaces.
-- `WINRT_IMPL_SKIP_INCLUDES` — Set locally inside .g.h files only (under
-  `#ifdef WINRT_MODULE`). Suppresses cross-namespace platform SDK deps that
-  are already in the module. NOT defined project-wide.
+  behavior, version assert base.h skip, AND triggers inclusion of
+  `winrt_module_namespaces.h` for per-namespace guards.
+- `WINRT_MODULE_NS_*` — Per-namespace macros (e.g. `WINRT_MODULE_NS_Windows_Foundation`)
+  defined in the generated `winrt_module_namespaces.h`. Each cross-namespace
+  `#include` dep is guarded by `#ifndef WINRT_MODULE_NS_<namespace>`. Only
+  namespaces in the module are skipped; component and other deps always resolve.
 
-## WINRT_IMPL_SKIP_INCLUDES
+## Per-Namespace Include Guards
 
-Generated namespace headers guard cross-namespace `#include` dependencies with:
+Generated namespace headers use per-namespace guards for cross-namespace deps:
 ```cpp
-#ifndef WINRT_IMPL_SKIP_INCLUDES
-#include "winrt/impl/OtherNamespace.0.h"
+#ifndef WINRT_MODULE_NS_Windows_Foundation
+#include "winrt/impl/Windows.Foundation.0.h"
 #endif
 ```
 
-The version assert at the top of each namespace header checks all three macros:
+The version assert at the top of each namespace header:
 ```cpp
-#if defined(WINRT_BUILD_MODULE) || defined(WINRT_MODULE) || defined(WINRT_IMPL_SKIP_INCLUDES)
+#if defined(WINRT_BUILD_MODULE) || defined(WINRT_MODULE)
 #include "winrt/base_macros.h"
-#else
+#endif
+#if defined(WINRT_MODULE) && !defined(WINRT_BUILD_MODULE)
+#include "winrt/winrt_module_namespaces.h"
+#endif
+#if !defined(WINRT_BUILD_MODULE) && !defined(WINRT_MODULE)
 #include "winrt/base.h"
 #endif
 ```
 
-- Cross-namespace dependencies (other namespaces' impl headers): GUARDED by
-  `WINRT_IMPL_SKIP_INCLUDES` (`write_depends_guarded` / `write_root_include_guarded`)
-- Self-namespace dependencies (own impl headers): NOT guarded
+- Cross-namespace dependencies: GUARDED by `WINRT_MODULE_NS_*`
+  (`write_depends_guarded` / `write_root_include_guarded`)
+- Self-namespace dependencies: NOT guarded
   (`write_depends` / `write_root_include`)
-- base.h include in version assert: GUARDED by all three macros
+- base.h include: GUARDED by `WINRT_BUILD_MODULE || WINRT_MODULE`
 
 ## Test Project Architecture
 

cppwinrt/file_writers.h

@@ -60,10 +60,10 @@ import std;
     }
 
     // Lightweight header containing only the preprocessor macros needed by
-    // generated namespace headers. Used when WINRT_IMPL_SKIP_INCLUDES is
-    // defined (i.e., consuming component headers after 'import winrt;').
-    // Macros don't cross module boundaries, so this provides the macros
-    // that base.h would normally supply.
+    // generated namespace headers. Used when WINRT_MODULE or WINRT_BUILD_MODULE
+    // is defined (i.e., consuming or building the winrt module). Macros don't
+    // cross module boundaries, so this provides the macros that base.h would
+    // normally supply.
     static void write_base_macros_h()
     {
         writer w;

docs/modules-internals.md

@@ -10,7 +10,7 @@ them, and the interactions between the various moving pieces.
 - [winrt.ixx Generation](#winrtixx-generation)
 - [Split Standard Library Includes](#split-standard-library-includes)
 - [base_macros.h: Why Macros Need Special Handling](#base_macrosh-why-macros-need-special-handling)
-- [WINRT_IMPL_SKIP_INCLUDES: Guarded Cross-Namespace Includes](#winrt_impl_skip_includes-guarded-cross-namespace-includes)
+- [Per-Namespace Include Guards (WINRT_MODULE_NS_*)](#per-namespace-include-guards-winrt_module_ns)
 - [WINRT_EXPORT on Extern Handlers](#winrt_export-on-extern-handlers)
 - [The -module Flag: Component Code Generation](#the--module-flag-component-code-generation)
 - [The Combined-ixx Approach](#the-combined-ixx-approach)
@@ -133,52 +133,66 @@ import winrt;
 // ... template code using WINRT_IMPL_EMPTY_BASES etc.
 ```
 
-## WINRT_IMPL_SKIP_INCLUDES: Guarded Cross-Namespace Includes
+## Per-Namespace Include Guards (WINRT_MODULE_NS_*)
 
-**Problem**: Inside generated `.g.h` files, after `import winrt;`, the
-component's own projection headers are included. Those headers have
-cross-namespace `#include` deps for platform SDK types (e.g.,
-`Windows.Foundation`) that are already available from the module. Re-including
-platform headers works (MSVC handles the re-declarations gracefully), but
-skipping them in this narrow scope avoids redundant processing.
+**Problem**: After `import winrt;`, consumers textually `#include` component
+and reference projection headers. Those headers have cross-namespace `#include`
+deps. Platform namespace deps (already in the module) must be skipped to avoid
+MSVC redeclaration errors on `inline constexpr` variable template specializations
+like `name_v`. But component-to-component cross-namespace deps must NOT be
+skipped, or multi-namespace components break.
 
-**Solution**: Generated `.g.h` files set `WINRT_IMPL_SKIP_INCLUDES` locally
-(under `#ifdef WINRT_MODULE`) before including the component's own headers.
-Generated namespace headers wrap their cross-namespace deps with guards:
+**Solution**: cppwinrt generates `winrt/winrt_module_namespaces.h` alongside
+`winrt.ixx`. This header defines one macro per namespace in the module:
 
 ```cpp
-// In generated Windows.Foundation.h:
-#ifndef WINRT_IMPL_SKIP_INCLUDES
-#include "winrt/base.h"
+// Generated winrt/winrt_module_namespaces.h:
+#pragma once
+#define WINRT_MODULE_NS_Windows_Foundation
+#define WINRT_MODULE_NS_Windows_Foundation_Collections
+// ... one per namespace in the module
+```
+
+Generated namespace headers use per-namespace guards for cross-namespace deps:
+
+```cpp
+// In generated TestModuleComponent.h:
+#ifndef WINRT_MODULE_NS_Windows_Foundation
+#include "winrt/impl/Windows.Foundation.2.h"
 #endif
-// ... (cross-namespace deps guarded)
-#include "winrt/impl/Windows.Foundation.2.h"   // self-namespace: NOT guarded
+#include "winrt/impl/TestModuleComponent.Widgets.2.h"  // NOT guarded (not in module)
+#include "winrt/impl/TestModuleComponent.2.h"          // self-namespace: never guarded
 ```
 
-**Critical scoping**: `WINRT_IMPL_SKIP_INCLUDES` is NOT defined project-wide.
-It is only defined locally inside `.g.h` files. This ensures that consumer
-source files can `#include <winrt/MyComponent.Widgets.h>` after `import winrt;`
-and the cross-namespace deps between component namespaces resolve normally.
-
-**WINRT_MODULE vs WINRT_IMPL_SKIP_INCLUDES in the version assert**: The version
-assert at the top of every namespace header checks `WINRT_BUILD_MODULE`,
-`WINRT_MODULE`, or `WINRT_IMPL_SKIP_INCLUDES` to decide whether to skip
-`#include "base.h"` and use `base_macros.h` instead. This three-way check
-covers: (a) inside winrt.ixx, (b) consumer source files, (c) inside .g.h files.
-
-**WINRT_BUILD_MODULE in winrt.ixx**: The ixx defines `WINRT_BUILD_MODULE`
-and `#undef`s `WINRT_IMPL_SKIP_INCLUDES` in its global module fragment. This
-ensures the version assert uses `base_macros.h` (since base.h is already
-explicitly included), but cross-namespace deps are included normally so
-namespace headers can reference each other's types inside the ixx.
-
-**Implementation**: `write_root_include_guarded()` in `type_writers.h` wraps the
-`#include` with `#ifndef WINRT_IMPL_SKIP_INCLUDES`. Used by:
+When `WINRT_MODULE` is defined, the version assert at the top of each namespace
+header includes `winrt_module_namespaces.h`, making the `WINRT_MODULE_NS_*`
+macros available for the guards. When `WINRT_BUILD_MODULE` is defined (inside
+winrt.ixx), `winrt_module_namespaces.h` is NOT included, so all cross-namespace
+deps resolve normally — the ixx needs them to build the module.
+
+**Implementation**: `write_root_include_guarded()` in `type_writers.h` extracts
+the namespace from the include path and emits `#ifndef WINRT_MODULE_NS_<ns>`.
+Used by:
 - `write_depends_guarded()` for cross-namespace impl includes
 - `write_parent_depends()` for parent namespace includes
 
-`write_version_assert()` in `code_writers.h` checks `WINRT_BUILD_MODULE ||
-WINRT_MODULE || WINRT_IMPL_SKIP_INCLUDES` for the base.h skip.
+`write_version_assert()` in `code_writers.h`:
+```cpp
+#if defined(WINRT_BUILD_MODULE) || defined(WINRT_MODULE)
+#include "winrt/base_macros.h"
+#endif
+#if defined(WINRT_MODULE) && !defined(WINRT_BUILD_MODULE)
+#include "winrt/winrt_module_namespaces.h"
+#endif
+#if !defined(WINRT_BUILD_MODULE) && !defined(WINRT_MODULE)
+#include "winrt/base.h"
+#endif
+```
+
+**winrt_module_namespaces.h generation**: In `main.cpp`, emitted alongside
+`winrt.ixx` when `settings.base` is true and `settings.component` is false.
+This prevents component projections (which may also use `-base`) from generating
+a stale version that would mask the module builder's file on the include path.
 
 The component's own impl headers are always included (via `write_depends()`,
 unguarded) since they contain the component-specific type definitions.
@@ -241,14 +255,15 @@ import winrt;
 import std;
 #endif
 import winrt;
-#define WINRT_IMPL_SKIP_INCLUDES
 #endif
 #include "winrt/test_component.h"  // always emitted
 ```
 
-When `WINRT_MODULE` is defined, `WINRT_IMPL_SKIP_INCLUDES` causes the component
-headers to skip cross-namespace platform `#include` deps (already in the module).
-When not defined, the headers pull in `base.h` transitively as normal.
+When `WINRT_MODULE` is defined, the version assert in each included header
+pulls in `winrt_module_namespaces.h`, which provides per-namespace
+`WINRT_MODULE_NS_*` macros. Platform namespace deps are skipped by these
+guards; component cross-namespace deps are included normally.
+When `WINRT_MODULE` is not defined, the headers pull in `base.h` transitively.
 
 ### Toaster.g.cpp (factory + optional optimized constructors)
 
@@ -387,34 +402,41 @@ User sets CppWinRTModuleBuild=true (or CppWinRTModuleConsume=true) + BuildStlMod
     ├── NuGet targets define WINRT_IMPORT_STD on all ClCompile items
     │
     ▼
-winrt.ixx compilation:
+winrt.ixx compilation (WINRT_BUILD_MODULE defined in global module fragment):
     module;
+    #define WINRT_BUILD_MODULE
     <intrin.h, version, directxmath.h>         ← platform includes (base_includes)
     <algorithm, array, string, coroutine, ...> ← std library includes (base_std_includes)
     export module winrt;
     #define WINRT_EXPORT export
-    #include "winrt/base.h"                    ← base.h (pragma once)
+    #include "winrt/base.h"                    ← base.h (explicit include)
     #include "winrt/Windows.Foundation.h"      ← SDK types + specializations
     ...                                        ← winrt::impl is exported
+    Also generates: winrt/winrt_module_namespaces.h (per-namespace macros)
 
-Consumer .cpp compilation:
+Consumer .cpp compilation (WINRT_MODULE defined by NuGet targets):
     #include "pch.h"                           ← PCH (no winrt/ headers)
     import std;                                ← std module (optional, needs BuildStlModules)
     import winrt;                              ← winrt module (SDK types + exported impl)
+    #include "winrt/MyComponent.h"             ← reference projection header
+      → version assert includes winrt_module_namespaces.h (via WINRT_MODULE)
+      → platform deps guarded by WINRT_MODULE_NS_* (skipped)
+      → component cross-namespace deps NOT guarded (included normally)
 
 Component .g.h (WINRT_MODULE defined by NuGet targets):
     #include "winrt/base_macros.h"             ← macros only (WINRT_EXPORT etc.)
     #ifdef WINRT_IMPORT_STD
     import std;                                ← conditional on WINRT_IMPORT_STD
     #endif
     import winrt;                              ← SDK types + exported impl templates
-    #define WINRT_IMPL_SKIP_INCLUDES           ← skip SDK #include deps
     #include "winrt/MyComponent.h"             ← component projection (specializes impl)
+      → platform deps skipped by WINRT_MODULE_NS_* guards
+      → cross-namespace component deps included normally
 
 module.g.cpp compilation:
     #include "pch.h"                           ← PCH preserved
     #ifdef WINRT_IMPORT_STD / import std;      ← conditional
-    import winrt;                              ← from -module code gen
+    import winrt;                              ← module import
     void* winrt_make_MyComponent_Toaster()     ← factory function
     bool __stdcall ..._can_unload_now()        ← DLL entry points
 ```