# Build versioned application binaries

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

```go
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. 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 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](../cli.md) 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](delivery.md) for page-only delivery and retry states.