Bazel Knowledge Hub

0.3.7 Aliases

recommended

alias() gives an existing target a stable second label. It does not create another implementation or copy the underlying files. Other packages can depend on that handle even if the real target later moves, gets renamed, or already sits behind a long label.1

alias(
    name = "my_lib",
    actual = "//path/to/real:lib",
)

In the example above, other targets can depend on //path/to:my_lib instead of //path/to/real:lib.1 The visible label and the underlying target are different names that lead to the same implementation.1

The Two Attributes To Notice

The syntax is small. name gives the alias its own label in the current package, and actual points at the target it redirects to.1 An alias can also declare its own visibility, so the access-control rules from 0.2.4 Visibility still matter when you expose a target under an alternate name.1

Why This Rule Exists

The value of alias() is indirection. If a package wants one stable public label while the real implementation target changes over time, an alias keeps consumers decoupled from that internal churn.1 That is why it helps with renames, refactors, and package APIs that want a cleaner public entry point than the underlying target path.1

The separate file-collection case is covered in 0.3.6 filegroup Rule.1

If a package does not naturally have an eponymous default target, alias() can also create one.2 That connects back to the shorthand rules in 0.2.2 Syntactic Sugar & Relative Labels: one label stands in for another target.2

extra

A Legacy Pattern You May Still See

During Bzlmod migration, alias() replaces old bind() entries from WORKSPACE.3 Instead of keeping dependents on //external:openssl, you define a normal alias in a regular package and move callers to that package-local label.3

alias(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)
key takeaway

An alias is a stable label that points at an existing target. When you see alias(), read it as a small indirection layer in the target graph: consumers depend on the alias name, and the alias forwards them to the real thing. That makes renames, refactors, and cleaner package interfaces cheaper without changing the underlying implementation.1

Check your understanding · 2 questions

1.What does alias() actually create in the Bazel build graph?

Select one answer

2.True or false: when and how alias() is used.

Choose True or False for each sentence

alias() can declare its own visibility, independent of the underlying target's visibility.
When the actual target in an alias() is renamed or moved, all consumers that reference the alias must update their BUILD files.
alias() can be used to create an eponymous default target when no natural one exists in a package.
The Bzlmod migration guide recommends alias() as a replacement for legacy bind() entries from WORKSPACE.
0 of 2 answered

Footnotes

  1. Ultimate Monorepo and Bazel for Building Apps at Scale — alias as redirect/pointer, name and actual, optional visibility, and stable-name/refactor use cases ↩1 ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9

  2. Bazel Training 101 (Part 9): Packages, Rules, Targets, and Labels — using alias() to create a package default target when no natural eponymous target exists ↩1 ↩2

  3. Bzlmod Migration Guide — replacing legacy bind() entries with a normal alias() target in a regular package ↩1 ↩2

← Previousfilegroup RuleNext →select() Awareness