Rename "Skylark" to "Starlark" in documentation.
RELNOTES:
In documentation, we've renamed Skylark into Starlark.
PiperOrigin-RevId: 209142944
diff --git a/site/docs/android-instrumentation-test.md b/site/docs/android-instrumentation-test.md
index c023623..8251db5 100644
--- a/site/docs/android-instrumentation-test.md
+++ b/site/docs/android-instrumentation-test.md
@@ -571,6 +571,6 @@
- Improved external dependency management
- Remote test caching and execution
-We are planning to rewrite the Android rules in [Skylark](https://docs.bazel.build/versions/master/skylark/concepts.html).
+We are planning to rewrite the Android rules in [Starlark](https://docs.bazel.build/versions/master/skylark/concepts.html).
The `android_instrumentation_test` rule will be part of the rewrite, however,
its usage will remain unchanged from the end-user perspective.
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md
index 009b030..33db50e 100644
--- a/site/docs/configurable-attributes.md
+++ b/site/docs/configurable-attributes.md
@@ -15,12 +15,12 @@
* [Multiple Selects](#multiple-selects)
* [OR Chaining](#or-chaining)
* [Custom Error Messages](#custom-error-messages)
-* [Skylark Compatibility](#skylark)
+* [Starlark Compatibility](#starlark)
* [Bazel Query and Cquery](#query)
* [FAQ](#faq)
- * [Why doesn't select() work in Skylark](#skylark-macros-select)
- * [Why does select() always return true in Skylark?](#boolean-select)
- * [Can I read select() like a dict in Skylark?](#inspectable-select)
+ * [Why doesn't select() work in macros](#starlark-macros-select)
+ * [Why does select() always return true?](#boolean-select)
+ * [Can I read select() like a dict?](#inspectable-select)
@@ -143,8 +143,8 @@
`config_setting` semantics are intentionally simple. For example, there's no
direct support for `OR` chaining (although a
-[Skylark convenience function](#or-chaining) provides this). Consider writing
-Skylark macros for complicated flag logic.
+[convenience function](#or-chaining) provides this). Consider writing
+macros for complicated flag logic.
## Defaults
@@ -344,7 +344,7 @@
```
-For more complex expressions, use [Skylark macros](skylark/macros.md):
+For more complex expressions, use [macros](skylark/macros.md):
Before:
@@ -430,7 +430,7 @@
)
```
-or write a [Skylark macro](skylark/macros.md) to do the same thing
+or write a [macro](skylark/macros.md) to do the same thing
automatically.
This approach doesn't work for non-deps attributes (like
@@ -543,15 +543,15 @@
build with an Android or Windows toolchain
```
-## <a name="skylark"></a>Skylark Compatibility
-Skylark is compatible with configurable attributes in limited form.
+## <a name="starlark"></a>Starlark Compatibility
+Starlark is compatible with configurable attributes in limited form.
-Skylark rule implementations receive the *resolved values* of configurable
+Rule implementations receive the *resolved values* of configurable
attributes. For example, given:
```sh
//myproject/BUILD:
-some_skylark_rule(
+some_rule(
name = "my_rule",
some_attr = select({
":foo_mode": [":foo"],
@@ -564,11 +564,11 @@
$ bazel build //myproject/my_rule --define mode=foo
```
-Skylark rule implementation code sees `ctx.attr.some_attr` as `[":foo"]`.
+Rule implementation code sees `ctx.attr.some_attr` as `[":foo"]`.
-Skylark macros can accept `select()` clauses and pass them through to native
+Macros can accept `select()` clauses and pass them through to native
rules. But *they cannot directly manipulate them*. For example, there's no way
-for a Skylark macro to convert
+for a macro to convert
```sh
`select({"foo": "val"}, ...)`
@@ -638,17 +638,17 @@
## FAQ
-## <a name="skylark-macros-select"></a>Why doesn't select() work in Skylark?
-select() *does* work in Skylark! See [Skylark compatibility](#skylark) for
+## <a name="macros-select"></a>Why doesn't select() work in macros?
+select() *does* work in rules! See [Starlark compatibility](#starlark) for
details.
The key issue this question usually means is that select() doesn't work in
-Skylark *macros*. These are different than Skylark *rules*. See the Skylark
+*macros*. These are different than *rules*. See the
documentation on [rules](skylark/rules.html) and [macros](skylark/macros.html)
to understand the difference.
Here's an end-to-end example:
-Define a Skylark rule and macro:
+Define a rule and macro:
```sh
# myproject/defs.bzl:
@@ -660,13 +660,13 @@
allcaps = ctx.attr.my_config_string.upper() # This works fine on all values.
print("My name is " + name + " with custom message: " + allcaps)
-# Skylark rule declaration:
+# Rule declaration:
my_custom_bazel_rule = rule(
implementation = _impl,
attrs = {"my_config_string": attr.string()}
)
-# Skylark macro declaration:
+# Macro declaration:
def my_custom_bazel_macro(name, my_config_string):
allcaps = my_config_string.upper() # This line won't work with select(s).
print("My name is " + name + " with custom message: " + allcaps)
@@ -746,9 +746,9 @@
DEBUG: /myworkspace/myproject/defs.bzl:15:3: My name is sad_macro_less_sad with custom message: FIRST STRING.
```
-## <a name="boolean-select"></a>Why does select() always return true in Skylark?
-Because Skylark *macros* (but not rules) by definition
-[can't evaluate select(s)](#skylark-macros-select), any attempt to do so
+## <a name="boolean-select"></a>Why does select() always return true?
+Because *macros* (but not rules) by definition
+[can't evaluate select(s)](#macros-select), any attempt to do so
usually produces a an error:
```sh
@@ -785,13 +785,13 @@
DEBUG: /myworkspace/myproject/defs.bzl:4:3: TRUE.
```
-This happens because Skylark macros don't understand the contents of `select()`.
+This happens because macros don't understand the contents of `select()`.
So what they're really evaluting is the `select()` object itself. According to
[Pythonic](https://docs.python.org/release/2.5.2/lib/truth.html) design
standards, all objects aside from a very small number of exceptions
automatically return true.
-## <a name="inspectable-select"></a>Can I read select() like a dict in Skylark?
-Fine. Skylark macros [can't](#skylark-macros-select) evaluate select(s) because
+## <a name="inspectable-select"></a>Can I read select() like a dict?
+Fine. Macros [can't](#macros-select) evaluate select(s) because
macros are evaluated before Bazel knows what the command line flags are.
Can macros at least read the `select()`'s dictionary, say, to add an extra
diff --git a/site/docs/ide.md b/site/docs/ide.md
index 8d3b16a..86f6890 100644
--- a/site/docs/ide.md
+++ b/site/docs/ide.md
@@ -16,7 +16,7 @@
[Plug-ins](http://ij.bazel.build) for Android Studio, CLion, and IntelliJ enable you to:
* Import BUILD files into the IDE
-* Make your IDE aware of Bazel's build and Skylark languages
+* Make your IDE aware of Starlark, the language used for Bazel's BUILD and bzl files
* Build, test, and execute binaries directly from the IDE
Installation:
diff --git a/site/docs/remote-execution-rules.md b/site/docs/remote-execution-rules.md
index 60edd52..2e1e964 100644
--- a/site/docs/remote-execution-rules.md
+++ b/site/docs/remote-execution-rules.md
@@ -10,7 +10,7 @@
is currently in development. You can try remote execution with [bazel-buildfarm](https://github.com/bazelbuild/bazel-buildfarm),
an open-source project that aims to provide a distributed remote execution
platform. This document is intended for Bazel users writing custom build and
-test rules in Skylark who want to understand the requirements for Bazel rules in
+test rules who want to understand the requirements for Bazel rules in
the context of remote execution.
This document uses the following terminology when referring to different
diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md
index 6c27fa6..9caebb3 100644
--- a/site/docs/skylark/backward-compatibility.md
+++ b/site/docs/skylark/backward-compatibility.md
@@ -252,7 +252,7 @@
### Remove native git repository
When set, the native `git_repository` and `new_git_repository` rules are
-disabled. The Skylark versions
+disabled. The Starlark versions
```python
load("@bazel_tools//tools/build_defs/repo:git.bzl",
@@ -271,7 +271,7 @@
### Remove native http archive
When set, the native `http_archive` and all related rules are disabled.
-The Skylark version
+The Starlark version
```python
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
@@ -279,7 +279,7 @@
should be used instead. This is a drop-in replacement, however with the
additional requirement that all label arguments be provided as
-fully qualified labels (usually starting with `@//`). The Skylark `http_archive`
+fully qualified labels (usually starting with `@//`). The Starlark `http_archive`
is also a drop-in replacement for the native `new_http_archive` (with
the same proviso). `http.bzl` also
provides `http_jar` and `http_file` (the latter only supports the `urls`
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md
index a80524e..495b6a5 100644
--- a/site/docs/skylark/bzl-style.md
+++ b/site/docs/skylark/bzl-style.md
@@ -6,15 +6,15 @@
# .bzl Style Guide
-Skylark is a language that defines how software is built, and as such it is both
-a programming and a configuration language.
+[Starlark](language.md) is a language that defines how software is built, and as
+such it is both a programming and a configuration language.
-You will use Skylark to write BUILD files, macros, and build rules. Macros and
+You will use Starlark to write BUILD files, macros, and build rules. Macros and
rules are essentially meta-languages - they define how BUILD files are written.
BUILD files are intended to be simple and repetitive.
All software is read more often than it is written. This is especially true for
-Skylark, as engineers read BUILD files to understand dependencies of their
+Starlark, as engineers read BUILD files to understand dependencies of their
targets and details of their builds.This reading will often happen in passing,
in a hurry, or in parallel to accomplishing some other task. Consequently,
simplicity and readability are very important so that users can parse and
@@ -125,9 +125,9 @@
* When calling a macro, use only keyword arguments. This is consistent with
rules, and greatly improves readability.
-Engineers often write macros when the Skylark API of relevant rules is
+Engineers often write macros when the Starlark API of relevant rules is
insufficient for their specific use case, regardless of whether the rule is
-defined within Bazel in native code, or in Skylark. If you’re facing this
+defined within Bazel in native code, or in Starlark. If you’re facing this
problem, ask the rule author if they can extend the API to accomplish your
goals.
diff --git a/site/docs/skylark/faq.md b/site/docs/skylark/faq.md
index fcc3217..58d5481 100644
--- a/site/docs/skylark/faq.md
+++ b/site/docs/skylark/faq.md
@@ -71,7 +71,7 @@
access it during the loading and analysis phases. You can pass it as an input or
runfile to actions and executables that need it during the execution phase.
-## How should I document Skylark code?
+## How should I document Starlark code?
For rules and rule attributes, you can pass a docstring literal (possibly
triple-quoted) to the `doc` parameter of `rule` or `attr.*()`. For helper
diff --git a/site/docs/skylark/language.md b/site/docs/skylark/language.md
index 317c890..a3607be 100644
--- a/site/docs/skylark/language.md
+++ b/site/docs/skylark/language.md
@@ -1,20 +1,22 @@
---
layout: documentation
-title: Skylark Language
+title: Starlark Language
---
-# Skylark Language
+# Starlark Language
<!-- [TOC] -->
-The page is an overview of Skylark, the language used in Bazel. This should be
+The page is an overview of [Starlark](https://github.com/bazelbuild/starlark)
+(formerly known as Skylark), the language used in Bazel. This should be
enough to get you started, but you may be interested in a more complete
-[Skylark Language Specification](spec.md). For a complete list of functions and
-types, please check the [API reference](lib/skylark-overview.html).
+[Starlark Language Specification](https://github.com/bazelbuild/starlark/blob/master/spec.md).
+For a complete list of functions and types, please check the
+[API reference](lib/skylark-overview.html).
## Syntax
-Skylark is designed to be small, simple, and thread-safe. Although it is
+Starlark is designed to be small, simple, and thread-safe. Although it is
inspired from Python, it is not a general-purpose language and most Python
features are not included.
@@ -42,11 +44,11 @@
types are specific to Bazel: [depset](lib/depset.html) and
[struct](lib/struct.html).
-Skylark is syntactically a subset of both Python 2 and Python 3, and will remain
+Starlark is syntactically a subset of both Python 2 and Python 3, and will remain
so through at least the 1.x release lifecycle. This ensures that Python-based
-tooling can at least parse Skylark code. Although Skylark is not *semantically*
+tooling can at least parse Starlark code. Although Starlark is not *semantically*
a subset of Python, behavioral differences are rare (excluding cases where
-Skylark raises an error).
+Starlark raises an error).
## Mutability
diff --git a/site/docs/skylark/performance.md b/site/docs/skylark/performance.md
index 80937af..7153c3f 100644
--- a/site/docs/skylark/performance.md
+++ b/site/docs/skylark/performance.md
@@ -7,11 +7,15 @@
<!-- [TOC] -->
-Skylark efficiency often involves avoiding O(N^2) in time and/or space.
-Crucially this involves understanding depsets and avoiding their expansion.
+When writing rules, the most common performance pitfall is to traverse or copy
+data that is accumulated from dependencies. When aggregated over the whole
+build, these operations can easily take O(N^2) time or space. To avoid this, it
+is crucial to understand how to use depsets effectively.
This can be hard to get right, so Bazel also provides a memory profiler that
-assists you in finding spots where you might have made a mistake.
+assists you in finding spots where you might have made a mistake. Be warned:
+The cost of writing an inefficient rule may not be evident until it is in
+widespread use.
## Use depsets
@@ -196,7 +200,7 @@
## Memory Profiling
Bazel comes with a built-in memory profiler that can help you check your rule's
-memory use. If there is a problem you can dump the Skylark heap to find the
+memory use. If there is a problem you can dump the heap to find the
exact line of code that is causing the problem.
### Enabling Memory Tracking
diff --git a/site/docs/skylark/skylint.md b/site/docs/skylark/skylint.md
index 06c1b83..686ad5c 100644
--- a/site/docs/skylark/skylint.md
+++ b/site/docs/skylark/skylint.md
@@ -7,7 +7,7 @@
[Style guide](https://docs.bazel.build/versions/master/skylark/bzl-style.html)
-This document explains how to use Skylint, the Skylark linter.
+This document explains how to use Skylint, the Starlark linter.
<!-- [TOC] -->
@@ -100,7 +100,7 @@
<a name="bad-docstring-format"></a>
Categories: [missing-module-docstring] [missing-function-docstring] [bad-docstring-format]
-The Skylark conventions for docstrings are similar to the [the Python
+The Starlark conventions for docstrings are similar to the [the Python
conventions](https://google.github.io/styleguide/pyguide.html?showone=Comments#Comments).
Docstrings are triple-quoted string literals and the closing quotes have to
appear on their own line unless the docstring is only one line long.
@@ -176,7 +176,7 @@
<a name="confusing-name"></a>
Categories: [name-with-wrong-case] [provider-name-suffix] [confusing-name]
-**TL;DR**: Most Skylark identifiers should be `snake_case`, not `camelCase`.
+**TL;DR**: Most Starlark identifiers should be `snake_case`, not `camelCase`.
In detail, the rules are the following:
diff --git a/site/docs/skylark/testing.md b/site/docs/skylark/testing.md
index 5957e6d..b99bdd8 100644
--- a/site/docs/skylark/testing.md
+++ b/site/docs/skylark/testing.md
@@ -5,7 +5,7 @@
# Testing
-There are several different approaches to testing Skylark code in Bazel. This
+There are several different approaches to testing Starlark code in Bazel. This
page gathers the current best practices and frameworks by use case.
<!-- [TOC] -->
@@ -17,7 +17,7 @@
[`unittest.bzl`](https://github.com/bazelbuild/bazel-skylib/blob/master/lib/unittest.bzl)
for checking the analysis-time behavior of rules, such as their actions and
providers. It is currently the best option for tests that need to access the
-inner workings of Skylark rules.
+inner workings of rules.
Some caveats:
@@ -314,9 +314,9 @@
### Using a custom rule
A more complicated alternative is to write the shell script as a template that
-gets instantiated by a new Skylark rule. This involves more indirection and
-Skylark logic, but leads to cleaner BUILD files. As a side-benefit, any argument
-preprocessing can be done in Skylark instead of the script, and the script is
+gets instantiated by a new rule. This involves more indirection and Starlark
+logic, but leads to cleaner BUILD files. As a side-benefit, any argument
+preprocessing can be done in Starlark instead of the script, and the script is
slightly more self-documenting since it uses symbolic placeholders (for
substitutions) instead of numeric ones (for arguments).
@@ -394,7 +394,7 @@
analysis phase using the `str.format` method or `%`-formatting.
-## For testing Skylark utilities
+## For testing Starlark utilities
The same framework that was used to test rules can also be used to test utility
functions (i.e., functions that are neither macros nor rule implementations).
