commit f9abcf06d651226734ca2d1a885b558ff2afee48
author Googler <noreply@google.com> Mon Nov 23 08:28:58 2020 -0800
committer Copybara-Service <copybara-worker@google.com> Mon Nov 23 08:31:19 2020 -0800
tree 28a5e4afe377fcc743dfebdfcca1074af2276b8c
parent 10e44727c210307e3457fc5f3a6d9aeac241fc61

Improve the "Rules" documentation section

Makes the following changes:

* Mention providers earlier in the introduction. They're a more central concept than the current organization makes that out to be. Put a little more detail in the "how a rule works" example to get at the idea that rules return general-purpose and rule-specific providers.

* Use "bzl" instead of "python" for fenced code-blocks.

* For the section on attributes, split out sections on "dependency attributes" and "output attributes". Moving the latter further down because, as the current text points out, it's "relatively rare".

* Have the section on "dependency attributes" mention the conventional names and usage for "srcs", "deps", and "data". That idiom is worth calling out explicitly. "deps" and "data" are even mentioned in the "common attributes" section as attributes that are very frequently (but not implicitly) added to build rules (https://docs.bazel.build/versions/master/be/common-definitions.html#common-attributes).

* In the section on implicit dependencies, change the wording to treat "implicit dependency" as a more general-purpose technical term than a piece of idiosyncratic jargon. Our usage here isn't unusual, so I think we can be clearer by saying that label attributes with a default _create_ implicit dependencies, and explaining why "[the dependency] is implicit because" as opposed to "the name [implicit dependency] comes from the fact".

* The section on output attributes previously said that such attributes "do not create a dependency relationship between targets", which is incorrect. Instead, clarify that the dependency relationship is in the opposite direction, and also that such attributes define an output file target instead of referencing one. Also mention that "out" and "outs" is a typical name.

* In the section on outputs, link to the (newly split-off) section on output attributes. Also mention that (and how) the names of outputs are often based on the target name.

* Also in that section, make it clearer that/why rules should provide default outputs where possible. Even if that output is some sort of intermediate state that end-users aren't expected to use, doing that ensured "blaze build :target" actually performs that action and reproduces build failures.

* In the section on runfiles, stop treating runfiles associated with a library as a special case. Every language rule implementer shouldn't have to invent an extra rule-specific provider for runfiles. This allows providing much simpler advice about how runfiles should be populated: Take files from stuff that's supposed to provide arbitrary files for runfiles (i.e. data), merge runfiles from everything that's a runtime dependency (including data). The idea of a "subtool" shouldn't be a special case, if you have an attribute that provides an executable used at runtime, that's a runtime dependency so you need to merge in its runfiles. The fact that the binary you depend on might call _yet another_ binary from runfiles is an implementation detail of that target. The consumer shouldn't need to know if that's the case or not.

* Merge the sections about how a rule implementation function knows the path of stuff in runfiles, and how a binary might be able to tell where the runfiles are (it should guess that it's next door, but then tell the binaries it calls because only the first binary's guess will be right and any subsequent binaries' guesses would be wrong).

* In the section on deprecated runfiles features, mention merging in dependencies' runfiles.

* Also in the section on deprecated runfiles features, mention how the distinction between `default_runfiles` and `data_runfiles` was used in the past, at least in some cases. That gives a little context about why that's not necessary.

* In the section on "executable rules", mention that `executable` also ends up in default outputs and runfiles.

* In the section on runfiles, also mention that and link to the section on "executable rules", adding a shorter section anchor for the latter section.

* Removes a bit about ctx.expand_location, which isn't closely-related to the typical use of runfiles.

RELNOTES: None.
PiperOrigin-RevId: 343856494