diff options
author | Kristina Chodorow <kchodorow@google.com> | 2016-06-20 17:27:28 +0000 |
---|---|---|
committer | Philipp Wollermann <philwo@google.com> | 2016-06-21 09:58:14 +0000 |
commit | 662dadd57662400c3a59edfa5347e1cf917053aa (patch) | |
tree | bb89e8d92cc75bbee761353099319ff560ce3a6c /site/docs/skylark/bzl-style.md | |
parent | 28de2754fa6f3dce071e630bbf6e14aa7f554acd (diff) |
Add license types to the documentation
Fixes #642.
--
MOS_MIGRATED_REVID=125351602
Diffstat (limited to 'site/docs/skylark/bzl-style.md')
-rw-r--r-- | site/docs/skylark/bzl-style.md | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/site/docs/skylark/bzl-style.md b/site/docs/skylark/bzl-style.md new file mode 100644 index 0000000000..a88dfcad76 --- /dev/null +++ b/site/docs/skylark/bzl-style.md @@ -0,0 +1,48 @@ + +# .bzl file style guide + +## Style + +* When in doubt, follow the + [Python style guide](https://www.python.org/dev/peps/pep-0008/). + +* Code should be documented using + [docstrings](https://www.python.org/dev/peps/pep-0257/). Use a docstring at + the top of the file, and a docstring for each public function. + +* Variables and function names use lowercase with words separated by underscores + (`[a-z][a-z0-9_]*`), e.g. `cc_library`. Top-level private values start with + one underscore. Bazel enforces that private values cannot be used from other + files. + +* As in BUILD files, there is no strict line length limit as labels can be long. + When possible, try to use at most 79 characters per line. + +* In keyword arguments, spaces around the equal sign are optional. In general, + we follow the BUILD file convention when calling macros and native rules, and + the Python convention for other functions, e.g. + +```python +def fct(name, srcs): + filtered_srcs = my_filter(source=srcs) + native.cc_library( + name = name, + srcs = filtered_srcs, + ) +``` + +## Macros + +A [macro](macros.md) is a function which instantiates one or many rules during +the loading phase. + +* Macros must accept a name attribute and each invocation should specify a name. + The generated name attribute of rules should include the name attribute as a + prefix. For example, `my_macro(name = "foo")` can generate a rule `foo` and a + rule `foo_gen`. *Rationale*: Users should be able to find easily which macro + generated a rule. Also, automated refactoring tools need a way to identify a + specific rule to edit. + +* When calling a macro, use only keyword arguments. *Rationale*: This is for + consistency with rules, it greatly improves readability. + |