Skip to content

docs(go): document the buildmode variant field #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
raphaelvigee merged 1 commit into from
Aug 13, 2026
Merged

docs(go): document the buildmode variant field #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions plugins/heph-go/skills/heph-go/references/go-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,7 @@ provider_state(provider = "go", variants = {
| `goexperiment` | `list[string]` | no | `GOEXPERIMENT` values. |
| `gcflags` | `list[string]` | no | Extra `go tool compile` flags. |
| `ldflags` | `list[string]` | no | Extra `go tool link` flags. |
| `buildmode` | `string` | no | Link mode for a `package main` `:build`: `"exe"` (default, static on Linux) or `"pie"` (position-independent, needs an interpreter on Linux). See "Buildmode" below. |
| `inherit` | `string` | no | Another variant name in the same map to start from. |

No `cgo` field — every heph-built Go target has `CGO_ENABLED=0` unconditionally.
Expand All @@ -198,6 +199,24 @@ No `cgo` field — every heph-built Go target has `CGO_ENABLED=0` unconditionall
merged**; `goos`/`goarch` may be omitted when the base sets them; inheritance
cycles error.

### Buildmode

`buildmode` picks the link mode for a `package main` target's `:build`:
`"exe"` (default) matches plain `go build` — on Linux the binary links
statically with no interpreter, so it runs in `FROM scratch`/distroless.
`"pie"` produces a position-independent executable, which on Linux always
needs `/lib/ld-linux-<arch>.so.1` at run time, cgo or not.

```python title="BUILD"
provider_state(provider = "go", variants = {
"release": {"goos": "linux", "goarch": "arm64", "buildmode": "pie"},
})
```

On darwin/arm64 the linker makes every executable PIE regardless of this
setting — the knob only changes behavior on Linux. Only affects the linked
binary; libraries/archives are unaffected.

Select with `@v=NAME` on the address:

```bash
Expand Down
24 changes: 24 additions & 0 deletions website/docs/plugins/go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,6 +359,7 @@ provider_state(provider = "go", variants = {
| `goexperiment` | `list[string]` | no | `GOEXPERIMENT` values to enable. |
| `gcflags` | `list[string]` | no | Extra flags passed to `go tool compile`. |
| `ldflags` | `list[string]` | no | Extra flags passed to `go tool link`. |
| `buildmode` | `string` | no | Link mode: `"exe"` (default) or `"pie"`. See [Buildmode: static vs PIE](#buildmode-static-vs-pie). |
| `inherit` | `string` | no | Name of another variant in the same map to start from. |

`cgo` is not a variant field — every heph-built Go target compiles with
Expand All @@ -371,6 +372,29 @@ on top of it. List fields (`tags`, `goexperiment`, `gcflags`, `ldflags`) are
`goarch` can be omitted when inheriting from a variant that already sets them.
Inheritance cycles are rejected with an error.

### Buildmode: static vs PIE

`buildmode` controls the binary's link mode for a `package main` target's
`:build`:

| Value | Behavior |
|---------|----------|
| `"exe"` | Default. Matches plain `go build`. On Linux, links a statically linked binary with no interpreter — it runs in a `FROM scratch` or distroless image. |
| `"pie"` | Position-independent executable. On Linux this always needs `/lib/ld-linux-<arch>.so.1` present at run time, even with cgo disabled. |

```python title="BUILD"
provider_state(provider = "go", variants = {
"release": {"goos": "linux", "goarch": "arm64", "buildmode": "pie"},
})
```

On darwin/arm64 the Go linker makes every executable PIE regardless of this
setting, so both values produce the same kind of binary there — the knob only
changes behavior on Linux.

Library targets and archives are unaffected by `buildmode`; it only applies to
the linked binary of a `package main`.

### Selecting a variant

Add `@v=NAME` to a target address:
Expand Down
Loading