## Overview

The Fuchsia project follows the official Bazel
[.bzl Style Guide](https://bazel.build/rules/bzl-style), with a few exceptions.
The guidance on this page is in addition to the
[common Bazel style guide and best practices](https://fuchsia.dev/fuchsia-src/development/languages/bazel/style/common).

`.bzl` files are most often used for
[Defining rules, macros, and functions](https://fuchsia.dev/fuchsia-src/development/languages/bazel/style/rules_macros), for which there is
additional guidance.

This page is part of the
[Bazel style guide and best practices](https://fuchsia.dev/fuchsia-src/development/languages/bazel/style/README).

## Visibility

### Load visibility

Unlike `.gni` files, `.bzl` files support
[load visibility](https://bazel.build/concepts/visibility#load-visibility) to restrict from where they
can be loaded. By default, there are no restrictions.

Always specify `visibility` in `.bzl` files
*\[SHAC error\]*:

- Use `visibility("private")` for any `.bzl` files not specifically intended for
  use outside the package.

  - Especially when a package contains a mix of public and private `.bzl` files, it may make sense to put the latter in a `private/` directory. Bazel has mechanisms to restrict loading of files in such directories.
- Otherwise, use `visibility([...])` to specify the packages (directories) that
  may use it.

Load `visibility` uses a different syntax than target `visibility`:

- Just the path is the equivalent of `:__pkg__`.

- The path followed by `/...` is the equivalent of `:__subpackages__`.

For very common targets truly meant to be used across the code base, `"//..."`
may be used. [Do not use public visibility](https://fuchsia.dev/fuchsia-src/development/languages/bazel/style/common#do-not-use-public-visibility)
(`visibility("public")`) *\[SHAC error\]* . In
most cases, though, a set of top-level and/or second-level directories (e.g.,
`"//src/..."` and `"//sdk/lib/..."`) is sufficient.

### Symbol visibility

Within `.bzl` files, prefix symbol names with an underscore to restrict access
to within the `.bzl` file, preventing use by other files even within the same
package (directory).

## Do not create defs.bzl files

Though you may see them, especially in third-party repositories, defining or
exporting multiple symbols that are not certain to be used together, as is
often the case in `defs.bzl` files, is an anti-pattern. See
[Limit the symbols exported by each `.bzl`
file](https://bazel.build/build/style-guide#limit-symbols). In all cases,
choose a more descriptive file name.
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/languages/bazel/style/bzl_files.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/languages/bazel/style/bzl_files.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/languages/bazel/style/bzl_files.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/languages/bazel/style/bzl_files.md "Edit the source code of this page")