Add a Troubleshoot section for rules

RELNOTES: None.
PiperOrigin-RevId: 179200616

1 files changed, 31 insertions, 0 deletions

diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index eb05b06ad7..0af307f525 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -627,3 +627,34 @@ _example_test = rule(
  ...
 )
 ```
+
+## Troubleshooting
+
+### Why is the action never executed?
+
+Bazel executes an action only when at least one of its outputs are requested. If
+the target is built directly, make sure the output you need is in the [default
+outputs](#default-outputs).
+
+When the target is used as a dependency, check which providers are used and consumed.
+
+### Why is the implementation function not executed?
+
+Bazel analyzes only the targets that are requested for the build. You should
+either build the target, or build something that depends on the target.
+
+### A file is missing during execution
+
+When you create an action, you need to specify all the inputs. Please
+double-check that you didn't forget anything.
+
+If a binary requires files at runtime, such as dynamic libraries or data files,
+you may need to [specify the runfiles](#runfiles).
+
+### How to choose which files are shown in the output of `bazel build`?
+
+Use the `DefaultInfo` provider to [set the default outputs](#default-outputs).
+
+### How to run a program in the analysis phase?
+
+It is not possible.