Simplify visibility docs
Correct legacy uses of "rule" terminology to "target". Eliminate extra example verbosity.
Follow-up work to #8982.
RELNOTES: None
PiperOrigin-RevId: 311414362
diff --git a/site/docs/visibility.md b/site/docs/visibility.md
index d6494cb..e122ca5 100644
--- a/site/docs/visibility.md
+++ b/site/docs/visibility.md
@@ -2,79 +2,64 @@
layout: documentation
title: Visibility
---
+All rule targets have a `visibility` attribute that takes a list of labels. One
+target is visible to another if they are in the same package, or if they are
+granted visibility by one of the labels.
-# Visibility
+Each label has one of the following forms:
-Visibility controls whether a target can be used by other packages. It is an
-important tool to structure the code when a codebase grows: it lets developers
-distinguish between implementation details and libraries other people can depend
-on.
+* `"//visibility:public"`: Anyone can use this target. (May not be combined
+ with any other specification.)
-If you need to disable the visibility check (for example when experimenting),
-use `--check_visibility=false`.
+* `"//visibility:private"`: Only targets in this package can use this
+ target. (May not be combined with any other specification.)
-## Visibility labels
+* `"//foo/bar:__pkg__"`: Grants access to targets defined in `//foo/bar` (but
+ not its subpackages). Here, `__pkg__` is a special piece of syntax
+ representing all of the targets in a package.
-There are five forms a visibility label can take:
+* `"//foo/bar:__subpackages__"`: Grants access to targets defined in
+ `//foo/bar`, or any of its direct or indirect subpackages. Again,
+ `__subpackages__` is special syntax.
-* `["//visibility:public"]`: Anyone can use this rule.
-* `["//visibility:private"]`: Only rules in this package can use this rule.
+* `"//foo/bar:my_package_group"`: Grants access to all of the packages named
+ by the given [package group](be/functions.html#package_group). This can be
+ used to allow access to an entire subtree, such as `//myproj/...`.
-* `["//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,
- `//some/package/foo:bar` or `//other/package/testing:bla` wouldn't have
- access. `__pkg__` is a special target and must be used verbatim. It
- represents all of the rules in the package.
-* `["//project:__subpackages__", "//other:__subpackages__"]`: Only rules in
- packages `project` or `other` or in one of their sub-packages have access to
- this rule. For example, `//project:rule`, `//project/library:lib` or
- `//other/testing/internal:munge` are allowed to depend on this rule (but not
- `//independent:evil`)
-* `["//some/package:my_package_group"]`: A
- [package group](be/functions.html#package_group) is a named set of package
- names. Package groups can also grant access rights to entire subtrees,
- e.g.`//myproj/...`.
+For example, if `//some/package:mytarget` has its `visibility` set to
+`[":__subpackages__", "//tests:__pkg__"]`, then it could be used by any target
+that is part of the `//some/package/...` source tree, as well as targets defined
+in `//tests/BUILD`, but not by targets defined in `//tests/integration/BUILD`.
-The visibility specifications of `//visibility:public` and
-`//visibility:private` can not be combined with any other visibility
-specifications.
+## Visibility of a rule target
-A visibility specification may contain a combination of package labels (i.e.
-`//foo:__pkg__`) and `package_group`s.
-
-## Visibility of a rule
-
-If a rule does specify the visibility attribute, that specification overrides
-any [`default_visibility`](be/functions.html#package.default_visibility)
-attribute of the [`package`](functions.html#package) statement in the BUILD
-file containing the rule.
-
-Otherwise, if a rule does not specify the visibility attribute, the
-default_visibility of the package is used.
-
-Otherwise, if the default_visibility for the package is not specified,
-`//visibility:private` is used.
+If a rule target does not set the `visibility` attribute, its visibility is
+given by the
+[`default_visibility`](be/functions.html#package.default_visibility) that was
+specified in the [`package`](functions.html#package) statement of the target's
+BUILD file. If there is no such `default_visibility` declaration, the visibility
+is `//visibility:private`.
### Example
File `//frobber/bin/BUILD`:
```python
-# This rule is visible to everyone
+# This target is visible to everyone
cc_binary(
name = "executable",
visibility = ["//visibility:public"],
deps = [":library"],
)
-# This rule is visible only to rules declared in the same package
+# This target is visible only to targets declared in the same package
cc_library(
name = "library",
- visibility = ["//visibility:private"],
+ # No visibility -- defaults to private since no
+ # package(default_visibility = ...) was used.
)
-# This rule is visible to rules in package //object and //noun
+# This target is visible to targets in package //object and //noun
cc_library(
name = "subject",
visibility = [
@@ -84,7 +69,7 @@
)
# See package group "//frobber:friends" (below) for who can
-# access this rule.
+# access this target.
cc_library(
name = "thingy",
visibility = ["//frobber:friends"],
@@ -94,7 +79,7 @@
File `//frobber/BUILD`:
```python
-# This is the package group declaration to which rule
+# This is the package group declaration to which target
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
@@ -108,20 +93,20 @@
)
```
-## Visibility of a file
+## Visibility of a file target
-By default, files are visible only from the same package. To make a file
+By default, file targets are visible only from the same package. To make a file
accessible from another package, use
[`exports_files`](be/functions.html#exports_files).
-If the call to `exports_files` rule does specify the visibility attribute, that
-specification applies. Otherwise, the file is public (the `default_visibility`
+If the call to `exports_files` specifies the visibility attribute, that
+visibility 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.
+`.java` file. It's good form for a rule target to only directly include sources
+in its own package.
### Example
@@ -145,8 +130,8 @@
If the flag [`--incompatible_no_implicit_file_export`](https://github.com/bazelbuild/bazel/issues/10225)
is not set, a legacy behavior applies instead.
-With the legacy behavior, files used by at least one rule in the file are
-implicitly exported using the `default_visibility` specification. See the
+With the legacy behavior, files used by at least one rule target in the package
+are implicitly exported using the `default_visibility` specification. See the
[design proposal](https://github.com/bazelbuild/proposals/blob/master/designs/2019-10-24-file-visibility.md#example-and-description-of-the-problem)
for more details.
