---
title: Go Examples
description: Common Go build patterns with managed SDKs.
---

# Go Examples

These examples pin Go `1.26.5`. Replace it deliberately when the project changes toolchain versions.

## Build One Source File

Project layout:

```text
.
|-- .xx/
|   `-- build.star
|-- go.mod
`-- main.go
```

`.xx/build.star`:

```python
load("@go@1.26.5", "go_binary")

go_binary(entry_point="main.go")
```

Run `xx run build`. Output is `.xx/out/main` or `.xx/out/main.exe` on Windows.

## Build a Package Directory

Use a directory when a command has multiple Go files:

```python
load("@go@1.26.5", "go_binary")

go_binary(
    entry_point="cmd/server",
    output="bin/server",
)
```

xx invokes `go build` for the complete `cmd/server` package and creates `bin/` when needed. Custom output names are exact, so use `bin/server.exe` explicitly when a custom Windows filename is required.

## Reproducible Release Flags

Pass normal `go build` flags through `flags`:

```python
load("@go@1.26.5", "go_binary")
load("@os@1", "env_set")

go_binary(
    entry_point="cmd/server",
    output="dist/server",
    flags=[
        "-trimpath",
        "-ldflags=-s -w",
    ],
    deps=[env_set("CGO_ENABLED", "0")],
)
```

Use `output` for the destination. Do not put `-o` in `flags`.

## Run Tests with Managed Go

Load the `go` dependency when a command needs the managed SDK outside `go_binary`:

```python
load("@go@1.26.5", "go")
load("@os@1", "env_set", "run")

run(
    ("go", "test", "./..."),
    deps=[
        go,
        env_set("CGO_ENABLED", "0"),
    ],
)
```

No global Go executable is used. The command runs from project root with xx's managed SDK and caches.

## Run a Versioned Go Tool

Use `go_run` for a Go command that does not need to remain available to later tasks:

```python
load("@go@1.26.5", "go_run")

go_run(
    package="codeberg.org/tsukinoko-kun/doctopus",
    version="latest",
    args=["build"],
)
```

xx invokes `go run codeberg.org/tsukinoko-kun/doctopus@latest build` with the managed SDK.

## Build and Test Together

One entrypoint can declare independent tasks:

```python
load("@go@1.26.5", "go", "go_binary")
load("@os@1", "run")

run(("go", "test", "./..."), deps=[go])

go_binary(
    entry_point="cmd/server",
    output="bin/server",
    flags=["-trimpath"],
)
```

Both tasks share setup for Go `1.26.5` and may execute concurrently. If one fails, xx cancels the other and exits with an error.

## Separate Build and Test Entrypoints

For commands that should be selectable independently, create `.xx/build.star` and `.xx/test.star`.

`.xx/build.star`:

```python
load("@go@1.26.5", "go_binary")

go_binary(entry_point="cmd/server", output="bin/server")
```

`.xx/test.star`:

```python
load("@go@1.26.5", "go")
load("@os@1", "run")

run(("go", "test", "./..."), deps=[go])
```

Run either or both:

```console
xx run build
xx run test
xx run build test
```

When multiple names are passed, xx starts each entrypoint and reports any failures together.

<!--
Sitemap

URL: https://withxx.dev/index.md
Title: xx
Description: Practical, reproducible builds without build-system ceremony

URL: https://withxx.dev/examples/commands.md
Title: Command Examples
Description: General command, environment, and entrypoint patterns.

URL: https://withxx.dev/examples/go.md
Title: Go Examples
Description: Common Go build patterns with managed SDKs.

URL: https://withxx.dev/examples/index.md
Title: Examples
Description: Common xx build and task patterns.

URL: https://withxx.dev/examples/nodejs.md
Title: Node.js Examples
Description: Common Node.js task patterns with a managed distribution.

URL: https://withxx.dev/load.md
Title: Loading Files
Description: Split xx configuration into local Starlark modules.

URL: https://withxx.dev/packages/go.md
Title: Go Package
Description: Provision an official Go SDK, run or install Go tools, and build Go binaries.

URL: https://withxx.dev/packages/nodejs.md
Title: Node.js Package
Description: Provision official Node.js distributions and run npm and npx tasks.

URL: https://withxx.dev/packages/os.md
Title: OS Package
Description: Run commands and construct isolated task environments.
-->