diff options
author | Laurent Le Brun <laurentlb@google.com> | 2017-02-17 15:05:43 +0000 |
---|---|---|
committer | Irina Iancu <elenairina@google.com> | 2017-02-20 09:40:07 +0000 |
commit | 463a957a381a1473a973cd88217a12423e9dcd09 (patch) | |
tree | 956f14da9f6f87c2aa836fd3bd8adac15546543b /site | |
parent | e36a66cd6e35e5b4b276f2b6ce63e1c691bcb02c (diff) |
Split documentation. Move language description to a separate page.
--
PiperOrigin-RevId: 147834340
MOS_MIGRATED_REVID=147834340
Diffstat (limited to 'site')
-rw-r--r-- | site/_layouts/documentation.html | 1 | ||||
-rw-r--r-- | site/versions/master/docs/skylark/concepts.md | 132 | ||||
-rw-r--r-- | site/versions/master/docs/skylark/language.md | 142 |
3 files changed, 143 insertions, 132 deletions
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html index 86abd3197f..775ca27852 100644 --- a/site/_layouts/documentation.html +++ b/site/_layouts/documentation.html @@ -84,6 +84,7 @@ version_prefix: /versions/master <h3>Extensions</h3> <ul class="sidebar-nav"> <li><a href="{{ page.version_prefix }}/docs/skylark/concepts.html">Overview</a></li> + <li><a href="{{ page.version_prefix }}/docs/skylark/language.html">Language</a></li> <li><a href="{{ page.version_prefix }}/docs/skylark/macros.html">Macros</a></li> <li><a href="{{ page.version_prefix }}/docs/skylark/rules.html">Rules</a></li> <li><a href="{{ page.version_prefix }}/docs/skylark/aspects.html">Aspects</a></li> diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md index 0aac390d9f..fb6f0e2f9c 100644 --- a/site/versions/master/docs/skylark/concepts.md +++ b/site/versions/master/docs/skylark/concepts.md @@ -91,138 +91,6 @@ 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 -[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. - -The following constructs have been added to the Core Build Language: `if` -statements, `for` loops, and function definitions. They behave like in Python. -Here is an example to show the syntax: - -```python -def fizz_buzz(n): - """Print Fizz Buzz numbers from 1 to n.""" - for i in range(1, n + 1): - s = "" - if i % 3 == 0: - s += "Fizz" - if i % 5 == 0: - s += "Buzz" - print(s if s else i) - -fizz_buzz(20) -``` - -## Mutability - -Because evaluation of BUILD and .bzl files is performed in parallel, there are -some restrictions in order to guarantee thread-safety and determinism. Two -mutable data structures are available: [lists](lib/list.html) and -[dicts](lib/dict.html). - -In a build, there are many "evaluation contexts": each `.bzl` file and each -`BUILD` file is loaded in a different context. Each rule is also analyzed in a -separate context. We allow side-effects (e.g. appending a value to a list or -deleting an entry in a dictionary) only on objects created during the current -evaluation context. Once the code in that context is done executing, all of its -values are frozen. - -For example, here is the content of the file `foo.bzl`: - -```python -var = [] - -def fct(): - var.append(5) - -fct() -``` - -The variable `var` is created when `foo.bzl` is loaded. `fct()` is called during -the same context, so it is safe. At the end of the evaluation, the environment -contains an entry mapping the identifier `var` to a list `[5]`; this list is -then frozen. - -It is possible for multiple other files to load symbols from `foo.bzl` at the -same time. For this reason, the following code is not legal: - -```python -load(":foo.bzl", "var", "fct") - -var.append(6) # runtime error, the list stored in var is frozen - -fct() # runtime error, fct() attempts to modify a frozen list -``` - -Evaluation contexts are also created for the analysis of each custom rule. This -means that any values that are returned from the rule's analysis are frozen. -Note that by the time a custom rule's analysis begins, the .bzl file in which -it is defined has already been loaded, and so the global variables are already -frozen. - -There are also restrictions on rebinding variables. In .bzl files, it is illegal -to overwrite an existing global or built-in variable, such as by assigning to -it, even when the module has not yet been frozen. - -## Differences with Python - -In addition to the mutability restrictions, there are also differences with -Python: - -* Global variables cannot be reassigned. - -* `for` statements are not allowed at the top-level; factor them into functions - instead. - -* Dictionaries have a deterministic order of iteration. - -* Recursion is not allowed. - -* Int type is limited to 32-bit signed integers. - -* Lists and other mutable types may be stored in dictionary - keys once they are frozen. - -* Modifying a collection during iteration is an error. You can avoid the error - by iterating over a copy of the collection, e.g. - `for x in list(my_list): ...`. You can still modify its deep contents - regardless. - -* Global (non-function) variables must be declared before they can be used in - a function, even if the function is not called until after the global variable - declaration. However, it is fine to define `f()` before `g()`, even if `f()` - calls `g()`. - -* The order comparison operators (<, <=, >=, >) are not defined across different - types of values, e.g., you can't compare `5 < 'foo'` (however you still can - compare them using == or !=). This is a difference with Python 2, but - consistent with Python 3. Note that this means you are unable to sort lists - that contain mixed types of values. - -* Tuple syntax is more restrictive. You may use a trailing comma only when the - tuple is between parentheses, e.g. write `(1,)` instead of `1,`. - -* Strings are represented with double-quotes (e.g. when you - call [repr](lib/globals.html#repr)). - -The following Python features are not supported: - -* implicit string concatenation (use explicit `+` operator) -* `class` (see [`struct`](lib/globals.html#struct) function) -* `import` (see [`load`](#loading-a-skylark-extension) statement) -* `while`, `yield` -* float and set types -* `lambda` and nested functions -* `is` (use `==` instead) -* `try`, `raise`, `except`, `finally` (see [`fail`](lib/globals.html#fail) - for fatal errors) -* `global`, `nonlocal` -* most builtin functions, most methods ## Upcoming changes diff --git a/site/versions/master/docs/skylark/language.md b/site/versions/master/docs/skylark/language.md new file mode 100644 index 0000000000..7b89b34a2f --- /dev/null +++ b/site/versions/master/docs/skylark/language.md @@ -0,0 +1,142 @@ +--- +layout: documentation +title: Extensions - Overview +--- +# Language + + +## Syntax + +The extension language (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. + +The following constructs have been added to the Core Build Language: `if` +statements, `for` loops, and function definitions. They behave like in Python. +Here is an example to show the syntax: + +```python +def fizz_buzz(n): + """Print Fizz Buzz numbers from 1 to n.""" + for i in range(1, n + 1): + s = "" + if i % 3 == 0: + s += "Fizz" + if i % 5 == 0: + s += "Buzz" + print(s if s else i) + +fizz_buzz(20) +``` + +The following basic types are supported: [None](lib/globals.html#None), +[bool](lib/bool.html), [dict](lib/dict.html), function, [int](lib/int.html), +[list](lib/list.html), [string](lib/string.html). On top of that, two new +types are specific to Bazel: [depset](lib/depset.html) and +[struct](lib/struct.html). + + +## Mutability + +Because evaluation of BUILD and .bzl files is performed in parallel, there are +some restrictions in order to guarantee thread-safety and determinism. Two +mutable data structures are available: [lists](lib/list.html) and +[dicts](lib/dict.html). + +In a build, there are many "evaluation contexts": each `.bzl` file and each +`BUILD` file is loaded in a different context. Each rule is also analyzed in a +separate context. We allow side-effects (e.g. appending a value to a list or +deleting an entry in a dictionary) only on objects created during the current +evaluation context. Once the code in that context is done executing, all of its +values are frozen. + +For example, here is the content of the file `foo.bzl`: + +```python +var = [] + +def fct(): + var.append(5) + +fct() +``` + +The variable `var` is created when `foo.bzl` is loaded. `fct()` is called during +the same context, so it is safe. At the end of the evaluation, the environment +contains an entry mapping the identifier `var` to a list `[5]`; this list is +then frozen. + +It is possible for multiple other files to load symbols from `foo.bzl` at the +same time. For this reason, the following code is not legal: + +```python +load(":foo.bzl", "var", "fct") + +var.append(6) # runtime error, the list stored in var is frozen + +fct() # runtime error, fct() attempts to modify a frozen list +``` + +Evaluation contexts are also created for the analysis of each custom rule. This +means that any values that are returned from the rule's analysis are frozen. +Note that by the time a custom rule's analysis begins, the .bzl file in which +it is defined has already been loaded, and so the global variables are already +frozen. + +## Differences with Python + +In addition to the mutability restrictions, there are also differences with +Python: + +* Global variables cannot be reassigned. + +* `for` statements are not allowed at the top-level; factor them into functions + instead. + +* Dictionaries have a deterministic order of iteration. + +* Recursion is not allowed. + +* Int type is limited to 32-bit signed integers. + +* Lists and other mutable types may be stored in dictionary + keys once they are frozen. + +* Modifying a collection during iteration is an error. You can avoid the error + by iterating over a copy of the collection, e.g. + `for x in list(my_list): ...`. You can still modify its deep contents + regardless. + +* Global (non-function) variables must be declared before they can be used in + a function, even if the function is not called until after the global variable + declaration. However, it is fine to define `f()` before `g()`, even if `f()` + calls `g()`. + +* The order comparison operators (<, <=, >=, >) are not defined across different + types of values, e.g., you can't compare `5 < 'foo'` (however you still can + compare them using == or !=). This is a difference with Python 2, but + consistent with Python 3. Note that this means you are unable to sort lists + that contain mixed types of values. + +* Tuple syntax is more restrictive. You may use a trailing comma only when the + tuple is between parentheses, e.g. write `(1,)` instead of `1,`. + +* Strings are represented with double-quotes (e.g. when you + call [repr](lib/globals.html#repr)). + +The following Python features are not supported: + +* implicit string concatenation (use explicit `+` operator) +* `class` (see [`struct`](lib/globals.html#struct) function) +* `import` (see [`load`](#loading-a-skylark-extension) statement) +* `while`, `yield` +* float and set types +* `lambda` and nested functions +* `is` (use `==` instead) +* `try`, `raise`, `except`, `finally` (see [`fail`](lib/globals.html#fail) + for fatal errors) +* `global`, `nonlocal` +* most builtin functions, most methods |