guestbuild

Documentation

Overview

Package guestbuild cross-compiles the guest-side binaries (clawk-init, clawk-pty-agent, clawk-time-sync) on the host, for injection into OCI-image sandbox disks.

Arbitrary OCI images have no Go toolchain, so the embedded sources are compiled here on the host with GOOS=linux CGO_ENABLED=0 and the static binaries are baked into the rootfs by machine/oci's inject support.

Release binaries carry these prebuilt (see internal/agentembed/prebuilt.go), so an installed clawk needs no Go toolchain at all. Building from source leaves them out and they are compiled here on first use instead, cached under <cacheDir>/guestbin/<hash>/ keyed by source content, target arch and toolchain version — so the ~seconds cost is paid once per clawk version.

Index

• func GeneratePrebuilt(ctx context.Context, destDir, arch string) error
• func Prebuilt(arch string) bool
• type Binaries
  • func Build(ctx context.Context, cacheDir, arch string) (Binaries, error)

Functions

func GeneratePrebuilt

func GeneratePrebuilt(ctx context.Context, destDir, arch string) error

GeneratePrebuilt builds the guest binaries for arch and writes them, plus a manifest, into destDir for `go:embed` to pick up. It is the implementation behind `make guestbin`; nothing at runtime calls it.

It deliberately reuses Build, so the binaries a release embeds are produced by the same code path a source build uses — one compiler invocation, one set of flags, no second recipe to drift.

func Prebuilt

func Prebuilt(arch string) bool

Prebuilt reports whether this binary carries guest binaries for arch, i.e. whether a sandbox can boot with no Go toolchain present. `clawk doctor` asks, so it can tell a hard prerequisite from an optional one.

Types

type Binaries

type Binaries struct {
	Init     string
	Agent    string
	TimeSync string

	// Cached reports that a previous build was reused — callers use it
	// to avoid announcing build work that didn't happen.
	Cached bool
}

Binaries holds the absolute paths of the built guest binaries.

func Build

func Build(ctx context.Context, cacheDir, arch string) (Binaries, error)

Build returns the guest binaries for linux/<arch>.

A release binary embeds them (see internal/agentembed/prebuilt.go), so this only unpacks and returns — no Go toolchain, no network. A source build has nothing embedded and compiles them from the embedded sources instead, caching the result; that path needs `go` on PATH, and network the first time for the guest modules' dependencies.