The setup

Chapter one's Makefile read a file it never declared. Nothing stopped it, so the build went quietly wrong. Let us make the same mistake on purpose, in Go, under a system that checks.

Go has a facility for baking a file into a binary at compile time. Point it at a file and its contents become a string constant:

package greeting

import (
	_ "embed"
	"fmt"
)

// The name comes from a file next to this source. go build finds it,
// because go build can read anything in the directory.
//
//go:embed name.txt
var name string

// Greet builds the message the server prints.
func Greet() string {
	return fmt.Sprintf("Hello %s", name)
}

The declaration is unchanged from chapter three — it lists the Go source, and nothing else:

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

go_library(
    name = "greeting",
    srcs = ["greeting.go"],
    importpath = "example.com/greet/server/greeting",
    visibility = ["//server:__subpackages__"],
)

This is precisely chapter one's mistake, transplanted. The compile step reads two files. One of them is declared.

Your own tools are fine with this

Before running the build, check what Go itself thinks:

$ go build -o /tmp/greet ./server/
$ /tmp/greet
Hello world

No error. No warning. The binary works. If you stopped here you would have no reason to suspect anything, which is exactly how chapter one's bug ships.

The build refuses

Now the same source, same compiler version, under the build system:

$ bazel build //server
ERROR: GoCompilePkg server/greeting/greeting.a failed: (Exit 1)
compilepkg: greeting.go:11:12: could not embed name.txt: no matching files found
ERROR: Build did NOT complete successfully

Read that error again with chapter one in mind. no matching files found — for a file that exists, spelled correctly, in the right directory.

The compiler is not confused. It is telling the truth about the place it was run.

Look inside

The build did not run the compiler in your directory. It ran it in a sandbox: a temporary directory containing exactly the files that target declared, and nothing else. Ask for that sandbox to be kept after the failure:

$ bazel build //server --sandbox_debug
...
$ ls <sandbox>/server/greeting/
greeting.go

One file.

name.txt is two directories away on your real disk and it is not here, because nothing declared it. The compiler did not fail to find a file it should have found — it correctly reported that the file was absent from the only world it could see.

The fix is one line

Tell the build about the file:

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__"],
)

$ bazel build //...
INFO: Build completed successfully, 38 total actions

$ bazel run //server
Hello world

One line of configuration. That is the entire cost of the guarantee.

The other half: a file that is there

A missing file is the loud version. Here is the quiet one, and it is the reason the sandbox scrubs more than the filesystem.

Suppose a build step stamps who built it. The shell way:

$ cat stamp.sh
echo "built-by=${BUILD_USER:-unknown}"

$ BUILD_USER=alice sh stamp.sh
built-by=alice

That works, and it is a trap. The output depends on a value that appears nowhere in the repository. Run it yourself and get alice; a colleague runs the identical command on the identical commit and gets their own name, or unknown, and neither of you has any reason to suspect the other saw something different.

Now the same command as a build step:

genrule(
    name = "build_tag",
    outs = ["build_tag.txt"],
    cmd = "echo \"built-by=$${BUILD_USER:-unknown}\" > $@",
)

$ BUILD_USER=alice bazel build //stamp:build_tag
$ cat bazel-bin/stamp/build_tag.txt
built-by=unknown

The sandbox is not only a directory. It is also an environment, and by default it contains almost nothing. Your shell's variables are exactly as undeclared as name.txt was, and they are refused the same way — except that here the refusal is silent, because an unset variable is a legal thing for a command to encounter.

Declaring an input that is not a file

If the stamp genuinely needs that value, say so:

$ BUILD_USER=alice bazel build //stamp:build_tag --action_env=BUILD_USER
$ cat bazel-bin/stamp/build_tag.txt
built-by=alice

And now the interesting part. Change the value and rebuild:

$ BUILD_USER=bob bazel build //stamp:build_tag --action_env=BUILD_USER
$ cat bazel-bin/stamp/build_tag.txt
built-by=bob

That is why the earlier chapters kept insisting the compiler is an input. It was never a special case. It is the same rule applied to a thing that does not look like a file, and this is the same rule again applied to a thing that is not even on disk.

Why this is worth the trouble

It is fair to object that the failure was annoying and Go managed fine. So it is worth being clear about what was bought.

The undeclared read was already a bug. It was a bug in chapter one and it is a bug here — a step whose real inputs differ from its declared ones, which means the build cannot know when its output is stale. Go did not fix that bug; it just did not mention it.

What changed is when you find out. Under Make you find out months later, on someone else's machine, as a wrong answer with no error message. Here you find out immediately, on your own machine, while you still remember what you were doing — with an error naming the exact file.

And it composes. Every action in the graph gets the same treatment, so the property holds for the whole build rather than the parts someone remembered to check. That is what makes the next part possible: once every step's inputs are genuinely known, the build can start reusing work across machines, because it can tell when two pieces of work are the same.

Try this in your own repository

Run a build step in an empty room. Copy one step's declared inputs into a fresh directory and run just that step there. Whatever fails is an undeclared input, and the list you get is usually longer than expected — configuration files, a lockfile, a certificate, an environment variable set by a shell profile.

Audit what your CI environment provides. List every environment variable your build reads. For each, ask what happens if it is unset, and whether anybody would notice. A variable that silently changes the output is the failure in this chapter, waiting.

What you can now do

Diagnose a build failure caused by an undeclared input, inspect the sandbox to see what a step could actually reach, and declare data files a compiler reads. Part one is complete: you have a build whose graph is enforced rather than promised. Part two is about the language you write that graph in.