ReleaseKit/docs/consumers/build.md

Build versioned application binaries

Use releasekit.Build when an application needs binaries for explicit Go operating-system and architecture pairs:

import (
	"context"
	"fmt"

	releasekit "gitea.maximumdirect.net/eric/ReleaseKit"
)

func build(ctx context.Context) error {
	result, err := releasekit.Build(ctx, releasekit.BuildRequest{
		RepositoryDir: "/work/project",
		Version:       "v1.2.3",
		Spec: releasekit.BuildSpec{
			MainPackage: "./cmd/project",
			BinaryName:  "project",
			Targets: []releasekit.Target{
				{OS: "linux", Arch: "amd64"},
				{OS: "linux", Arch: "arm64"},
				{OS: "darwin", Arch: "arm64"},
			},
		},
		OutputDir: "dist",
	})
	if err != nil {
		return err // result retains completed artifacts when a later step fails.
	}
	for _, artifact := range result.Artifacts {
		fmt.Println(artifact.Filename, artifact.SHA256)
	}
	return nil
}

Build resolves ModuleDir and the selected module's working-tree declaration once, records the repository's current HEAD, injects the selected stable version into buildinfo.Version, and returns repository/module identity, the derived tag, compiler identity, normalized targets, artifact paths, filenames, and SHA-256 digests. It does not require a release note, unused tag, clean main, or publication. Names follow <binary>-<version>-<goos>-<goarch>; Windows targets add .exe. A repeated target pair is built once, at its first position. Local builds may use modified source. SourceVerified is true only after a complete build observes clean source and the same HEAD before and after compilation; binary delivery requires that fact. This observation is not a source snapshot or attestation guarantee.

Go commands run from ModuleDir, so MainPackage is interpreted within that module. The default output directory is <module>/dist; a relative OutputDir is resolved from the module, while an absolute path is used as supplied. Selected artifact filenames are regenerated. Other files in the output directory are left in place. A failed later build or native version check returns the binaries already generated in BuildResult.Artifacts.

Builds use the available compatible Go toolchain selected locally; ReleaseKit does not download a different toolchain automatically. It disables workspace discovery and module network access, uses readonly module mode, sets CGO_ENABLED=0, and passes -trimpath and -buildvcs=false. Effective cache, module-cache, temporary-directory, and tool settings are retained, including values from Go's persistent environment file. Ambient experiment and CPU feature settings are cleared so the selected toolchain uses its baseline for each target. Each selected target is compiled explicitly. ReleaseKit then runs the version command on a native binary and requires <binary> <version> followed by a newline. If no selected target matches the Go host, it builds a temporary native binary for this check and removes it afterward. Cross-compilation does not promise that a binary runs on another platform.

An empty target list records the source commit and returns without invoking Go, creating the output directory, or running a version check. It does not require a main package or binary name. This supports source-only operations without silently adding a binary check.

The build command reads the same build specification from the profile and writes a private receipt alongside its artifacts. check and publish run selected builds after the standard suite and any additional checks using temporary output outside the worktree. Candidate checks do not write a receipt or leave build files in the repository. Disposable native version-check output also remains outside the whole repository when TMPDIR points inside the source tree.

For delivery from a tagged checkout, deliver builds selected tagged-source targets into temporary storage by default. Use --assets DIR to deliver a separate build output; ReleaseKit requires the current module-bound receipt and checks its source identity and normalized build settings. It verifies artifact bytes and sizes during delivery before the first Gitea write. Older receipts must be regenerated with the updated build command. See the delivery consumer guide for page-only delivery and retry states.