Add ctx.coverage_instrumented function to Skylark

Skylark already has ctx.configuration.coverage_enabled to determine if coverage data collection is on for an entire run. But that does not reveal which targets specifically are supposed to be instrumented (based on the values of --instrumentation_filer and --instrument_test_targets). This is inefficient for languages which add coverage instrumentation at compile-time, though correct coverage output can still be produced by instrumenting everything and filtering later.

By default, this function returns whether the rule represented by ctx should be instrumented. If a Skylark Target (e.g. from a label or label_list attribute in ctx.attr) is passed to the function, it instead returns whether that Target is a rule whose sources should be instrumented. Rules that directly incorporate source-files from their dependencies before compilation (e.g. header files) may need to know if those source files need to be instrumented when compiled.

Expanded the documentation of instrumented_files to be a more general section on implementing code coverage instrumentation in Skylark.

Also tweaked the code comment and variable names for the version of shouldIncludeLocalSources that takes a TransitiveInfoCollection.

RELNOTES: Add ctx.coverage_instrumented function to Skylark, to indicate whether a specific targets should be instrumented for code coverage data collection.

--
MOS_MIGRATED_REVID=139460989

1 files changed, 33 insertions, 4 deletions

diff --git a/site/versions/master/docs/skylark/rules.md b/site/versions/master/docs/skylark/rules.md
index cc92341398..a93ece56e0 100644
--- a/site/versions/master/docs/skylark/rules.md
+++ b/site/versions/master/docs/skylark/rules.md
@@ -417,11 +417,10 @@ with an error describing the conflict. To fix, you will need to modify your
 any targets using your rule, as well as targets of any kind that depend on those
 targets.
 
-## Instrumented files
+## Code coverage instrumentation
 
-Instrumented files are a set of files used by the coverage command. A rule can
-use the `instrumented_files` provider to provide information about which files
-should be used for measuring coverage.
+A rule can use the `instrumented_files` provider to provide information about
+which files should be measured when code coverage data collection is enabled:
 
 ```python
 def rule_implementation(ctx):
@@ -439,6 +438,36 @@ def rule_implementation(ctx):
       dependency_attributes=["data", "deps"]))
 ```
 
+`ctx.config.coverage_enabled` notes whether coverage data collection is enabled
+for the current run in general (but says nothing about which files specifically
+should be instrumented). If a rule implementation needs to add coverage
+instrumentation at compile-time, it can determine if its sources should be
+instrumented with:
+
+```python
+# Are this rule's sources instrumented?
+if ctx.coverage_instrumented():
+  # Do something to turn on coverage for this compile action
+```
+
+Note that function will always return false if `ctx.config.coverage_enabled` is
+false, so you don't need to check both.
+
+If the rule directly includes sources from its dependencies before compilation
+(e.g. header files), it may also need to turn on compile-time instrumentation
+if the dependencies' sources should be instrumented. In this case, it may
+also be worth checking `ctx.config.coverage_enabled` so you can avoid looping
+over dependencies unnecessarily:
+
+```python
+# Are this rule's sources or any of the sources for its direct dependencies
+# in deps instrumented?
+if ctx.config.coverage_enabled:
+    if (ctx.coverage_instrumented() or
+        any(ctx.coverage_instrumented(dep) for dep in ctx.attr.deps):
+        # Do something to turn on coverage for this compile action
+```
+
 ## Executable rules
 
 An executable rule is a rule that users can run using `bazel run`.