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 records the repository's current HEAD, injects the selected stable version into buildinfo.Version, and returns the compiler identity, normalized targets, artifact paths, filenames, and SHA-256 digests. 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.

The default output directory is <repository>/dist; a relative OutputDir is resolved from the repository. Existing files with a selected artifact name are preserved and cause an error. 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 prepared local Go toolchain, readonly module mode, disabled module network access, CGO_ENABLED=0, -trimpath, and -buildvcs=false. 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 their one validation callback using temporary output outside the worktree; those candidate checks do not write a receipt or leave build files in the repository.

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 its receipt and verifies the source, build settings, and artifact hashes before the first Gitea write. See the delivery consumer guide for page-only delivery and retry states.