Clarify documentation about Concepts
--
PiperOrigin-RevId: 147491785
MOS_MIGRATED_REVID=147491785
diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md
index ca5d69d..2d5430f 100644
--- a/site/versions/master/docs/skylark/concepts.md
+++ b/site/versions/master/docs/skylark/concepts.md
@@ -4,6 +4,7 @@
---
# Overview
+
## Loading an extension
Extensions are files with the `.bzl` extension. Use the `load` statement to
@@ -35,23 +36,28 @@
load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
```
-Symbols starting with `_` are private and cannot be loaded from other files.
-Visibility doesn't affect loading (yet): you don't need to use `exports_files`
-to make a `.bzl` file visible.
+In a `.bzl` file, symbols starting with `_` are private and cannot be loaded
+from another file. Visibility doesn't affect loading (yet): you don't need to
+use `exports_files` to make a `.bzl` file visible.
## Macros and rules
-A [macro](macros.md) is a function that instantiates rules. The
-function is evaluated as soon as the BUILD file is read. Bazel has little
-information about macros: if your macro generates a `genrule`, Bazel will behave
-as if you wrote the `genrule`. As a result, `bazel query` will only list the
-generated `genrule`.
+A [macro](macros.md) is a function that instantiates rules. It is useful when a
+BUILD file is getting too repetitive or too complex, as it allows you to reuse
+some code. The function is evaluated as soon as the BUILD file is read. After
+the evaluation of the BUILD file, Bazel has little information about macros: if
+your macro generates a `genrule`, Bazel will behave as if you wrote the
+`genrule`. As a result, `bazel query` will only list the generated `genrule`.
-A [rule](rules.md) is more powerful than a macro, as it can access
-Bazel internals and have full control over what is going on. It may for example
-pass information to other rules.
+A [rule](rules.md) is more powerful than a macro. It can access Bazel internals
+and have full control over what is going on. It may for example pass information
+to other rules.
-If a macro becomes complex, it is often a good idea to make it a rule.
+If you want to reuse simple logic, start with a macro. If a macro becomes
+complex, it is often a good idea to make it a rule. Support for a new language
+is typically done with a rule. Rules are for advanced users: we expect that most
+people will never have to write one, they will only load and call existing
+rules.
## Evaluation model
@@ -59,17 +65,20 @@
* **Loading phase**. First, we load and evaluate all extensions and all BUILD
files that are needed for the build. The execution of the BUILD files simply
- instantiates rules. This is where macros are evaluated.
+ instantiates rules (each time a rule is called, it gets added to a graph).
+ This is where macros are evaluated.
* **Analysis phase**. The code of the rules is executed (their `implementation`
function), and actions are instantiated. An action describes how to generate
a set of outputs from a set of inputs, e.g. "run gcc on hello.c and get
hello.o". It is important to note that we have to list explicitly which
- files will be generated before executing the actual commands.
+ files will be generated before executing the actual commands. In other words,
+ the analysis phase takes the graph generated by the loading phase and
+ generates an action graph.
* **Execution phase**. Actions are executed, when at least one of their outputs is
required. If a file is missing or if a command fails to generate one output,
- the build fails. Tests are run during this phase, as they are actions.
+ the build fails. Tests are also run during this phase.
Bazel uses parallelism to read, parse and evaluate the `.bzl` files and `BUILD`
files. A file is read at most once per build and the result of the evaluation is
@@ -77,6 +86,11 @@
statements) have been resolved. By design, loading a `.bzl` file has no visible
side-effect, it only defines values and functions.
+Bazel tries to be clever: it uses dependency analysis to know which files must
+be loaded, which rules must be analyzed, and which actions must be executed. For
+example, if a rule generates actions that we don't need for the current build,
+they will not be executed.
+
## Syntax
The extension language (Skylark) is a superset of the
