The attribute you have been ignoring

Since chapter three, every library declaration has carried a line you have had no reason to think about:

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "greeting",
    srcs = ["greeting.go"],
    # go:embed reads this file, so the build has to be told about it.
    # Without this line the compiler cannot see it, even though it sits
    # right next to greeting.go on disk.
    embedsrcs = ["name.txt"],
    importpath = "example.com/greet/server/greeting",
    visibility = ["//server:__subpackages__"],
)

With one consumer, that line does nothing you can observe. It is the kind of boilerplate you copy from the target above and stop seeing.

Give the workspace a second consumer and it wakes up.

A perfectly reasonable mistake

Suppose you want a small command-line tool alongside the server. It should print the same greeting, and there is already a package that builds greetings, so you reach for it:

package main

import (
	"fmt"

	"example.com/greet/server/greeting"
)

func main() {
	fmt.Println(greeting.Greet())
}

load("@rules_go//go:def.bzl", "go_binary", "go_library")

go_library(
    name = "hello_lib",
    srcs = ["main.go"],
    importpath = "example.com/greet/cmd/hello",
    deps = ["//server/greeting"],
)

go_binary(
    name = "hello",
    embed = [":hello_lib"],
)

This is not a contrived error. It is the most natural thing in the world: the code you need exists, you import it, you move on. In most build systems that is the end of the story and the second caller is now a fact.

The build says no

$ bazel build //cmd/hello
ERROR: in go_library rule //cmd/hello:hello_lib: Visibility error:
target '//server/greeting:greeting' is not visible from
target '//cmd/hello:hello_lib'
Recommendation: modify the visibility declaration if you think the
dependency is legitimate. For more info see
https://bazel.build/concepts/visibility

Notice what the error does not say. It does not say you did something wrong. It says this dependency is not currently allowed, and that if you think it should be, the way to say so is to change the declaration.

The build is not making an architectural judgement. It is telling you that one is required, and that you are the one who has to make it.

The choice

You now have two ways forward, and the difference between them is the actual content of this chapter.

Name the new consumer. The greeting package grows its list to say that //cmd may also use it:

load("@rules_go//go:def.bzl", "go_library")

go_library(
    name = "greeting",
    srcs = ["greeting.go"],
    # go:embed reads this file, so the build has to be told about it.
    # Without this line the compiler cannot see it, even though it sits
    # right next to greeting.go on disk.
    embedsrcs = ["name.txt"],
    importpath = "example.com/greet/server/greeting",
    # //cmd/hello needs this too, so the package list grows to name it.
    # Widening to //visibility:public would work and would also stop the
    # build system from ever asking this question again.
    visibility = [
        "//cmd:__subpackages__",
        "//server:__subpackages__",
    ],
)

Or widen it to everything. visibility = ["//visibility:public"] also fixes the error, in less typing, and permanently. The build will never ask again — about this consumer or any future one.

Both compile. The second is faster today and costs you the mechanism. Once a target is public, "who depends on this?" becomes a question you answer by searching rather than by reading, and the next person to add a consumer gets no prompt to think about whether they should.

What public actually costs

The two options both compile, so the argument for one over the other has to be about something else. Here it is, concretely.

Suppose a second team adds a reporting tool somewhere else in the tree and reaches for the same internal package:

$ bazel build //vendor/report
ERROR: in go_library rule //vendor/report:report_lib: Visibility error:
target '//server/greeting:greeting' is not visible from
target '//vendor/report:report_lib'

Refused, as expected. Now take the quick way out:

$ bazel build //vendor/report
INFO: Build completed successfully, 15 total actions

$ bazel run //vendor/report
Hello world

It works. Nothing is broken, no test fails, and the reviewer sees a one-line diff that makes a build error go away.

Here is what it cost. Ask the file who is allowed to depend on this package:

visibility = ["//visibility:public"],

visibility = [
    "//server:__subpackages__",
    "//vendor/report:__pkg__",
],

Same build, same binary, same output. The difference is that one of these files still knows something and the other has forgotten.

Why the list is the better default

The listing version has a property the public version does not: it tells you something true when you read it later. A visibility list is a record of every part of the repository that was allowed in, and each entry was added by somebody who had to justify it at least to themselves.

That makes the reverse question cheap. Chapter three showed rdeps answering "what depends on this" from the graph. Visibility answers a different question — "what is permitted to depend on this" — and it answers it from a single file you can read in five seconds.

The two together are what makes a large repository navigable. One tells you what the code does; the other tells you what it was meant to do.

Boundaries you can move on purpose

The thing worth internalizing is that this boundary is movable. It is not a wall someone built once; it is a line in a file that changes when the design changes, with a build failure marking every moment it does.

That is a good property for architecture to have. It means the design is written down in a form that cannot silently rot, and that the moments it changes are visible in your history rather than lost in the diff of whoever needed one more import.

Try this in your own repository

Find a package with more consumers than it was designed for. Something written for one caller that now has six. Ask each caller whether they needed the whole thing or one function — the second answer means the boundary is in the wrong place, not that the package should be public.

Try to write down your intended boundaries. Not the ones the code has; the ones you would defend. Anywhere the two disagree is either a boundary worth enforcing or an intention worth abandoning, and it is worth deciding which.

What you can now do

Read a visibility declaration and say who may depend on the target, diagnose a visibility error, and make the boundary decision deliberately rather than by reflex. The next chapter looks at the BUILD files themselves, which have started to repeat.