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
+28
-64
+28
-64
@@ -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
|
A green run alone shows neither that the check ran nor that it covers what
|
||||||
it should.
|
it should.
|
||||||
|
|
||||||
|
## Canonical Go `Dockerfile`
|
||||||
|
|
||||||
- **The gate phases are separate stages, and the build stage depends on both.**
|
- **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
|
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.
|
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
|
That image has both Go and the linter, so nothing needs installing. The test
|
||||||
`Dockerfile` is at
|
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`.
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`.
|
||||||
|
|
||||||
Key points:
|
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:
|
- 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 layers of the system packages and Go's modules. Go checks every
|
||||||
the packages again when the base image or the install line changes.
|
module against `go.sum` as it downloads it, and no later build can
|
||||||
Docker downloads the modules again when `go.mod` or `go.sum` changes.
|
change a kept layer.
|
||||||
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.
|
|
||||||
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for
|
- Go's build cache (`/root/.cache/go-build`, where Go keeps it for
|
||||||
root), mounted on the steps that compile: `golangci-lint run`, both
|
root), mounted on the steps that compile: `golangci-lint run`, both
|
||||||
`go test` runs and `go build`. Go reuses a compiled package only when
|
`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
|
all its inputs are unchanged.
|
||||||
is why both `go test` runs carry `-count=1`.
|
|
||||||
- golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned
|
- golangci-lint's cache (`/root/.cache/golangci-lint`, where the pinned
|
||||||
image keeps it), mounted on `golangci-lint run`. golangci-lint reuses
|
image keeps it), mounted on `golangci-lint run`. golangci-lint reuses
|
||||||
a package's findings only when all of these are unchanged:
|
a package's findings only when all of these are unchanged:
|
||||||
@@ -427,9 +415,10 @@ style conventions are in separate documents:
|
|||||||
- `go.mod`
|
- `go.mod`
|
||||||
- the linters and their settings in `.golangci.yml`
|
- the linters and their settings in `.golangci.yml`
|
||||||
- the golangci-lint version
|
- the golangci-lint version
|
||||||
- In a Python `test` phase, the layer of the step that runs
|
- The modules are kept in a layer rather than a cache mount. A cache mount
|
||||||
`script/bootstrap` to install the packages from `Pipfile.lock`, as
|
is shared by every build on the host, and Go builds from whatever files
|
||||||
described for that phase below.
|
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
|
- If the project uses `//go:embed` directives that reference build
|
||||||
artifacts, the lint phase must create placeholder files so the embed
|
artifacts, the lint phase must create placeholder files so the embed
|
||||||
directives resolve. A web frontend compiled in a separate stage is such an
|
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
|
base image or the install line changes. The first lines of a lint phase
|
||||||
that installs system libraries are at
|
that installs system libraries are at
|
||||||
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`.
|
`https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`.
|
||||||
|
- The test command keeps the first run's output, to look in it for what Go
|
||||||
Go example:
|
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
|
||||||
```makefile
|
timer, about a minute later. Go prints the goroutine stacks with either
|
||||||
test:
|
line, as long as the test can still respond. On either line the command
|
||||||
@status=0; \
|
exits 1 without a rerun. A failure with neither line reruns with `-v`. The
|
||||||
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.
|
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
|
||||||
`-count=1` is required on both invocations. It defeats Go's test _result_
|
result in its cache directory (`GOCACHE`). When the same tests run again
|
||||||
cache, so neither run can report a stored pass in place of running the
|
on unchanged code, it prints that result, marked `(cached)`, without
|
||||||
tests. It leaves the build cache alone, so it costs the runtime of the suite
|
running them. That directory lasts between runs on a developer's machine,
|
||||||
and no recompilation.
|
and in the `test` phase, which mounts it to keep compiled packages.
|
||||||
|
- `-count=1` defeats only that test _result_ cache. It leaves the build
|
||||||
That cache is Go's own, separate from Docker's layer cache. Go stores a
|
cache alone, so it costs the runtime of the suite and no recompilation.
|
||||||
passing result in its cache directory (`GOCACHE`). When the same tests run
|
The cache is Go's own, separate from Docker's layer cache.
|
||||||
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.
|
|
||||||
|
|
||||||
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it
|
- **A Python `test` phase that installs its packages from `Pipfile.lock` does it
|
||||||
before `COPY . .`, so check builds keep them.** The steps are:
|
before `COPY . .`, so check builds keep them.** The steps are:
|
||||||
|
|||||||
Reference in new issue
Block a user