Cuts the Go make test recipe, which repeats the command in examples/go.Dockerfile, and turns its notes into three key points; drops key points stated elsewhere (the no-op copies and the last stage under Dockerfile, when Docker installs again under Docker's cache, the Python layer under the Python section) and "BuildKit runs stages in parallel"; every rule stays. Model: opus-5-5
This commit is contained in:
1 parent
c166d20195
commit
e3f3160fad
1 file changed
+30
-66
+30
-66
@@ -388,38 +388,26 @@ style conventions are in separate documents:
|
||||
A green run alone shows neither that the check ran nor that it covers what
|
||||
it should.
|
||||
|
||||
## Canonical Go `Dockerfile`
|
||||
|
||||
- **The gate phases are separate stages, and the build stage depends on both.**
|
||||
The lint phase is based on the `golangci/golangci-lint` image (pinned by
|
||||
hash), so lint failures surface in seconds rather than after a full compile.
|
||||
The test phase is based on the Debian Go image. The canonical Go repo
|
||||
`Dockerfile` is at
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`.
|
||||
That image has both Go and the linter, so nothing needs installing. The test
|
||||
phase is based on the Debian Go image.
|
||||
|
||||
The canonical Go `Dockerfile` is at
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`.
|
||||
|
||||
Key points:
|
||||
- The lint phase uses the `golangci/golangci-lint` image directly, so
|
||||
nothing needs installing: it has both Go and the linter.
|
||||
- `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
|
||||
purpose is the dependency on that phase. BuildKit runs stages in parallel
|
||||
by default, and a stage nothing depends on is not built at all. Without
|
||||
these two lines a red gate would not fail the build.
|
||||
- Keep the runtime stage last. If you add a stage after it, give it the same
|
||||
two copies. A plain `docker build .` builds the last stage's chain and
|
||||
nothing else.
|
||||
- Check builds keep these, and none of them can hand back a stale result:
|
||||
- The layers of the system packages and Go's modules. Docker installs
|
||||
the packages again when the base image or the install line changes.
|
||||
Docker downloads the modules again when `go.mod` or `go.sum` changes.
|
||||
Go checks every module against `go.sum` as it downloads it, and no
|
||||
later build can change a kept layer. The modules are kept in a layer
|
||||
rather than a cache mount. A cache mount is shared by every build on
|
||||
the host, and Go builds from whatever files the mount holds without
|
||||
checking them again (only `go mod verify` does). A file changed there
|
||||
would go unnoticed.
|
||||
- The layers of the system packages and Go's modules. Go checks every
|
||||
module against `go.sum` as it downloads it, and no later build can
|
||||
change a kept layer.
|
||||
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for
|
||||
root), mounted on the steps that compile: `golangci-lint run`, both
|
||||
`go test` runs and `go build`. Go reuses a compiled package only when
|
||||
all its inputs are unchanged. The cache also holds test results, which
|
||||
is why both `go test` runs carry `-count=1`.
|
||||
all its inputs are unchanged.
|
||||
- golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned
|
||||
image keeps it), mounted on `golangci-lint run`. golangci-lint reuses
|
||||
a package's findings only when all of these are unchanged:
|
||||
@@ -427,9 +415,10 @@ style conventions are in separate documents:
|
||||
- `go.mod`
|
||||
- the linters and their settings in `.golangci.yml`
|
||||
- the golangci-lint version
|
||||
- In a Python `test` phase, the layer of the step that runs
|
||||
`script/bootstrap` to install the packages from `Pipfile.lock`, as
|
||||
described for that phase below.
|
||||
- The modules are kept in a layer rather than a cache mount. A cache mount
|
||||
is shared by every build on the host, and Go builds from whatever files
|
||||
the mount holds without checking them again (only `go mod verify` does). A
|
||||
file changed there would go unnoticed.
|
||||
- If the project uses `//go:embed` directives that reference build
|
||||
artifacts, the lint phase must create placeholder files so the embed
|
||||
directives resolve. A web frontend compiled in a separate stage is such an
|
||||
@@ -445,46 +434,21 @@ style conventions are in separate documents:
|
||||
base image or the install line changes. The first lines of a lint phase
|
||||
that installs system libraries are at
|
||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`.
|
||||
|
||||
Go example:
|
||||
|
||||
```makefile
|
||||
test:
|
||||
@status=0; \
|
||||
output=$$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$$?; \
|
||||
printf '%s\n' "$$output"; \
|
||||
test "$$status" -eq 0 && exit 0; \
|
||||
case "$$output" in \
|
||||
*"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \
|
||||
esac; \
|
||||
echo "--- Rerunning with -v for details ---"; \
|
||||
go test -count=1 -timeout 90s -race -v ./...; \
|
||||
exit 1
|
||||
```
|
||||
|
||||
The first run's output is kept so that the recipe can look in it for what Go
|
||||
prints for a hang:
|
||||
- `panic: test timed out` means the test's own timer fired.
|
||||
- `*** Test killed` means `go test` stopped a test that ignored that timer,
|
||||
about a minute later.
|
||||
|
||||
Go prints the goroutine stacks with either line, as long as the test can
|
||||
still respond. A rerun would only wait for the same hang, so the recipe
|
||||
exits 1. A failure with neither line in its output reruns with `-v`. The
|
||||
kept output prints when the first run ends, not while it runs.
|
||||
|
||||
`-count=1` is required on both invocations. It defeats Go's test _result_
|
||||
cache, so neither run can report a stored pass in place of running the
|
||||
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
||||
and no recompilation.
|
||||
|
||||
That cache is Go's own, separate from Docker's layer cache. Go stores a
|
||||
passing result in its cache directory (`GOCACHE`). When the same tests run
|
||||
again on unchanged code, it prints that result, marked `(cached)`, without
|
||||
running them. The directory lasts from one run to the next on a developer's
|
||||
machine, where this target runs. The directory also lasts in the `test`
|
||||
phase of the `Dockerfile`, which mounts it to keep compiled packages between
|
||||
check builds, so the phase's `go test` runs carry `-count=1` too.
|
||||
- The test command keeps the first run's output, to look in it for what Go
|
||||
prints for a hang. `panic: test timed out` means the test's own timer
|
||||
fired. `*** Test killed` means `go test` stopped a test that ignored that
|
||||
timer, about a minute later. Go prints the goroutine stacks with either
|
||||
line, as long as the test can still respond. On either line the command
|
||||
exits 1 without a rerun. A failure with neither line reruns with `-v`. The
|
||||
kept output prints when the first run ends, not while it runs.
|
||||
- `-count=1` is required on both `go test` invocations. Go stores a passing
|
||||
result in its cache directory (`GOCACHE`). When the same tests run again
|
||||
on unchanged code, it prints that result, marked `(cached)`, without
|
||||
running them. That directory lasts between runs on a developer's machine,
|
||||
and in the `test` phase, which mounts it to keep compiled packages.
|
||||
- `-count=1` defeats only that test _result_ cache. It leaves the build
|
||||
cache alone, so it costs the runtime of the suite and no recompilation.
|
||||
The cache is Go's own, separate from Docker's layer cache.
|
||||
|
||||
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it
|
||||
before `COPY . .`, so check builds keep them.** The steps are:
|
||||
|
||||
Reference in new issue
Block a user