docs, support renamed features in other PRs

Author: aaronsky

docs/usage.md

@@ -5,6 +5,7 @@
     - [`rules_xcodeproj_generator`](#rules_xcodeproj_generator)
     - [`rules_xcodeproj_indexbuild`](#rules_xcodeproj_indexbuild)
     - [`rules_xcodeproj_swiftuipreviews`](#rules_xcodeproj_swiftuipreviews)
+    - [`rules_xcodeproj_coverage`](#rules_xcodeproj_coverage)
   - [Project-level configs](#project-level-configs)
   - [Extra config flags](#extra-config-flags)
   - [`.bazelrc` files](#bazelrc-files)
@@ -119,6 +120,31 @@ SwiftUI Preview build.
 You shouldn’t need to adjust this config. The default config applies the needed
 build adjusting flags.
 
+### `rules_xcodeproj_coverage`
+
+The `rules_xcodeproj_coverage` config is used when building the project tests
+inside of Xcode when code coverage is enabled. This config sets the needed
+features inside apple_support and rules_swift to generate coverage data with
+absolute paths to sources so Xcode can map them correctly.
+
+By default, code coverage is **disabled** for test actions of schemes. You can
+enable code coverage in Xcode by setting `code_coverage = True` on an
+[`xcschemes.test_options`](/doc/bazel.md#xcschemes.test_options-code_coverage)
+declaration, or by enabling the "Gather coverage data" option in the scheme editor.
+
+> [!WARNING]
+> Enabling code coverage will cause tests to be built for coverage, which is a
+> distinct configuration mode from normal test builds. For building in Xcode
+> in particular, this results in build outputs that are inherently non-hermetic
+> as they contain absolute paths to source files. This will result in poor
+> cache hit rates for these builds. This does not impact `coverage` builds run
+> using the [command-line API](#command-line-api) or normal `bazel test` runs.
+>
+> It is recommended to only enable code coverage inside of Xcode when actively
+> using it for development, and to use tool sets like
+> [lcov](https://registry.bazel.build/modules/lcov) to produce coverage reports
+> from normal `bazel` test runs.
+
 ## Project-level configs
 
 Each `xcodeproj` can specify a set of configs which inherit from the

xcodeproj/internal/templates/xcodeproj.bazelrc

@@ -91,7 +91,7 @@ common:rules_xcodeproj_coverage --config=rules_xcodeproj
 
 # Enable features that allow for building for instrumentation.
 #
-# Of particular note are the (swift./)coverage_prefix_map_canonical_non_hermetic
+# Of particular note are the (swift./)_coverage_prefix_map_absolute_sources_non_hermetic
 # features, which remap the execroot during the build as the absolute, canonical path
 # to the source root.
 #
@@ -100,11 +100,11 @@ common:rules_xcodeproj_coverage --config=rules_xcodeproj
 # coverage).
 common:rules_xcodeproj_coverage --features=coverage
 common:rules_xcodeproj_coverage --features=llvm_coverage_map_format
-common:rules_xcodeproj_coverage --features=coverage_prefix_map_canonical_non_hermetic
+common:rules_xcodeproj_coverage --features=_coverage_prefix_map_absolute_sources_non_hermetic
 common:rules_xcodeproj_coverage --features=swift.coverage
-common:rules_xcodeproj_coverage --features=swift.coverage_prefix_map_canonical_non_hermetic
+common:rules_xcodeproj_coverage --features=swift._coverage_prefix_map_absolute_sources_non_hermetic
 
-# Disable features that interfere with (swift./)coverage_prefix_map_canonical_non_hermetic
+# Disable features that interfere with (swift./)_coverage_prefix_map_absolute_sources_non_hermetic
 common:rules_xcodeproj_coverage --features=-coverage_prefix_map
 common:rules_xcodeproj_coverage --features=-file_prefix_map
 common:rules_xcodeproj_coverage --features=-swift.coverage_prefix_map