| # Buildifier warnings |
| |
| Warning categories supported by buildifier's linter: |
| |
| * [`attr-applicable_licenses`](#attr-applicable_licenses) |
| * [`attr-cfg`](#attr-cfg) |
| * [`attr-license`](#attr-license) |
| * [`attr-licenses`](#attr-licenses) |
| * [`attr-non-empty`](#attr-non-empty) |
| * [`attr-output-default`](#attr-output-default) |
| * [`attr-package-metadata`](#attr-package-metadata) |
| * [`attr-single-file`](#attr-single-file) |
| * [`build-args-kwargs`](#build-args-kwargs) |
| * [`bzl-visibility`](#bzl-visibility) |
| * [`confusing-name`](#confusing-name) |
| * [`constant-glob`](#constant-glob) |
| * [`ctx-actions`](#ctx-actions) |
| * [`ctx-args`](#ctx-args) |
| * [`deprecated-function`](#deprecated-function) |
| * [`depset-items`](#depset-items) |
| * [`depset-iteration`](#depset-iteration) |
| * [`depset-union`](#depset-union) |
| * [`dict-concatenation`](#dict-concatenation) |
| * [`dict-method-named-arg`](#dict-method-named-arg) |
| * [`duplicated-name`](#duplicated-name) |
| * [`filetype`](#filetype) |
| * [`function-docstring`](#function-docstring) |
| * [`function-docstring-args`](#function-docstring-args) |
| * [`function-docstring-header`](#function-docstring-header) |
| * [`function-docstring-return`](#function-docstring-return) |
| * [`git-repository`](#git-repository) |
| * [`http-archive`](#http-archive) |
| * [`integer-division`](#integer-division) |
| * [`keyword-positional-params`](#keyword-positional-params) |
| * [`list-append`](#list-append) |
| * [`load`](#load) |
| * [`load-on-top`](#load-on-top) |
| * [`module-docstring`](#module-docstring) |
| * [`name-conventions`](#name-conventions) |
| * [`native-android`](#native-android) |
| * [`native-build`](#native-build) |
| * [`native-cc-binary`](#native-cc-binary) |
| * [`native-cc-common`](#native-cc-common) |
| * [`native-cc-debug-package-info`](#native-cc-debug-package-info) |
| * [`native-cc-fdo-prefetch-hints`](#native-cc-fdo-prefetch-hints) |
| * [`native-cc-fdo-profile`](#native-cc-fdo-profile) |
| * [`native-cc-import`](#native-cc-import) |
| * [`native-cc-info`](#native-cc-info) |
| * [`native-cc-library`](#native-cc-library) |
| * [`native-cc-memprof-profile`](#native-cc-memprof-profile) |
| * [`native-cc-objc-import`](#native-cc-objc-import) |
| * [`native-cc-objc-library`](#native-cc-objc-library) |
| * [`native-cc-propeller-optimize`](#native-cc-propeller-optimize) |
| * [`native-cc-proto`](#native-cc-proto) |
| * [`native-cc-shared-library`](#native-cc-shared-library) |
| * [`native-cc-shared-library-hint-info`](#native-cc-shared-library-hint-info) |
| * [`native-cc-shared-library-info`](#native-cc-shared-library-info) |
| * [`native-cc-test`](#native-cc-test) |
| * [`native-cc-toolchain`](#native-cc-toolchain) |
| * [`native-cc-toolchain-suite`](#native-cc-toolchain-suite) |
| * [`native-java-binary`](#native-java-binary) |
| * [`native-java-common`](#native-java-common) |
| * [`native-java-import`](#native-java-import) |
| * [`native-java-info`](#native-java-info) |
| * [`native-java-library`](#native-java-library) |
| * [`native-java-lite-proto`](#native-java-lite-proto) |
| * [`native-java-package-config`](#native-java-package-config) |
| * [`native-java-plugin`](#native-java-plugin) |
| * [`native-java-plugin-info`](#native-java-plugin-info) |
| * [`native-java-proto`](#native-java-proto) |
| * [`native-java-runtime`](#native-java-runtime) |
| * [`native-java-test`](#native-java-test) |
| * [`native-java-toolchain`](#native-java-toolchain) |
| * [`native-package`](#native-package) |
| * [`native-proto`](#native-proto) |
| * [`native-proto-common`](#native-proto-common) |
| * [`native-proto-info`](#native-proto-info) |
| * [`native-proto-lang-toolchain`](#native-proto-lang-toolchain) |
| * [`native-proto-lang-toolchain-info`](#native-proto-lang-toolchain-info) |
| * [`native-py`](#native-py) |
| * [`native-sh-binary`](#native-sh-binary) |
| * [`native-sh-library`](#native-sh-library) |
| * [`native-sh-test`](#native-sh-test) |
| * [`no-effect`](#no-effect) |
| * [`out-of-order-load`](#out-of-order-load) |
| * [`output-group`](#output-group) |
| * [`overly-nested-depset`](#overly-nested-depset) |
| * [`package-name`](#package-name) |
| * [`package-on-top`](#package-on-top) |
| * [`positional-args`](#positional-args) |
| * [`print`](#print) |
| * [`provider-params`](#provider-params) |
| * [`redefined-variable`](#redefined-variable) |
| * [`repository-name`](#repository-name) |
| * [`return-value`](#return-value) |
| * [`rule-impl-return`](#rule-impl-return) |
| * [`same-origin-load`](#same-origin-load) |
| * [`skylark-comment`](#skylark-comment) |
| * [`skylark-docstring`](#skylark-docstring) |
| * [`string-iteration`](#string-iteration) |
| * [`uninitialized`](#uninitialized) |
| * [`unnamed-macro`](#unnamed-macro) |
| * [`unreachable`](#unreachable) |
| * [`unsorted-dict-items`](#unsorted-dict-items) |
| * [`unused-variable`](#unused-variable) |
| |
| ### <a name="suppress"></a>How to disable warnings |
| |
| All warnings can be disabled / suppressed / ignored by adding a special comment `# buildifier: disable=<category_name>` to |
| the expression that causes the warning. Historically comments with `buildozer` instead of |
| `buildifier` are also supported, they are equivalent. |
| |
| #### Examples |
| |
| ```python |
| # buildifier: disable=no-effect |
| """ |
| A multiline comment as a string literal. |
| |
| Docstrings don't trigger the warning if they are first statements of a file or a function. |
| """ |
| |
| if debug: |
| print("Debug information:", foo) # buildifier: disable=print |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-applicable_licenses"></a>Do not use `applicable_licenses` as an attribute name. |
| |
| * Category name: `attr-applicable_licenses` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-applicable_licenses` |
| |
| Using `applicable_licenses` as an attribute name may cause unexpected behavior. Its use may be prohibited in future Bazel releases. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-cfg"></a>`cfg = "data"` for attr definitions has no effect |
| |
| * Category name: `attr-cfg` |
| * Flag in Bazel: [`--incompatible_disallow_data_transition`](https://github.com/bazelbuild/bazel/issues/6153) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-cfg` |
| |
| The [Configuration](https://docs.bazel.build/versions/main/skylark/rules.html#configurations) |
| `cfg = "data"` is deprecated and has no effect. Consider removing it. |
| The [Configuration](https://docs.bazel.build/versions/main/skylark/rules.html#configurations) |
| `cfg = "host"` is deprecated. Consider replacing it with `cfg = "exec"`. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-license"></a>`attr.license()` is deprecated and shouldn't be used |
| |
| * Category name: `attr-license` |
| * Flag in Bazel: `--incompatible_no_attr_license` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-license` |
| |
| The `attr.license()` method is almost never used and being deprecated. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-licenses"></a>Do not use `licenses` as an attribute name. |
| |
| * Category name: `attr-licenses` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-licenses` |
| |
| Using licenses as an attribute name may cause unexpected behavior. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-non-empty"></a>`non_empty` attribute for attr definitions is deprecated |
| |
| * Category name: `attr-non-empty` |
| * Flag in Bazel: `--incompatible_disable_deprecated_attr_params` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-non-empty` |
| |
| The `non_empty` [attribute](https://docs.bazel.build/versions/main/skylark/lib/attr.html) |
| for attr definitions is deprecated, please use `allow_empty` with an opposite value instead. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-output-default"></a>The `default` parameter for `attr.output()`is deprecated |
| |
| * Category name: `attr-output-default` |
| * Flag in Bazel: [`--incompatible_no_output_attr_default`](https://github.com/bazelbuild/bazel/issues/7950) |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-output-default` |
| |
| The `default` parameter of `attr.output()` is bug-prone, as two targets of the same rule would be |
| unable to exist in the same package under default behavior. Use Starlark macros to specify defaults |
| for these attributes instead. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-package-metadata"></a>Do not use `package_metadata` as an attribute name. |
| |
| * Category name: `attr-package-metadata` |
| * Automatic fix: no |
| * Not supported by the latest version of Buildifier |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-package-metadata` |
| |
| Using `package_metadata` as an attribute name may cause unexpected behavior. Its use may be prohibited in future Bazel releases. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="attr-single-file"></a>`single_file` is deprecated |
| |
| * Category name: `attr-single-file` |
| * Flag in Bazel: `--incompatible_disable_deprecated_attr_params` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=attr-single-file` |
| |
| The `single_file` [attribute](https://docs.bazel.build/versions/main/skylark/lib/attr.html) |
| is deprecated, please use `allow_single_file` instead. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="build-args-kwargs"></a>`*args` and `**kwargs` are not allowed in BUILD files |
| |
| * Category name: `build-args-kwargs` |
| * Flag in Bazel: `--incompatible_no_kwargs_in_build_files` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=build-args-kwargs` |
| |
| Having `*args` or `**kwargs` makes BUILD files hard to read and manipulate. The list of |
| arguments should be explicit. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="bzl-visibility"></a>Module shouldn't be used directly |
| |
| * Category name: `bzl-visibility` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=bzl-visibility` |
| |
| If a directory `foo` contains a subdirectory `internal` or `private`, only files located under `foo` |
| can access it. |
| |
| For example, `dir/rules_mockascript/private/foo.bzl` can be loaded from |
| `dir/rules_mockascript/private/bar.bzl` or `dir/rules_mockascript/sub/public.bzl`, |
| but not from `dir/other_rule/file.bzl`. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="confusing-name"></a>Never use `l`, `I`, or `O` as names |
| |
| * Category name: `confusing-name` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=confusing-name` |
| |
| The names `l`, `I`, or `O` can be easily confused with `I`, `l`, or `0` correspondingly. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="constant-glob"></a>Glob pattern has no wildcard ('*') |
| |
| * Category name: `constant-glob` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=constant-glob` |
| |
| [Glob function](https://docs.bazel.build/versions/main/be/functions.html#glob) |
| is used to get a list of files from the depot. The patterns (the first argument) |
| typically include a wildcard (* character). A pattern without a wildcard is |
| often useless and sometimes harmful. |
| |
| To fix the warning, move the string out of the glob: |
| |
| ```diff |
| - glob(["*.cc", "test.cpp"]) |
| + glob(["*.cc"]) + ["test.cpp"] |
| ``` |
| |
| **There’s one important difference**: before the change, Bazel would silently |
| ignore test.cpp if file is missing; after the change, Bazel will throw an error |
| if file is missing. |
| |
| If `test.cpp` doesn’t exist, the fix becomes: |
| |
| ```diff |
| - glob(["*.cc", "test.cpp"]) |
| + glob(["*.cc"]) |
| ``` |
| |
| which improves maintenance and readability. |
| |
| If no pattern has a wildcard, just remove the glob. It will also improve build |
| performance (glob can be relatively slow): |
| |
| ```diff |
| - glob(["test.cpp"]) |
| + ["test.cpp"] |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="ctx-actions"></a>`ctx.{action_name}` is deprecated |
| |
| * Category name: `ctx-actions` |
| * Flag in Bazel: [`--incompatible_new_actions_api`](https://github.com/bazelbuild/bazel/issues/5825) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=ctx-actions` |
| |
| The following [actions](https://docs.bazel.build/versions/main/skylark/lib/actions.html) |
| are deprecated, please use the new API: |
| |
| * [`ctx.new_file`](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#new_file) → [`ctx.actions.declare_file`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#declare_file) |
| * `ctx.experimental_new_directory` → [`ctx.actions.declare_directory`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#declare_directory) |
| * [`ctx.file_action`](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#file_action) → [`ctx.actions.write`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#write) |
| * [`ctx.action(command = "...")`](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#action) → [`ctx.actions.run_shell`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#run_shell) |
| * [`ctx.action(executable = "...")`](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#action) → [`ctx.actions.run`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#run) |
| * [`ctx.empty_action`](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#empty_action) → [`ctx.actions.do_nothing`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#do_nothing) |
| * [`ctx.template_action`](https://docs.bazel.build/versions/main/skylark/lib/ctx.html#template_action) → [`ctx.actions.expand_template`](https://docs.bazel.build/versions/main/skylark/lib/actions.html#expand_template) |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="ctx-args"></a>`ctx.actions.args().add()` for multiple arguments is deprecated |
| |
| * Category name: `ctx-args` |
| * Flag in Bazel: [`--incompatible_disallow_old_style_args_add`](https://github.com/bazelbuild/bazel/issues/5822) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=ctx-args` |
| |
| It's deprecated to use the [`add`](https://docs.bazel.build/versions/main/skylark/lib/Args.html#add) |
| method of `ctx.actions.args()` to add a list (or a depset) of variables. Please use either |
| [`add_all`](https://docs.bazel.build/versions/main/skylark/lib/Args.html#add_all) or |
| [`add_joined`](https://docs.bazel.build/versions/main/skylark/lib/Args.html#add_joined), |
| depending on the desired behavior. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="deprecated-function"></a>The function is deprecated |
| |
| * Category name: `deprecated-function` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=deprecated-function` |
| |
| The function defined in another .bzl file has a docstring stating that it's deprecated, i.e. it |
| contains a `Deprecated:` section. The convention for function docstrings is described by |
| the [`function-docstring`](#function-docstring) warning. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="depset-items"></a>Depset's "items" parameter is deprecated |
| |
| * Category name: `depset-items` |
| * Flag in Bazel: [`--incompatible_disable_depset_items`](https://github.com/bazelbuild/bazel/issues/9017) |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=depset-items` |
| |
| The `items` parameter for [`depset`](https://docs.bazel.build/versions/main/skylark/lib/globals.html#depset) |
| is deprecated. In its old form it's either a list of direct elements to be |
| added (use the `direct` or unnamed first parameter instead) or a depset that |
| becomes a transitive element of the new depset (use the `transitive` parameter |
| instead). |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="depset-iteration"></a>Depset iteration is deprecated |
| |
| * Category name: `depset-iteration` |
| * Flag in Bazel: [`--incompatible_depset_is_not_iterable`](https://github.com/bazelbuild/bazel/issues/5816) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=depset-iteration` |
| |
| Depsets are complex structures, iterations over them and lookups require flattening them to |
| a list which may be a heavy operation. To make it more obvious it's now required to call |
| the `.to_list()` method on them in order to be able to iterate their items: |
| |
| ```python |
| deps = depset() |
| [x.path for x in deps] # deprecated |
| [x.path for x in deps.to_list()] # recommended |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="depset-union"></a>Depsets should be joined using the depset constructor |
| |
| * Category name: `depset-union` |
| * Flag in Bazel: [`--incompatible_depset_union`](https://github.com/bazelbuild/bazel/issues/5817) |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=depset-union` |
| |
| The following ways to merge two depsets are deprecated: |
| |
| ```python |
| depset1 + depset2 |
| depset1 | depset2 |
| depset1.union(depset2) |
| ``` |
| |
| Please use the [depset](https://docs.bazel.build/versions/main/skylark/lib/depset.html) constructor |
| instead: |
| |
| ```python |
| depset(transitive = [depset1, depset2]) |
| ``` |
| |
| When fixing this issue, make sure you |
| [understand depsets](https://docs.bazel.build/versions/main/skylark/depsets.html) |
| and try to |
| [reduce the number of calls to depset](https://docs.bazel.build/versions/main/skylark/performance.html#reduce-the-number-of-calls-to-depset). |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="dict-concatenation"></a>Dictionary concatenation is deprecated |
| |
| * Category name: `dict-concatenation` |
| * Flag in Bazel: [`--incompatible_disallow_dict_plus`](https://github.com/bazelbuild/bazel/issues/6461) |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=dict-concatenation` |
| |
| The `+` operator to concatenate dicts is deprecated. The operator used to create a new dict and |
| copy the data to it. There are several ways to avoid it, for example, instead of `d = d1 + d2 + d3` |
| you can use one of the following: |
| |
| * Use [Skylib](https://github.com/bazelbuild/bazel-skylib): |
| |
| ```python |
| load("@bazel_skylib//lib:dicts.bzl", "dicts") |
| |
| d = dicts.add(d1, d2, d3) |
| ``` |
| |
| * The same if you don't want to use Skylib: |
| |
| ```python |
| d = dict(d1.items() + d2.items() + d3.items()) |
| ``` |
| |
| * The same in several steps: |
| |
| ```python |
| d = dict(d1) # If you don't want `d1` to be mutated |
| d.update(d2) |
| d.update(d3) |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="dict-method-named-arg"></a>Dict methods do not have a named argument `default` |
| |
| * Category name: `dict-method-named-arg` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=dict-method-named-arg` |
| |
| Dict methods `get`, `pop` and `setdefault` do not accept a named argument |
| called `default`. Due to a bug, Bazel currently accepts that named argument. |
| It is better to use a positional argument instead: |
| |
| ```diff |
| - mydict.get(5, default = 0) |
| + mydict.get(5, 0) |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="duplicated-name"></a>A rule with name `foo` was already found on line |
| |
| * Category name: `duplicated-name` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=duplicated-name` |
| |
| Each label in Bazel has a unique name, and Bazel doesn’t allow two rules to have |
| the same name. With macros, this may be accepted by Bazel (if each macro |
| generates different rules): |
| |
| ```python |
| my_first_macro(name = "foo") |
| my_other_macro(name = "foo") |
| ``` |
| |
| Although the build may work, this code can be very confusing. It can confuse |
| users reading a BUILD file (if they look for the rule “foo”, they may read see |
| only one of the macros). It will also confuse tools that edit BUILD files. |
| |
| To fix the issue just change the name attribute of one rule/macro. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="filetype"></a>The `FileType` function is deprecated |
| |
| * Category name: `filetype` |
| * Flag in Bazel: [`--incompatible_disallow_filetype`](https://github.com/bazelbuild/bazel/issues/5831) |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=filetype` |
| |
| The function `FileType` is deprecated. Instead of using it as an argument to the |
| [`rule` function](https://docs.bazel.build/versions/main/skylark/lib/globals.html#rule) |
| just use a list of strings. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="function-docstring"></a><a name="function-docstring-header"></a><a name="function-docstring-args"></a><a name="function-docstring-return"></a>Function docstring |
| |
| * Category names: |
| * `function-docstring` |
| * `function-docstring-header` |
| * `function-docstring-args` |
| * `function-docstring-return` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=function-docstring`, `# buildifier: disable=function-docstring-header`, `# buildifier: disable=function-docstring-args`, `# buildifier: disable=function-docstring-return` |
| |
| Public functions should have docstrings describing functions and their signatures. |
| A docstring is a string literal (not a comment) which should be the first statement |
| of a function (it may follow comment lines). Function docstrings are expected to be |
| formatted in the following way: |
| |
| ```python |
| """One-line summary: must be followed and may be preceded by a blank line. |
| |
| Optional additional description like this. |
| |
| If it's a function docstring and the function has more than one argument, the docstring has |
| to document these parameters as follows: |
| |
| Args: |
| parameter1: description of the first parameter. Each parameter line |
| should be indented by one, preferably two, spaces (as here). |
| parameter2: description of the second |
| parameter that spans two lines. Each additional line should have a |
| hanging indentation of at least one, preferably two, additional spaces (as here). |
| another_parameter (unused, mutable): a parameter may be followed |
| by additional attributes in parentheses |
| |
| Returns: |
| Description of the return value. |
| Should be indented by at least one, preferably two spaces (as here) |
| Can span multiple lines. |
| |
| Deprecated: |
| Optional, description of why the function is deprecated and what should be used instead. |
| """ |
| ``` |
| |
| Docstrings are required for all public functions with at least 5 statements. If a docstring exists |
| it should start with a one-line summary line followed by an empty line. If a docstring is required |
| or it describes some arguments, it should describe all of them. If a docstring is required and |
| the function returns a value, it should be described. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="git-repository"></a>Function `git_repository` is not global anymore |
| |
| * Category name: `git-repository` |
| * Flag in Bazel: [`--incompatible_remove_native_git_repository`](https://github.com/bazelbuild/bazel/issues/6569) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=git-repository` |
| |
| Native `git_repository` and `new_git_repository` functions are removed. |
| Please use the Starlark version instead: |
| |
| ```python |
| load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="http-archive"></a>Function `http_archive` is not global anymore |
| |
| * Category name: `http-archive` |
| * Flag in Bazel: [`--incompatible_remove_native_http_archive`](https://github.com/bazelbuild/bazel/issues/6570) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=http-archive` |
| |
| Native `http_archive` function is removed. |
| Please use the Starlark version instead: |
| |
| ```python |
| load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="integer-division"></a>The `/` operator for integer division is deprecated |
| |
| * Category name: `integer-division` |
| * Flag in Bazel: [`--incompatible_disallow_slash_operator`](https://github.com/bazelbuild/bazel/issues/5823) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=integer-division` |
| |
| The `/` operator is deprecated in favor of `//`, please use the latter for |
| integer division: |
| |
| ```python |
| a = b // c |
| d //= e |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="keyword-positional-params"></a>Keyword parameter should be positional |
| |
| * Category name: `keyword-positional-params` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=keyword-positional-params` |
| |
| Some parameters for builtin functions in Starlark are keyword for legacy reasons; |
| their names are not meaningful (e.g. `x`). Making them positional-only will improve |
| the readability. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="list-append"></a>Prefer using `.append()` to adding a single element list |
| |
| * Category name: `list-append` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=list-append` |
| |
| Transforming `x += [expr]` to `x.append(expr)` avoids a list allocation. |
| NOTE: .append() does not work if the target is a select, hence this warning can safely |
| be ignored or suppressed. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="load"></a>Loaded symbol is unused |
| |
| * Category name: `load` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=load` |
| |
| ### Background |
| |
| [load](https://docs.bazel.build/versions/main/skylark/concepts.html#loading-an-extension) |
| is used to import definitions in a BUILD file. If the definition is not used in |
| the file, the load can be safely removed. If a symbol is loaded two times, you |
| will get a warning on the second occurrence. |
| |
| ### How to fix it |
| |
| Delete the line. When load is used to import multiple symbols, you can remove |
| the unused symbols from the list. To fix your BUILD files automatically, try |
| this command: |
| |
| ```bash |
| $ buildozer 'fix unusedLoads' path/to/BUILD |
| ``` |
| |
| If you want to keep the load, you can disable the warning by adding a comment |
| `# @unused`. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="load-on-top"></a>Load statements should be at the top of the file |
| |
| * Category name: `load-on-top` |
| * Flag in Bazel: [`--incompatible_bzl_disallow_load_after_statement`](https://github.com/bazelbuild/bazel/issues/5815) |
| * Automatic fix: yes |
| * Not supported by the latest version of Buildifier |
| * [Suppress the warning](#suppress): `# buildifier: disable=load-on-top` |
| |
| Obsolete; the warning has been implemented in the formatter and the fix is now automatically applied to all files except `WORKSPACE` files (unless suppressed). |
| |
| Load statements should be first statements (with the exception of `WORKSPACE` files), |
| they can follow only comments and docstrings. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="module-docstring"></a>The file has no module docstring |
| |
| * Category name: `module-docstring` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=module-docstring` |
| |
| `.bzl` files should have docstrings on top of them. A docstring is a string literal |
| (not a comment) which should be the first statement of the file (it may follow |
| comment lines). For example: |
| |
| ```python |
| """ |
| This module contains build rules for my project. |
| """ |
| |
| ... |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="name-conventions"></a>Name conventions |
| |
| * Category name: `name-conventions` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=name-conventions` |
| |
| By convention, all variables should be lower_snake_case, constant should be |
| UPPER_SNAKE_CASE, and providers should be UpperCamelCase ending with `Info`. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-android"></a>All Android build rules should be loaded from Starlark |
| |
| * Category name: `native-android` |
| * Flag in Bazel: [`--incompatible_disable_native_android_rules`](https://github.com/bazelbuild/bazel/issues/8391) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-android` |
| |
| The Android build rules should be loaded from Starlark. |
| |
| Update: the plans for disabling native rules |
| [have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ), |
| at the moment it's not required to load Starlark rules. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-build"></a>The `native` module shouldn't be used in BUILD files |
| |
| * Category name: `native-build` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-build` |
| |
| There's no need in using `native.` in BUILD files, its members are available |
| as global symbols there. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-cc-binary"></a><a name="native-cc-common"></a><a name="native-cc-debug-package-info"></a><a name="native-cc-fdo-prefetch-hints"></a><a name="native-cc-fdo-profile"></a><a name="native-cc-import"></a><a name="native-cc-info"></a><a name="native-cc-library"></a><a name="native-cc-memprof-profile"></a><a name="native-cc-objc-import"></a><a name="native-cc-objc-library"></a><a name="native-cc-propeller-optimize"></a><a name="native-cc-shared-library"></a><a name="native-cc-shared-library-hint-info"></a><a name="native-cc-shared-library-info"></a><a name="native-cc-test"></a><a name="native-cc-toolchain"></a><a name="native-cc-toolchain-suite"></a>All C++ build rules should be loaded from Starlark |
| |
| * Category names: |
| * `native-cc-binary` |
| * `native-cc-common` |
| * `native-cc-debug-package-info` |
| * `native-cc-fdo-prefetch-hints` |
| * `native-cc-fdo-profile` |
| * `native-cc-import` |
| * `native-cc-info` |
| * `native-cc-library` |
| * `native-cc-memprof-profile` |
| * `native-cc-objc-import` |
| * `native-cc-objc-library` |
| * `native-cc-propeller-optimize` |
| * `native-cc-shared-library` |
| * `native-cc-shared-library-hint-info` |
| * `native-cc-shared-library-info` |
| * `native-cc-test` |
| * `native-cc-toolchain` |
| * `native-cc-toolchain-suite` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-cc-binary`, `# buildifier: disable=native-cc-common`, `# buildifier: disable=native-cc-debug-package-info`, `# buildifier: disable=native-cc-fdo-prefetch-hints`, `# buildifier: disable=native-cc-fdo-profile`, `# buildifier: disable=native-cc-import`, `# buildifier: disable=native-cc-info`, `# buildifier: disable=native-cc-library`, `# buildifier: disable=native-cc-memprof-profile`, `# buildifier: disable=native-cc-objc-import`, `# buildifier: disable=native-cc-objc-library`, `# buildifier: disable=native-cc-propeller-optimize`, `# buildifier: disable=native-cc-shared-library`, `# buildifier: disable=native-cc-shared-library-hint-info`, `# buildifier: disable=native-cc-shared-library-info`, `# buildifier: disable=native-cc-test`, `# buildifier: disable=native-cc-toolchain`, `# buildifier: disable=native-cc-toolchain-suite` |
| |
| The C++ build rules should be loaded from @rules_cc. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-cc-proto"></a>cc_proto_library rule should be loaded from Starlark |
| |
| * Category name: `native-cc-proto` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-cc-proto` |
| |
| The cc_proto_library rule should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-binary"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-binary` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-binary` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-common"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-common` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-common` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-import"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-import` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-import` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-info"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-info` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-info` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-library"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-library` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-library` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-lite-proto"></a>java_lite_proto_library rule should be loaded from Starlark |
| |
| * Category name: `native-java-lite-proto` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-lite-proto` |
| |
| The java_lite_proto_library rule should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-package-config"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-package-config` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-package-config` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-plugin"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-plugin` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-plugin` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-plugin-info"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-plugin-info` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-plugin-info` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-proto"></a>java_proto_library rule should be loaded from Starlark |
| |
| * Category name: `native-java-proto` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-proto` |
| |
| The java_proto_library rule should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-runtime"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-runtime` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-runtime` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-test"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-test` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-test` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-java-toolchain"></a>All Java build rules should be loaded from Starlark |
| |
| * Category name: `native-java-toolchain` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-java-toolchain` |
| |
| The Java build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-package"></a>`native.package()` shouldn't be used in .bzl files |
| |
| * Category name: `native-package` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-package` |
| |
| It's discouraged and will be disallowed to use `native.package()` in .bzl files. |
| It can silently modify the semantics of a BUILD file and makes it hard to maintain. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-proto"></a>proto_library rule should be loaded from Starlark |
| |
| * Category name: `native-proto` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-proto` |
| |
| The proto_library rule should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-proto-common"></a>proto_common module should be loaded from Starlark |
| |
| * Category name: `native-proto-common` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-proto-common` |
| |
| The proto_common module should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-proto-info"></a>ProtoInfo provider should be loaded from Starlark |
| |
| * Category name: `native-proto-info` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-proto-info` |
| |
| The ProtoInfo provider should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-proto-lang-toolchain"></a>proto_lang_toolchain rule should be loaded from Starlark |
| |
| * Category name: `native-proto-lang-toolchain` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-proto-lang-toolchain` |
| |
| The proto_lang_toolchain rule should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-proto-lang-toolchain-info"></a>ProtoLangToolchainInfo provider should be loaded from Starlark |
| |
| * Category name: `native-proto-lang-toolchain-info` |
| * Flag in Bazel: [`--incompatible_autoload_externally`](https://github.com/bazelbuild/bazel/issues/23043) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-proto-lang-toolchain-info` |
| |
| The ProtoLangToolchainInfo provider should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-py"></a>All Python build rules should be loaded from Starlark |
| |
| * Category name: `native-py` |
| * Flag in Bazel: [`--incompatible_load_python_rules_from_bzl`](https://github.com/bazelbuild/bazel/issues/9006) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-py` |
| |
| The Python build rules should be loaded from Starlark. |
| |
| Update: the plans for disabling native rules |
| [have been postponed](https://groups.google.com/g/bazel-discuss/c/XNvpWcge4AE/m/aJ-aQzszAwAJ), |
| at the moment it's not required to load Starlark rules. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-sh-binary"></a>sh_binary build rules should be loaded from Starlark |
| |
| * Category name: `native-sh-binary` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-sh-binary` |
| |
| The sh_binary build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-sh-library"></a>sh_library build rules should be loaded from Starlark |
| |
| * Category name: `native-sh-library` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-sh-library` |
| |
| The sh_library build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="native-sh-test"></a>sh_test build rules should be loaded from Starlark |
| |
| * Category name: `native-sh-test` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=native-sh-test` |
| |
| The sh_test build rules should be loaded from Starlark. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="no-effect"></a>Expression result is not used |
| |
| * Category name: `no-effect` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=no-effect` |
| |
| The statement has no effect. Consider removing it or storing its result in a variable. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="out-of-order-load"></a>Load statements should be ordered by their labels |
| |
| * Category name: `out-of-order-load` |
| * Automatic fix: yes |
| * Not supported by the latest version of Buildifier |
| * [Suppress the warning](#suppress): `# buildifier: disable=out-of-order-load` |
| |
| Obsolete; the warning has been implemented in the formatter and the fix is now automatically applied to all files (unless suppressed). |
| |
| Load statements should be ordered by their first argument - extension file label. |
| This makes it easier to developers to locate loads of interest and reduces chances |
| for conflicts when performing large-scale automated refactoring. |
| |
| When applying automated fixes, it's highly recommended to also use |
| [`load-on-top`](#load-on-top) fixes, since otherwise the relative order |
| of a symbol load and its usage can change resulting in runtime error. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="output-group"></a>`ctx.attr.dep.output_group` is deprecated |
| |
| * Category name: `output-group` |
| * Flag in Bazel: [`--incompatible_no_target_output_group`](https://github.com/bazelbuild/bazel/issues/7949) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=output-group` |
| |
| The `output_group` field of a target is deprecated in favor of the |
| [`OutputGroupInfo` provider](https://docs.bazel.build/versions/main/skylark/lib/OutputGroupInfo.html). |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="overly-nested-depset"></a>The depset is potentially overly nested |
| |
| * Category name: `overly-nested-depset` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=overly-nested-depset` |
| |
| If a depset is iteratively chained in a for loop, e.g. the following pattern is used: |
| |
| ```python |
| for ...: |
| x = depset(..., transitive = [..., x, ...]) |
| ``` |
| |
| this can result in an overly nested depset with a long chain of transitive elements. Such patterns |
| can lead to performance problems, consider refactoring the code to create a flat list of transitive |
| elements and call the depset constructor just once: |
| |
| ```python |
| transitive = [] |
| |
| for ...: |
| transitive += ... |
| |
| x = depset(..., transitive = transitive) |
| ``` |
| |
| Or in simple cases you can use list comprehensions instead: |
| |
| ```python |
| x = depset(..., transitive = [y.deps for y in ...]) |
| ``` |
| |
| For more information, read Bazel documentation about |
| [depsets](https://docs.bazel.build/versions/main/skylark/depsets.html) |
| and |
| [reducing the number of calls to depset](https://docs.bazel.build/versions/main/skylark/performance.html#reduce-the-number-of-calls-to-depset). |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="package-name"></a>Global variable `PACKAGE_NAME` is deprecated |
| |
| * Category name: `package-name` |
| * Flag in Bazel: [`--incompatible_package_name_is_a_function`](https://github.com/bazelbuild/bazel/issues/5827) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=package-name` |
| |
| The global variable `PACKAGE_NAME` is deprecated, please use |
| [`native.package_name()`](https://docs.bazel.build/versions/main/skylark/lib/native.html#package_name) |
| instead. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="package-on-top"></a>Package declaration should be at the top of the file |
| |
| * Category name: `package-on-top` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=package-on-top` |
| |
| Here is a typical structure of a BUILD file: |
| |
| * `load()` statements |
| * `package()` |
| * calls to rules, macros |
| |
| Instantiating a rule and setting the package defaults later can be very |
| confusing, and has been a source of bugs (tools and humans sometimes believe |
| package applies to everything in a BUILD file). This might become an error in |
| the future. |
| |
| ### What can be used before package()? |
| |
| The linter allows the following to be before `package()`: |
| |
| * comments |
| * `load()` |
| * variable declarations |
| * `package_group()` |
| * `licenses()` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="positional-args"></a>Keyword arguments should be used over positional arguments |
| |
| * Category name: `positional-args` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=positional-args` |
| |
| All top level calls (except for some built-ins) should use keyword args over |
| positional arguments. Positional arguments can cause subtle errors if the order |
| is switched or if an argument is removed. Keyword args also greatly improve |
| readability. |
| |
| ```diff |
| - my_macro("foo", "bar") |
| + my_macro(name = "foo", env = "bar") |
| ``` |
| |
| The linter allows the following functions to be called with positional arguments: |
| |
| * `load()` |
| * `vardef()` |
| * `export_files()` |
| * `licenses()` |
| * `print()` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="print"></a>`print()` is a debug function and shouldn't be submitted |
| |
| * Category name: `print` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=print` |
| |
| Using the `print()` function for warnings is discouraged: they are often spammy and |
| non actionable, the people who see the warning are usually not the people who can |
| fix the code to make the warning disappear, and the actual maintainers of the code |
| may never see the warning. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="provider-params"></a>Calls to `provider` should specify a list of fields and a documentation |
| |
| * Category name: `provider-params` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=provider-params` |
| |
| Calls to `provider` should specify a documentation string and a list of fields: |
| |
| ```python |
| ServerAddressInfo = provider( |
| "The address of an HTTP server. Fields are host (string) and port (int).", |
| fields = ["host", "port"] |
| ) |
| ``` |
| |
| Fields should also be documented when needed: |
| |
| ```python |
| ServerAddressInfo = provider( |
| "The address of an HTTP server.", |
| fields = { |
| "host": "string, e.g. 'example.com'", |
| "port": "int, a TCP port number", |
| } |
| ) |
| ``` |
| |
| Note that specifying a list of fields is a breaking change. It is an error if a |
| call to the provider uses undeclared fields. If you cannot declare the list of |
| fields, you may explicitly set it to None (and explain why in a comment). |
| |
| ```python |
| AllInfo = provider("This provider accepts any field.", fields = None) |
| |
| NoneInfo = provider("This provider cannot have fields.", fields = []) |
| ``` |
| |
| See the [documentation for providers](https://docs.bazel.build/versions/main/skylark/lib/globals.html#provider). |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="redefined-variable"></a>Variable has already been defined |
| |
| * Category name: `redefined-variable` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=redefined-variable` |
| |
| ### Background |
| |
| In .bzl files, redefining a global variable is already forbidden. This helps |
| both humans and tools reason about the code. For consistency, we want to bring |
| this restriction also to BUILD files. |
| |
| ### How to fix it |
| |
| Rename one of the variables. |
| |
| Note that the content of lists and dictionaries can still be modified. We will |
| forbid reassignment, but not every side-effect. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="repository-name"></a>Global variable `REPOSITORY_NAME` is deprecated |
| |
| * Category name: `repository-name` |
| * Flag in Bazel: [`--incompatible_package_name_is_a_function`](https://github.com/bazelbuild/bazel/issues/5827) |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=repository-name` |
| |
| The global variable `REPOSITORY_NAME` is deprecated, please use |
| [`native.repository_name()`](https://docs.bazel.build/versions/main/skylark/lib/native.html#repository_name) |
| instead. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="return-value"></a>Some but not all execution paths of a function return a value |
| |
| * Category name: `return-value` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=return-value` |
| |
| Some but not all execution paths of a function return a value. Either there's |
| an explicit empty `return` statement, or an implicit return in the end of a |
| function. If it is intentional, make it explicit using `return None`. If you |
| know certain parts of the code cannot be reached, add the statement |
| `fail("unreachable")` to them. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="rule-impl-return"></a>Avoid using the legacy provider syntax |
| |
| * Category name: `rule-impl-return` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=rule-impl-return` |
| |
| Returning structs from rule implementation functions is |
| [deprecated](https://docs.bazel.build/versions/main/skylark/rules.html#migrating-from-legacy-providers), |
| consider using |
| [providers](https://docs.bazel.build/versions/main/skylark/rules.html#providers) |
| or lists of providers instead. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="same-origin-load"></a>Same label is used for multiple loads |
| |
| * Category name: `same-origin-load` |
| * Automatic fix: yes |
| * Not supported by the latest version of Buildifier |
| * [Suppress the warning](#suppress): `# buildifier: disable=same-origin-load` |
| |
| Obsolete; the warning has been implemented in the formatter and the fix is now automatically applied to all files except `WORKSPACE` files (unless suppressed). |
| |
| ### Background |
| |
| [load](https://docs.bazel.build/versions/main/skylark/concepts.html#loading-an-extension) |
| is used to import definitions in a BUILD file. If the same label is used for loading |
| symbols more the ones, all such loads can be merged into a single one. |
| |
| ### How to fix it |
| |
| Merge all loads into a single one. For example, |
| |
| ```python |
| load(":f.bzl", "s1") |
| load(":f.bzl", "s2") |
| ``` |
| |
| can be written more compactly as |
| |
| ```python |
| load(":f.bzl", "s1", "s2") |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="skylark-comment"></a><a name="skylark-docstring"></a>"Skylark" is an outdated name of the language, please use "starlark" instead |
| |
| * Category names: |
| * `skylark-comment` |
| * `skylark-docstring` |
| * Automatic fix: yes |
| * [Suppress the warning](#suppress): `# buildifier: disable=skylark-comment`, `# buildifier: disable=skylark-docstring` |
| |
| The configuration language for Bazel is called "Starlark" now, the name "Skylark" is |
| outdated and shouldn't be used. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="string-iteration"></a>String iteration is deprecated |
| |
| * Category name: `string-iteration` |
| * Flag in Bazel: [`--incompatible_string_is_not_iterable`](https://github.com/bazelbuild/bazel/issues/5830) |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=string-iteration` |
| |
| Iteration over strings often leads to confusion with iteration over a sequence of strings, |
| therefore strings won't be recognized as sequences of 1-element strings (like in Python). |
| Use string indexing and `len` instead: |
| |
| ```python |
| my_string = "hello world" |
| for i in range(len(my_string)): |
| char = my_string[i] |
| # do something with char |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="uninitialized"></a>Variable may not have been initialized |
| |
| * Category name: `uninitialized` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=uninitialized` |
| |
| The local value can be not initialized at the time of execution. It may happen if it's |
| initialized in one of the if-else clauses but not in all of them, or in a for-loop which |
| can potentially be empty. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="unnamed-macro"></a>The macro should have a keyword argument called "name" |
| |
| * Category name: `unnamed-macro` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=unnamed-macro` |
| |
| By convention all macro functions should have a keyword argument called `name` |
| (even if they don't use it). This is important for tooling and automation. |
| |
| A macro is a function that calls a rule (either directly or indirectly by calling other |
| macros). |
| |
| If this function is a helper function that's not supposed to be used outside of its file, |
| please make it private (rename it so that the name starts with `_`), this will |
| prevent loading the function from BUILD files and suppress the warning. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="unreachable"></a>The statement is unreachable |
| |
| * Category name: `unreachable` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=unreachable` |
| |
| The statement is unreachable because it follows a `return`, `break`, `continue`, |
| or `fail()` statement. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="unsorted-dict-items"></a>Dictionary items should be ordered by their keys |
| |
| * Category name: `unsorted-dict-items` |
| * Automatic fix: yes |
| * [Disabled by default](buildifier/README.md#linter) |
| * [Suppress the warning](#suppress): `# buildifier: disable=unsorted-dict-items` |
| |
| Dictionary items should be sorted lexicographically by their keys. This makes |
| it easier to find the item of interest and reduces chances of conflicts when |
| performing large-scale automated refactoring. |
| |
| The order is affected by `NamePriority` dictionary passed using `-tables` or |
| `-add_tables` flags. |
| |
| If you want to preserve the original dictionary items order, you can disable |
| the warning by adding a comment `# @unsorted-dict-items` to the dictionary |
| expression or any of its enclosing expressions (binary, if etc). For example, |
| |
| ```python |
| # @unsorted-dict-items |
| d = { |
| "b": "bvalue", |
| "a": "avalue", |
| } |
| ``` |
| |
| will not be reported as an issue because the assignment operation that uses |
| the dictionary with unsorted items has a comment disabling this warning. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## <a name="unused-variable"></a>Variable is unused |
| |
| * Category name: `unused-variable` |
| * Automatic fix: no |
| * [Suppress the warning](#suppress): `# buildifier: disable=unused-variable` |
| |
| This happens when a variable or function is set but not used in the file, e.g. |
| |
| ```python |
| x = [1, 2] |
| ``` |
| |
| The line can often be safely removed. |
| |
| If you want to keep the variable, you can disable the warning by adding a |
| comment `# @unused`. |
| |
| ```python |
| x = [1, 2] # @unused |
| |
| # @unused |
| def f( |
| x, |
| y, # @unused |
| ): |
| pass |
| ``` |
| |
| If an unused variable is used for partially unpacking tuples, just prefix |
| its name with an underscore to suppress the warning: |
| |
| ```python |
| x, _y = foo() |
| for _, (a, _b) in iterable: |
| print(a + x) |
| ``` |
| |
| The same applies for function arguments that are not used by design: |
| |
| ```python |
| def foo(a, _b, *_args): |
| return bar(a) |
| ``` |
| |
| If a tuple is unpacked not in a for-loop and all variables are unused, |
| it'll still trigger a warning, even if all variables are underscored: |
| |
| ```python |
| _a, _b = pair |
| _unused = 3 |
| ``` |
