golang-build

Files (2)

• SKILL.md
• build.go · assets/

SKILL.md (first lines)

**Persona:** Go build engineer — reproducible, static, cross-compiled binaries with zero external tooling.

# Go Build

## The build.go Convention

Every Go project should have a `build.go` file at the **root of the repository** (not inside `cmd/`). This file is a plain Go program that cross-compiles the project for all target platforms. It requires no external tools — only the Go toolchain.

Run it with:

```sh
go run build.go
```

The template is provided in [assets/build.go](assets/build.go). Copy it to the root of the project and adapt it to the project's needs.

## Default Configuration

The default `build.go` ships with the following settings:

| Setting | Default | Reason |
| --- | --- | --- |
| `CGO_ENABLED` | `0` | Produces fully static binaries; required for cross-compilation without a C cross-compiler |
| `linux/amd64` | ✅ | Standard server target |
| `windows/amd64` | ✅ | Standard Windows desktop/server target |
| `darwin/arm64` | ✅ | Apple Silicon Mac target |

## Customising the Build Script

All knobs are at the top of `build.go`:

### Change the Binary Name

```go
const (
    BinaryName   = "myapp" // ← rename to match the project
    C_GO_ENABLED = 0
)
```

### Add or Remove Target Platforms

```go
var platforms = []struct {
    OS   string
    Arch string
}{
    {"linux", "amd64"},
    {"windows", "amd64"},
    {"darwin", "arm64"},
    // {"darwin", "amd64"}, // Intel Mac
    // {"linux", "arm64"},  // ARM server / Raspberry Pi
}
```

### Add Build Flags

Uncomment or add entries in `buildOptions`:

```go
var buildOptions = []string{
    "-o", BinaryName,
    // "-v",                    // verbose output
    // "-trimpath",             // remove local file paths from binary
    // "-ldflags", "-s -w",     // strip debug symbols (smaller binary)
    // "-ldflags", "-X main.version=1.2.3", // embed version string
}
```

### Enable CGO

Only enable CGO if the project requires C bindings (e.g., sqlite3, certain crypto libs). Cross-compilation with CGO requires a C cross-compiler per target platform.

```go
const C_GO_ENABLED = 1 // requires C toolchain for each target
```

## Common Mistakes

| Mistake | Fix |
| --- | --- |
| Placing `build.go` inside `cmd/` | Keep it at the repository root — it builds the whole project |
| Using `CGO_ENABLED=1` without a cross-compiler | Either disable CGO or install the correct C toolchain for each target |
| Hardcoding the output path without platform suffix | When building for multiple platforms simultaneously, append `_OS_ARCH` to `BinaryName` to avoid overwriting |
| Forgetting `-trimpath` for release builds | Release binaries should not embed developer machine paths |

## Related Skills

- → See [golang-project-layout](../golang-project-layout/SKILL.md) for where build.go fits in the overall project structure

From paulohgodinho/skills, MIT.

More from paulohgodinho/skills