diff options
author | 2017-04-24 13:33:01 +0200 | |
---|---|---|
committer | 2017-04-24 16:52:05 +0200 | |
commit | 20df206caf8fdec39f92d2359f1c7e85ce6dae6a (patch) | |
tree | 7afcd1d632d19fe60202f7ae20dffb8ee480b09d /site | |
parent | b605a248ebe9233d8b7c0a971c62a6883bb6f0bd (diff) |
Make implementations method non-public
Prefix implementation methods with one underscore.
Also, consistently surround attribute assignmenets by spaces `rule(x = y)` instead `rule(x=y)`.
Closes #2770.
PiperOrigin-RevId: 154036583
Diffstat (limited to 'site')
-rw-r--r-- | site/versions/master/docs/skylark/rules.md | 72 |
1 files changed, 39 insertions, 33 deletions
diff --git a/site/versions/master/docs/skylark/rules.md b/site/versions/master/docs/skylark/rules.md index 525fe59b26..5db62cf5e0 100644 --- a/site/versions/master/docs/skylark/rules.md +++ b/site/versions/master/docs/skylark/rules.md @@ -9,7 +9,7 @@ title: Rules A rule defines a series of [actions](#actions) that Bazel should perform on inputs to get a set of outputs. For example, a C++ binary rule might take a set -of .cpp files (the inputs), run `g++` on them (the action), and return an +of `.cpp` files (the inputs), run `g++` on them (the action), and return an executable file (the output). Note that, from Bazel's perspective, `g++` and the standard C++ libraries are @@ -55,7 +55,7 @@ the attributes and their types when you define a rule. ```python sum = rule( - implementation = impl, + implementation = _impl, attrs = { "number": attr.int(default = 1), "deps": attr.label_list(), @@ -78,19 +78,23 @@ See [an example](cookbook.md#attr) of using `attr` in a rule. ### <a name="private-attributes"></a> Private Attributes -If an attribute name starts with `_` it is private and users cannot set it. It -is useful in particular for label attributes (your rule will have an +In Python, we use one leading underscore(`_`) for non-public methods and +instance variables (see [PEP-8][1]). + +Similarly, if an attribute name starts with `_` it is private and users cannot +set it. +It is useful in particular for label attributes (your rule will have an implicit dependency on this label). ```python metal_compile = rule( - implementation=impl, - attrs={ + implementation = _impl, + attrs = { "srcs": attr.label_list(), "_compiler": attr.label( - default=Label("//tools:metalc"), - allow_single_file=True, - executable=True, + default = Label("//tools:metalc"), + allow_single_file = True, + executable = True, ), }, ) @@ -108,16 +112,16 @@ has some helper functions. See [the library](lib/ctx.html) for more context. Example: ```python -def impl(ctx): +def _impl(ctx): ... return struct( - runfiles=..., - my_provider=..., + runfiles = ..., + my_provider = ..., ... ) my_rule = rule( - implementation=impl, + implementation = _impl, ... ) ``` @@ -153,14 +157,14 @@ my_rule( In the above case, it's possible to access targets declared in `my_rule.deps`: ```python -def impl(ctx): +def _impl(ctx): for dep in ctx.attr.deps: # Do something with dep ... my_rule = rule( - implementation=impl, - attrs={ + implementation = _impl, + attrs = { "deps": attr.label_list(), }, ... @@ -310,15 +314,15 @@ such as `cpp`, `java` and `jvm`. However, all required fragments must be declared in order to avoid access errors: ```python -def impl(ctx): +def _impl(ctx): # Using ctx.fragments.cpp would lead to an error since it was not declared. x = ctx.fragments.java ... my_rule = rule( - implementation=impl, - fragments=["java"], # Required fragments of the target configuration - host_fragments=["java"], # Required fragments of the host configuration + implementation = _impl, + fragments = ["java"], # Required fragments of the target configuration + host_fragments = ["java"], # Required fragments of the host configuration ... ) ``` @@ -364,7 +368,7 @@ Providers are created from the return value of the rule implementation function: def rule_implementation(ctx): ... return struct( - transitive_data=depset(["a", "b", "c"]) + transitive_data = depset(["a", "b", "c"]) ) ``` @@ -399,7 +403,7 @@ Runfiles can be added manually during rule creation and/or collected transitively from the rule's dependencies: ```python -def rule_implementation(ctx): +def _rule_implementation(ctx): ... transitive_runfiles = depset() for dep in ctx.attr.special_dependencies: @@ -407,16 +411,16 @@ def rule_implementation(ctx): runfiles = ctx.runfiles( # Add some files manually. - files=[ctx.file.some_data_file], + files = [ctx.file.some_data_file], # Add transitive files from dependencies manually. - transitive_files=transitive_runfiles, + transitive_files = transitive_runfiles, # Collect runfiles from the common locations: transitively from srcs, # deps and data attributes. - collect_default=True, + collect_default = True, ) # Add a field named "runfiles" to the return struct in order to actually # create the symlink tree. - return struct(runfiles=runfiles) + return struct(runfiles = runfiles) ``` Note that non-executable rule outputs can also have runfiles. For example, a @@ -437,8 +441,8 @@ name of the workspace. ```python ... runfiles = ctx.runfiles( - root_symlinks={"some/path/here.foo": ctx.file.some_data_file2} - symlinks={"some/path/here.bar": ctx.file.some_data_file3} + root_symlinks = {"some/path/here.foo": ctx.file.some_data_file2} + symlinks = {"some/path/here.bar": ctx.file.some_data_file3} ) # Creates something like: # sometarget.runfiles/ @@ -464,19 +468,19 @@ A rule can use the `instrumented_files` provider to provide information about which files should be measured when code coverage data collection is enabled: ```python -def rule_implementation(ctx): +def _rule_implementation(ctx): ... - return struct(instrumented_files=struct( + return struct(instrumented_files = struct( # Optional: File extensions used to filter files from source_attributes. # If not provided, then all files from source_attributes will be # added to instrumented files, if an empty list is provided, then # no files from source attributes will be added. - extensions=["ext1", "ext2"], + extensions = ["ext1", "ext2"], # Optional: Attributes that contain source files for this rule. - source_attributes=["srcs"], + source_attributes = ["srcs"], # Optional: Attributes for dependencies that could include instrumented # files. - dependency_attributes=["data", "deps"])) + dependency_attributes = ["data", "deps"])) ``` [ctx.config.coverage_enabled](lib/configuration.html#coverage_enabled) notes @@ -531,3 +535,5 @@ the `implementation` function of the rule must generate the output file Test rules inherit the following attributes: `args`, `flaky`, `local`, `shard_count`, `size`, `timeout`. + +[1]: https://www.python.org/dev/peps/pep-0008/#id46 |