Update glossary to clarify rule-related terminology

- Rewrite "artifact" and "tree artifact" a little
- Rewrite "aspect-on-aspect" a little
- Add entry for "attribute"
- Flesh out "provider" a little bit, especially to distinguish between providers and provider instances
- Rewrite "rule". Emphasize its behavior from a BUILD author's perspective rather than starting with a brain-dump of the jargon a rule author needs to know. Include a brief description of its interaction with the three build phases, since rules are *the* central concept in Bazel. Add sheepish note that rules and and rule targets are sometimes conflated.
- Add separate entry for "rule target". We commonly use this term in other documentation, and a user might be confused whether we're talking about a "rule" or a "target".
- Rewrite "target" to emphasize its role in the build graph and prioritize discussion of rule targets and file targets.

Follow-up work will restructure the information in visibility.md, and add content for .bzl visibility.

Work toward #11261.

PiperOrigin-RevId: 481238358
Change-Id: I728e1be134e1619e1f3710328a111c45c06732e0

site/en/reference/glossary.md

@@ -52,10 +52,13 @@ implementations are evaluated.
 ### Artifact {:#artifact}
 
 A source file or a generated file. Can also be a directory of files, known as
-"tree artifacts". Tree artifacts are black boxes to Bazel: Bazel does not treat
-the files in tree artifacts as individual artifacts and thus cannot reference
-them directly as action inputs / outputs. An artifact can be an input to
-multiple actions, but must only be generated by at most one action.
+[tree artifacts](#tree-artifact).
+
+An artifact may be an input to multiple actions, but must only be generated by
+at most one action.
+
+An artifact that corresponds to a [file target](#target) can be addressed by a
+label.
 
 ### Aspect {:#aspect}
 
@@ -71,12 +74,22 @@ metadata for IDEs, and create actions for linting.
 
 ### Aspect-on-aspect {:#aspect-on-aspect}
 
-An aspect composition mechanism, where aspects can be applied on other aspects.
-For an aspect A to inspect aspect B, aspect A must declare the *providers* it
-needs from aspect B (with the `required_aspect_providers` attribute), and aspect
-B must declare the providers it returns (with the `provides` attribute). For
-example, this can be used by IDE aspects to generate files using information
-also generated by aspects, like the `java_proto_library` aspect.
+A composition mechanism whereby aspects can be applied to the results
+of other aspects. For example, an aspect that generates information for use by
+IDEs can be applied on top of an aspect that generates `.java` files from a
+proto.
+
+For an aspect `A` to apply on top of aspect `B`, the [providers](#provider) that
+`B` advertises in its [`provides`](/rules/lib/globals#aspect.provides) attribute
+must match what `A` declares it wants in its [`required_aspect_providers`](/rules/lib/globals#aspect.required_aspect_providers)
+attribute.
+
+### Attribute {:#attribute}
+
+A parameter to a [rule](#rule), used to express per-target build information.
+Examples include `srcs`, `deps`, and `copts`, which respectively declare a
+target's source files, dependencies, and custom compiler options. The particular
+attributes available for a given target depend on its rule type.
 
 ### .bazelrc {:#bazelrc}
 
@@ -367,7 +380,7 @@ thus forming a package hierarchy.
 
 ### Package group {:#package-group}
 
-A [target](#target) representing a set of packages. Often used in visibility
+A [target](#target) representing a set of packages. Often used in `visibility`
 attribute values.
 
 ### Platform {:#platform}
@@ -378,10 +391,16 @@ and the machines targets are built for ("target platforms").
 
 ### Provider {:#provider}
 
-A set of information passed from a rule [target](#target) to other rule targets.
-Usually contains information like: compiler options, transitive source files,
-transitive output files, and build metadata. Frequently used in conjunction with
-[depsets](#depset).
+A schema describing a unit of information to pass between
+[rule targets](#rule-target) along dependency relationships. Typically this
+contains information like compiler options, transitive source or output files,
+and build metadata. Frequently used in conjunction with [depsets](#depset) to
+efficiently store accumulated transitive data. An example of a built-in provider
+is `DefaultInfo`.
+
+Note: The object holding specific data for a given rule target is
+referred to as a "provider instance", although sometimes this is conflated with
+"provider".
 
 **See also:** [Provider documentation](/rules/rules#providers)
 
@@ -421,15 +440,32 @@ or environment. Note that this does not necessarily imply that the outputs are
 
 ### Rule {:#rule}
 
-A function implementation that registers a series of [actions](#action) to be
-performed on input [artifacts](#artifact) to produce a set of output artifacts.
-Rules can read values from *attributes* as inputs (such as deps, testonly, name).
-Rule targets also produce and pass along information that may be useful to other
-rule targets in the form of [providers](#provider) (such as `DefaultInfo`
-provider).
+A schema for defining [rule targets](#rule-target) in a `BUILD` file, such as
+`cc_library`. From the perspective of a `BUILD` file author, a rule consists of
+a set of [attributes](#attributes) and black box logic. The logic tells the
+rule target how to produce output [artifacts](#artifact) and pass information to
+other rule targets. From the perspective of `.bzl` authors, rules are the
+primary way to extend Bazel to support new programming languages and
+environments.
+
+Rules are instantiated to produce rule targets in the
+[loading phase](#loading-phase). In the [analysis phase](#analysis-phase) rule
+targets communicate information to their downstream dependencies in the form of
+[providers](#provider), and register [actions](#action) describing how to
+generate their output artifacts. These actions are run in the [execution
+phase](#execution-phase).
+
+Note: Historically the term "rule" has been used to refer to a rule target.
+This usage was inherited from tools like Make, but causes confusion and should
+be avoided for Bazel.
 
 **See also:** [Rules documentation](/rules/rules)
 
+### Rule target {:#rule-target}
+
+A [target](#target) that is an instance of a rule. Contrasts with file targets
+and package groups. Not to be confused with [rule](#rule).
+
 ### Runfiles {:#runfiles}
 
 The runtime dependencies of an executable [target](#target). Most commonly, the
@@ -438,7 +474,7 @@ data dependencies of the test. Before the invocation of the executable (during
 bazel test), Bazel prepares the tree of runfiles alongside the test executable
 according to their source directory structure.
 
-**See also:** [Runfiles documentation](/rules/rules#runfiles)   
+**See also:** [Runfiles documentation](/rules/rules#runfiles)
 
 ### Sandboxing {:#sandboxing}
 
@@ -488,13 +524,24 @@ command.
 
 ### Target {:#target}
 
-A buildable unit. Can be a [rule](#rule) target, file target, or a [package
-group](#package-group). Rule targets are instantiated from rule declarations in
-[`BUILD` files](#build-file). Depending on the rule implementation, rule targets
-can also be testable or runnable. Every file used in `BUILD` files is a file
-target. Targets can depend on other targets via attributes (most commonly but
-not necessarily `deps`). A [configured target](#configured-target) is a pair of
-target and [build configuration](#configuration).
+An object that is defined in a [`BUILD` file](#build-file) and identified by a
+[label](#label). Targets represent the buildable units of a workspace from
+the perspective of the end user.
+
+A target that is declared by instantiating a [rule](#rule) is called a [rule
+target](#rule-target). Depending on the rule, these may be runnable (like
+`cc_binary`) or testable (like `cc_test`). Rule targets typically depend on
+other targets via their [attributes](#attribute) (such as `deps`); these
+dependencies form the basis of the [target graph](#target-graph).
+
+Aside from rule targets, there are also file targets and [package group](#package-group)
+targets. File targets correspond to [artifacts](#artifact) that are referenced
+within a `BUILD` file.
+
+Targets are discovered during the [loading phase](#loading-phase). During the
+[analysis phase](#analysis-phase), targets are associated with [build
+configurations](#configuration) to form [configured
+targets](#configured-target).
 
 ### Target graph {:#target-graph}
 
@@ -552,7 +599,9 @@ compiled for ARM and x86 using split transitions in a single build.
 
 ### Tree artifact {:#tree-artifact}
 
-See [Artifact](#artifact).
+An [artifact](#artifact) that represents a collection of files. Since these
+files are not themselves artifacts, an [action](#action) operating on them must
+instead register the tree artifact as its input or output.
 
 ### Visibility {:#visibility}