diff options
| -rw-r--r-- | docs/skylark/concepts.md | 60 |
1 files changed, 1 insertions, 59 deletions
diff --git a/docs/skylark/concepts.md b/docs/skylark/concepts.md index 8944b95ffa..a393182434 100644 --- a/docs/skylark/concepts.md +++ b/docs/skylark/concepts.md @@ -1,65 +1,7 @@ Concepts ======== -Loading a Skylark module ------------------------- - -Use the `load` statement to import a symbol from a Skylark module. - -```python -load("/build_tools/rules/maprule", "maprule") -``` - -This code will load the file `build_tools/rules/maprule.bzl` and add the -`maprule` symbol to the environment. This can be used to load new rules, -functions or constants (e.g. a string, a list, etc.). Multiple symbols can be -imported by using additional arguments to the call to `load`. Arguments must -be string literals (no variable) and `load` statements must appear at -top-level, i.e. they cannot be in a function body. - -Visibility doesn't affect loading. You don't need to use `exports_files` -to make a Skylark file visible. - -Symbols starting with `_` are private and cannot be loaded from other files. - -Macros and rules ----------------- - -A [macro](macros.md) in Skylark 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 [rule](rules.md) in Skylark 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 defined in Skylark will behave in a -similar way as a native rule. - -If a macro becomes complex, it is often a good idea to make it a rule. - -Evaluation model ----------------- - -A build consists of three phases. - -* **Loading phase**. First, we load and evaluate all Skylark modules 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. - -* **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. - -* **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. - -Language --------- - +Skylark is the code name of the extension mechanism. Skylark is a superset of the core build language and its syntax is a subset of Python. The following constructs have been added to the core build language: `if` statements, `for` loops, and function definitions. |