From 42f4adaa8d0f12326fb5e1660140cb4c92e8df51 Mon Sep 17 00:00:00 2001 From: Laurent Le Brun Date: Wed, 22 Jun 2016 14:01:19 +0000 Subject: Remove word "Skylark" from documentation. Text becomes somewhat clearer without using this codename. -- MOS_MIGRATED_REVID=125561237 --- site/docs/skylark/aspects.md | 2 +- site/docs/skylark/concepts.md | 28 ++++++++++++++-------------- site/docs/skylark/index.md | 4 ++-- site/docs/skylark/macros.md | 8 ++++---- site/docs/skylark/repository_rules.md | 6 +++--- site/docs/skylark/rules.md | 6 +++--- 6 files changed, 27 insertions(+), 27 deletions(-) (limited to 'site/docs/skylark') diff --git a/site/docs/skylark/aspects.md b/site/docs/skylark/aspects.md index 29de0eb17c..771dffdd57 100644 --- a/site/docs/skylark/aspects.md +++ b/site/docs/skylark/aspects.md @@ -1,6 +1,6 @@ --- layout: documentation -title: Skylark Aspects +title: Aspects --- # Aspects diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md index fb853e3452..873036e105 100644 --- a/site/docs/skylark/concepts.md +++ b/site/docs/skylark/concepts.md @@ -1,13 +1,13 @@ --- layout: documentation -title: Skylark - Concepts +title: Extensions - Overview --- -# Concepts +# Overview -## Loading a Skylark extension +## Loading an extension -Use the `load` statement to import a symbol from a `.bzl` Skylark -extension. +Extensions are files with the `.bzl` extension. Use the `load` statement to +import a symbol from an extension. ```python load("//build_tools/rules:maprule.bzl", "maprule") @@ -37,20 +37,19 @@ load("/path/to: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: you don't need to use `exports_files` to make -a Skylark file visible. +a `.bzl` file visible. ## Macros and rules -A [macro](macros.md) in Skylark is a function that instantiates rules. The +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 [rule](rules.md) in Skylark is more powerful than a macro, as it can access +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 defined in Skylark will behave in a -similar way as a native rule. +pass information to other rules. If a macro becomes complex, it is often a good idea to make it a rule. @@ -58,7 +57,7 @@ If a macro becomes complex, it is often a good idea to make it a rule. A build consists of three phases. -* **Loading phase**. First, we load and evaluate all Skylark extensions and all BUILD +* **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. @@ -78,10 +77,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. -## Language +## Syntax -Skylark is a superset of the core build language and its syntax is a subset of -Python. +The extension language (sometimes referred as "Skylark") is a superset of the +[Core Build Language](/docs/build-ref.html#core_build_language) +and its syntax is a subset of Python. It is designed to be simple, thread-safe and integrated with the BUILD language. It is not a general-purpose language and most Python features are not included. diff --git a/site/docs/skylark/index.md b/site/docs/skylark/index.md index b72b2183ea..b7d46a56f4 100644 --- a/site/docs/skylark/index.md +++ b/site/docs/skylark/index.md @@ -1,9 +1,9 @@ --- layout: documentation -title: Custom Rules +title: Extensions --- -# Custom rules +# Extensions Skylark is the name of the extension mechanism in Bazel. It lets you add support for new languages and tools by writing [custom build rules](rules.md). You can also compose existing rules into [macros](macros.md). diff --git a/site/docs/skylark/macros.md b/site/docs/skylark/macros.md index 296b6b2a99..4e0b93b0e8 100644 --- a/site/docs/skylark/macros.md +++ b/site/docs/skylark/macros.md @@ -6,10 +6,10 @@ title: Macros ## Macro creation -A macro is a function called from the BUILD file. It can instantiate native -or Skylark rules. Macros don't give additional power, they are just used for -encapsulation and code reuse. By the end of the loading phase, macros don't -exist anymore, and Bazel sees only the set of rules they created. +A macro is a function called from the BUILD file that can instantiate rules. +Macros don't give additional power, they are just used for encapsulation and +code reuse. By the end of the loading phase, macros don't exist anymore, and +Bazel sees only the set of rules they created. Native rules can be instantiated from the `native` module, e.g. diff --git a/site/docs/skylark/repository_rules.md b/site/docs/skylark/repository_rules.md index 98c87a4be7..762069d95d 100644 --- a/site/docs/skylark/repository_rules.md +++ b/site/docs/skylark/repository_rules.md @@ -1,6 +1,6 @@ --- layout: documentation -title: Skylark Repository Rules +title: Repository Rules --- # Repository Rules @@ -16,7 +16,7 @@ specific to the host Bazel is running on. ## Repository Rule creation -In a Skylark extension, use the +In a `.bzl` file, use the [repository_rule](lib/globals.html#repository_rule) function to create a new repository rule and store it in a global variable. @@ -72,7 +72,7 @@ local_repository = repository_rule( For now, we only have one full example of usage of the `repository_rule`: [C++ auto-configured toolchain](https://github.com/bazelbuild/bazel/blob/9116b3e99af2fd31d92c9bb7c37905a1675456c1/tools/cpp/cc_configure.bzl#L288). -This example uses a Skylark repository rule to automatically create the +This example uses a repository rule to automatically create the C++ configuration files for Bazel by looking for the local C++ compiler, the environment and the flags the C++ compiler supports. diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index 826c2521fb..860dce7ff4 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md @@ -1,6 +1,6 @@ --- layout: documentation -title: Skylark Rules +title: Rules --- # Rules @@ -19,7 +19,7 @@ to execute the actions (called _implicit inputs_). ## Rule creation -In a Skylark extension (a .bzl file), use the [rule](lib/globals.html#rule) +In a `.bzl` file, use the [rule](lib/globals.html#rule) function to create a new rule and store it in a global variable: ```python @@ -164,7 +164,7 @@ my_rule = rule( ## Output files A target can declare output files, which must be generated by the target's -actions. There are three ways to create output files in Skylark: +actions. There are three ways to create output files: * If the rule is marked `executable`, it creates an output file of the same name as the rule's. [See example](cookbook.md#outputs-executable) -- cgit v1.2.3