Support precise debug module tracking

README.md

@@ -109,6 +109,9 @@ encountered first on your `PATH`.
 To make cacheable builds work correctly with debugging see
 [this doc](doc/debuggable_remote_swift.md).
 
+For explicit module builds, see
+[debugging with explicit modules](doc/explicit_modules.md#debugging).
+
 ## Swift Package Manager Support
 
 To download, build, and reference external Swift packages as Bazel

doc/explicit_modules.md

@@ -40,6 +40,22 @@ would still be embedded in the swiftmodule files. This means debugging
 in `lldb` with explicit modules would not work with cached swiftmodules
 and is therefore disabled.
 
+### Module tracking in debug info
+
+With Swift 6.4 / Xcode 27 and newer, `swift.debug_module_path` is enabled by default
+for Xcode toolchains.
+In this mode the compiler writes the `.swiftmodule` path into each object file's
+debug information using `-debug-module-path`. Each explicit module also
+records its dependencies. LLDB uses these paths to find the module files
+it needs for expression evaluation, replacing the previous `-add_ast_path`
+or module-wrapping mechanism. See
+[Module Tracking in Swift Debug Info](https://www.swift.org/blog/module-tracking-in-debug-info/)
+for more details.
+
+Expression evaluation still requires the `.swiftmodule` and `.pcm`
+files at their original or remapped locations. Your build or debugger
+integration must make these files available locally.
+
 ## Using explicit dependencies
 
 By default we implicitly add all possible precompiled modules to the

swift/internal/debugging.bzl

@@ -25,8 +25,12 @@ load(
 load(
     ":feature_names.bzl",
     "SWIFT_FEATURE_DBG",
+    "SWIFT_FEATURE_DEBUG_MODULE_PATH",
     "SWIFT_FEATURE_FASTBUILD",
+    "SWIFT_FEATURE_FULL_DEBUG_INFO",
     "SWIFT_FEATURE_NO_EMBED_DEBUG_MODULE",
+    "SWIFT_FEATURE_USE_C_MODULES",
+    "SWIFT_FEATURE_USE_EXPLICIT_SWIFT_MODULE_MAP",
 )
 load(":features.bzl", "is_feature_enabled")
 
@@ -123,9 +127,36 @@ def should_embed_swiftmodule_for_debugging(
         not is_feature_enabled(
             feature_configuration = feature_configuration,
             feature_name = SWIFT_FEATURE_NO_EMBED_DEBUG_MODULE,
-        )
+        ) and
+        not uses_precise_debug_module_tracking(feature_configuration)
     )
 
+def uses_precise_debug_module_tracking(feature_configuration):
+    """Returns whether precise module tracking is enabled for this build.
+
+    Args:
+        feature_configuration: The Swift feature configuration.
+
+    Returns:
+        True for builds with debug info and all required module features enabled.
+    """
+
+    has_debug_info = _is_debugging(feature_configuration) or is_feature_enabled(
+        feature_configuration = feature_configuration,
+        feature_name = SWIFT_FEATURE_FULL_DEBUG_INFO,
+    )
+    return has_debug_info and all([
+        is_feature_enabled(
+            feature_configuration = feature_configuration,
+            feature_name = feature_name,
+        )
+        for feature_name in [
+            SWIFT_FEATURE_DEBUG_MODULE_PATH,
+            SWIFT_FEATURE_USE_C_MODULES,
+            SWIFT_FEATURE_USE_EXPLICIT_SWIFT_MODULE_MAP,
+        ]
+    ])
+
 def _is_debugging(feature_configuration):
     """Returns `True` if the current compilation mode produces debug info.
 

swift/internal/feature_names.bzl

@@ -224,6 +224,14 @@ SWIFT_FEATURE_ADD_DEFAULT_PRECOMPILED_MODULES = "swift.add_default_precompiled_m
 # using a JSON file instead of `-I` search paths.
 SWIFT_FEATURE_USE_EXPLICIT_SWIFT_MODULE_MAP = "swift.use_explicit_swift_module_map"
 
+# If enabled together with explicit modules and debug info, object
+# compilations record their own `.swiftmodule` path in debug info instead of
+# embedding modules at link time.
+# https://www.swift.org/blog/module-tracking-in-debug-info/
+# Requires Swift 6.4 or newer for the compiler and debugger support.
+# Enabled by default for Xcode 27 and newer.
+SWIFT_FEATURE_DEBUG_MODULE_PATH = "swift.debug_module_path"
+
 # If enabled, Swift compilation actions will use the same global Clang module
 # cache used by Objective-C compilation actions. This can be disabled because
 # under some circumstances Clang module cache corruption can cause the Swift

swift/toolchains/config/compile_config.bzl

@@ -41,6 +41,7 @@ load(
     "SWIFT_FEATURE_COVERAGE",
     "SWIFT_FEATURE_COVERAGE_PREFIX_MAP",
     "SWIFT_FEATURE_DBG",
+    "SWIFT_FEATURE_DEBUG_MODULE_PATH",
     "SWIFT_FEATURE_DEBUG_PREFIX_MAP",
     "SWIFT_FEATURE_DECLARE_SWIFTSOURCEINFO",
     "SWIFT_FEATURE_DISABLE_AVAILABILITY_CHECKING",
@@ -274,6 +275,21 @@ def compile_action_configs(
             configurators = [_constant_value_extraction_configurator],
         ),
 
+        # Record this object's own module path in debugging configurations.
+        ActionConfigInfo(
+            actions = [SWIFT_ACTION_COMPILE],
+            configurators = [lambda prerequisites, args: args.add(
+                "-debug-module-path",
+                prerequisites.swiftmodule_file,
+            )],
+            features = [[
+                SWIFT_FEATURE_DEBUG_MODULE_PATH,
+                SWIFT_FEATURE_USE_C_MODULES,
+                SWIFT_FEATURE_USE_EXPLICIT_SWIFT_MODULE_MAP,
+                compilation_mode,
+            ] for compilation_mode in [SWIFT_FEATURE_DBG, SWIFT_FEATURE_FASTBUILD, SWIFT_FEATURE_FULL_DEBUG_INFO]],
+        ),
+
         # Link Time Optimization (LTO).
         ActionConfigInfo(
             actions = all_compile_action_names(),

swift/toolchains/xcode_swift_toolchain.bzl

@@ -51,6 +51,7 @@ load(
     "SWIFT_FEATURE_ADD_DEFAULT_PRECOMPILED_MODULES",
     "SWIFT_FEATURE_COVERAGE",
     "SWIFT_FEATURE_COVERAGE_PREFIX_MAP",
+    "SWIFT_FEATURE_DEBUG_MODULE_PATH",
     "SWIFT_FEATURE_DEBUG_PREFIX_MAP",
     "SWIFT_FEATURE_DISABLE_SWIFT_SANDBOX",
     "SWIFT_FEATURE_FILE_PREFIX_MAP",
@@ -864,6 +865,9 @@ def _xcode_swift_toolchain_impl(ctx):
     if _is_xcode_at_least_version(xcode_config, "26.4"):
         requested_features.append(SWIFT_FEATURE__SUPPORTS_HERMETIC_SWIFTMODULE)
 
+    if _is_xcode_at_least_version(xcode_config, "27.0"):
+        requested_features.append(SWIFT_FEATURE_DEBUG_MODULE_PATH)
+
     # Xcode toolchains always support DEVELOPER_DIR
     requested_features.append(SWIFT_FEATURE__SUPPORTS_DEVELOPER_DIR)