Adjust docs

bazelbuild · Dec 21, 2022 · 442aac5 · 442aac5
1 parent da0f1f7
commit 442aac5
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -72,10 +72,10 @@ bazel run @build_bazel_rules_swift//tools/dump_toolchains
 **Linux hosts:** At this time, Bazel uses whichever `swift` executable is
 encountered first on your `PATH`.
 
-## Supporting remote builds
+## Supporting debugging
 
-To make remote builds work correctly with debugging and general
-reproducibility see [this doc](doc/debuggable_remote_swift.md)
+To make cacheable builds work correctly with debugging see
+[this doc](doc/debuggable_remote_swift.md).
 
 ## Swift Package Manager Support
 

diff --git a/doc/debuggable_remote_swift.md b/doc/debuggable_remote_swift.md
@@ -1,6 +1,6 @@
-# Debuggable Remotely Built Swift
+# Debugging Cacheable Swift Modules
 
-This is a guide to using remotely built Swift modules in local debug builds.
+This is a guide to enable debugging of cacheable Swift modules in local debug builds.
 
 At the time of writing, `lldb` depends on debugging options embedded in `.swiftmodule` files. These options include paths that are only valid on the build host. For local builds, this all just works, but for remote builds, it doesn't.
 
@@ -13,15 +13,13 @@ Globally disabling debugging options makes those `.swiftmodule`s usable on any m
 
 An lldb bug has been filed here: https://bugs.swift.org/browse/SR-11485
 
-### Disable Debugging Options Globally
-
-To globally disable debugging options, use the `swift.cacheable_swiftmodules` feature in rules_swift. For example, your `.bazelrc` could look like this:
+> **Note**
+>
+> If you don't care about cache misses, instead of following this guide you can instead disable the `swift.cacheable_swiftmodules` feature: `--features=-swift.cacheable_swiftmodules`. This is not recommended though if you use a remote cache.
 
-```
-build --features=swift.cacheable_swiftmodules
-```
+### Disable Debugging Options Globally
 
-What this does is ensure all modules are built explicitly with `-no-serialize-debugging-options`. It has to be explicit because `swiftc` enables `-serialize-debugging-options` in some cases.
+To globally disable debugging options, use the `swift.cacheable_swiftmodules` feature, which is enabled by default, in rules_swift. What this does is ensure all modules are built explicitly with `-no-serialize-debugging-options`. It has to be explicit because `swiftc` enables `-serialize-debugging-options` in some cases.
 
 ### Add Debug Build Config