Skip to content

docs(go): document build_addr relative pkg resolution #85

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
Jul 31, 2026
Merged

docs(go): document build_addr relative pkg resolution #85

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
5 changes: 5 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 @@ -221,9 +221,14 @@ none match. Library targets have no such shortcut — always give them `@v=NAME`
heph.go.build_addr(pkg, variant = "")
# heph.go.build_addr("cmd/server", "release") -> "//cmd/server:build@v=release"
# heph.go.build_addr("cmd/server") -> "//cmd/server:build"
# heph.go.build_addr("./worker", "release") -> relative to the calling package, e.g. "//cmd/server/worker:build@v=release"
# heph.go.build_addr("../shared") -> "//cmd/shared:build"
```

- `pkg` required; `variant` optional, defaults to `""` (plain address).
- `pkg` is a package path, or, starting with `./` or `../`, resolved relative
to the calling BUILD file's package (same rules as relative addresses). A
path that resolves outside the workspace is an error.
- All arguments are type-enforced: wrong type, missing required arg, or
unknown keyword → hard error naming the function and the offending argument.
- Pure string formatting — resolves and builds nothing, and doesn't check that
Expand Down
11 changes: 9 additions & 2 deletions website/docs/plugins/go.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@ namespace.

| Function | Signature | Returns |
|----------|-----------|-------|
| `heph.go.build_addr` | `build_addr(pkg: string, variant: string = "") -> string` | The address of `pkg`'s `build` target, optionally pinned to a named [build variant](#build-variants). |
| `heph.go.build_addr` | `build_addr(pkg: string, variant: string = "") -> string` | The address of `pkg`'s `build` target, optionally pinned to a named [build variant](#build-variants). `pkg` accepts a package path or a path relative to the calling BUILD file's package. |

The function enforces its argument types: wrong type, missing required argument,
or unknown keyword produces a clear error.
Expand Down Expand Up @@ -406,7 +406,7 @@ heph.go.build_addr(pkg, variant = "")

| Argument | Default | Meaning |
|-----------|---------|---------|
| `pkg` | required | The target's package, e.g. `"cmd/server"`. |
| `pkg` | required | The target's package, e.g. `"cmd/server"`. Starting with `./` or `../`, it resolves relative to the calling BUILD file's package instead — same rules as [relative addresses](../reference/addresses.md#relative-forms). A path that resolves outside the workspace is an error. |
| `variant` | `""` | The variant name. Omit (or pass `""`) for the plain, unparameterized address. |

```python title="cmd/server/BUILD"
Expand All @@ -423,6 +423,13 @@ The image target now embeds the `release`-variant binary. Calling `build_addr`
only formats the address — it does not resolve or build anything, and it does
not check that the variant is actually declared.

`pkg` can also be given relative to the calling package:

```python title="cmd/server/BUILD"
heph.go.build_addr("./worker", "release") # -> //cmd/server/worker:build@v=release
heph.go.build_addr("../shared") # -> //cmd/shared:build
```

:::note
List every provider-exposed BUILD function with `heph inspect functions`.
:::
Expand Down
Loading