# 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.

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.