Expand visibility documentation
- Expand documentation of exports_files
- Fix the visibility page (the header was missing).
- Documents https://github.com/bazelbuild/bazel/issues/4157
RELNOTES: None.
PiperOrigin-RevId: 311405680
diff --git a/site/docs/visibility.md b/site/docs/visibility.md
index d16a7b7..d6494cb 100644
--- a/site/docs/visibility.md
+++ b/site/docs/visibility.md
@@ -1,3 +1,8 @@
+---
+layout: documentation
+title: Visibility
+---
+
# Visibility
Visibility controls whether a target can be used by other packages. It is an
@@ -14,7 +19,7 @@
* `["//visibility:public"]`: Anyone can use this rule.
* `["//visibility:private"]`: Only rules in this package can use this rule.
- Rules in `javatests/foo/bar` can always use rules in `java/foo/bar`.
+
* `["//some/package:__pkg__", "//other/package:__pkg__"]`: Only rules in
`some/package/BUILD` and `other/package/BUILD` have access to this rule.
Note that sub-packages do not have access to the rule; for example,
@@ -113,6 +118,28 @@
specification applies. Otherwise, the file is public (the `default_visibility`
is ignored).
+When possible, prefer exposing a library or another type of rule instead of a
+source file. For example, declare a `java_library` instead of exporting a
+`.java` file. It's good form for a target to only directly include sources in
+its own package.
+
+### Example
+
+File `//frobber/data/BUILD`:
+
+```python
+exports_files(["readme.txt"])
+```
+
+File `//frobber/bin/BUILD`:
+
+```python
+cc_binary(
+ name = "my-program",
+ data = ["//frobber/data:readme.txt"],
+)
+```
+
### Legacy behavior
If the flag [`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225)
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
index 36891b2..341ac71 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
@@ -258,7 +258,10 @@
<p>
The BUILD file for a package may only refer directly to source files belonging
to another package if they are explicitly exported with an
- <pre>exports_files()</pre> statement.
+ <code>exports_files()</code> statement. Read more about
+ <a href="../visibility.md#visibility-of-a-file">visibility of files</a>.
+</p>
+ <p>
As a legacy behaviour, also files mentioned as input to a rule are exported
with the default visibility until the flag
<a href="https://github.com/bazelbuild/bazel/issues/10225"><code>--incompatible_no_implicit_file_export</code></a>
