Documentation
¶
Overview ¶
Package buildpkg implements the `dockyard build` pipeline — the step that turns a Dockyard project into the shippable artifact (RFC §14).
Build sequences five stages, in order:
- regenerate the project's contract artifacts (internal/generate);
- run the `dockyard validate` quality gate (internal/validate) — a validation BLOCKER fails the build, enforcing P1 at build time;
- build the project's web/ Vite UI, when one exists, so the dist/ embed target is on disk BEFORE go build reads the //go:embed directive (the RFC §14 embed ordering);
- go build the Go MCP server as one CGo-free, statically-linked binary with the UI embedded — CGO_ENABLED=0 is pinned on every invocation;
- cross-compile the RFC §14 target matrix (darwin/linux/windows × amd64/arm64) and emit a SHA-256 checksum file per artifact.
buildpkg is internal — it is the reusable, testable seam the `dockyard build` cobra verb and the Phase 20 integration test consume. The cobra RunE is a thin wrapper; the pipeline logic lives here (the house pattern, D-082).
Build holds no shared mutable state: it builds fresh state per call and is safe to call concurrently with distinct Options.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBuild = errors.New("dockyard/internal/buildpkg: build failed")
ErrBuild is the sentinel wrapping a `dockyard build` failure that is not a validation blocker — a missing project, an I/O fault, a `go build` or Vite failure. Callers branch with errors.Is(err, ErrBuild).
var ErrValidationBlocked = errors.New("dockyard/internal/buildpkg: build blocked by validation")
ErrValidationBlocked is the sentinel wrapping a build that failed because the `dockyard validate` gate reported a build blocker. It is distinct from ErrBuild so a caller (and the integration test's failure-mode assertion) can tell a quality-gate stop from a toolchain fault. RFC §14 / P1: a build with a validation blocker fails.
Functions ¶
This section is empty.
Types ¶
type Artifact ¶
type Artifact struct {
// Target is the GOOS/GOARCH this artifact was built for.
Target Target
// Path is the absolute path of the built binary.
Path string
// ChecksumPath is the absolute path of the binary's .sha256 sidecar.
ChecksumPath string
}
Artifact is one produced binary and its checksum sidecar.
type Options ¶
type Options struct {
// ProjectDir is the root of the Dockyard project — the directory holding
// dockyard.app.yaml. Required.
ProjectDir string
// OutputDir is where build artifacts and checksum files are written. An
// empty value defaults to <ProjectDir>/dist.
OutputDir string
// Targets is the cross-compile target set. An empty slice builds the host
// platform only — the fast inner-loop build; pass DefaultMatrix() for the
// full RFC §14 release matrix.
Targets []Target
// SkipValidate disables the validate gate. It is a test seam only —
// production builds always validate (P1). A normal build leaves it false.
SkipValidate bool
// Logger receives the build's structured progress output. A nil Logger
// falls back to a discarding logger so Build never panics on a missing
// logger; a caller should pass the dev-mode text handler.
Logger *slog.Logger
}
Options configures one `dockyard build` invocation.
type Result ¶
type Result struct {
// Artifacts is every produced binary + checksum, in target-matrix order.
Artifacts []Artifact
// UIEmbedded reports whether a web/ Vite UI was built and embedded. It is
// false for a no-template blank server (RFC §4.1 — a UI is additive).
UIEmbedded bool
}
Result reports what a Build produced.
func Build ¶
Build runs the `dockyard build` pipeline (RFC §14) for the project rooted at opts.ProjectDir: regenerate contracts → run the validate gate → build the web/ Vite UI (when present) → go build a CGo-free static binary per target with the UI embedded → emit a SHA-256 checksum per artifact.
A validation blocker fails the build with an error wrapping ErrValidationBlocked; any other failure wraps ErrBuild. On success every Result.Artifacts entry has a binary and a checksum file on disk.
Build builds fresh state per call and holds no shared mutable state.
type Target ¶
type Target struct {
// OS is the GOOS value (e.g. "linux", "darwin", "windows").
OS string
// Arch is the GOARCH value (e.g. "amd64", "arm64").
Arch string
}
Target is one cross-compile target — a GOOS/GOARCH pair. It names the platform a `dockyard build` artifact is produced for.
func DefaultMatrix ¶
func DefaultMatrix() []Target
DefaultMatrix returns the RFC §14 cross-compile matrix: the darwin/linux/windows × amd64/arm64 set every `dockyard build` produces an artifact and a checksum for. The order is stable so a Result and the emitted dist/ tree are deterministic.
Source Files