diff options
| -rw-r--r-- | site/versions/master/docs/skylark/concepts.md | 44 |
1 files changed, 29 insertions, 15 deletions
diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md index ca5d69db05..2d5430f0f8 100644 --- a/site/versions/master/docs/skylark/concepts.md +++ b/site/versions/master/docs/skylark/concepts.md @@ -4,6 +4,7 @@ title: Extensions - Overview --- # Overview + ## Loading an extension Extensions are files with the `.bzl` extension. Use the `load` statement to @@ -35,23 +36,28 @@ example is perfectly legal (please note when to use quotation marks). 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 @@ A build consists of three phases. * **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 @@ cached and reused. A file is evaluated only once all its dependencies (`load()` 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 |