> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Build Go applications with RBS — hermetic Go toolchain, cross-compilation, and CGO support.

# Go SDK

RBS provides hermetic Go support with automatic Go SDK management, hermetic builds with `GOPROXY=off`, and cross-compilation via platform flags.

## Setup

### Toolchain

Register a Go toolchain in `WORKSPACE.rbs`:

```python filename="WORKSPACE.rbs" theme={null}
load("@rbs//go/toolchain.rbs", "go_toolchain")

go_toolchain(name = "go", version = "1.22.0")
```

RBS downloads the Go SDK for your platform and uses it for all Go builds.

## Rules

### `go_library`

Creates a reusable Go library (source packaging for dependents).

```python theme={null}
load("@rbs//go/rules.rbs", "go_library")

go_library(
    name = "utils",
    srcs = ["utils.go", "helpers.go"],
    deps = [":common"],
)
```

| Attribute | Type   | Description                                                     |
| --------- | ------ | --------------------------------------------------------------- |
| `name`    | string | Unique target name (required).                                  |
| `srcs`    | list   | Go source files (can include `go.mod`, `go.sum`, vendor files). |
| `deps`    | list   | Local `go_library` dependencies.                                |
| `cgo`     | bool   | Enable CGO (default `False`).                                   |

### `go_binary`

Creates an executable Go binary.

```python theme={null}
load("@rbs//go/rules.rbs", "go_binary")

go_binary(
    name = "server",
    srcs = ["main.go", "server.go"],
    deps = [":utils"],
)

# With module support
go_binary(
    name = "app",
    srcs = ["main.go", "go.mod", "go.sum"],
    goflags = ["-ldflags", "-s -w"],  # Strip debug info
)

# With CGO enabled
go_binary(
    name = "native_app",
    srcs = ["main.go"],
    cgo = True,
)
```

| Attribute | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `name`    | string | Unique target name (required).                       |
| `srcs`    | list   | Go source files (required).                          |
| `deps`    | list   | Local `go_library` dependencies.                     |
| `goflags` | list   | Extra flags passed to `go build` (e.g., `-ldflags`). |
| `cgo`     | bool   | Enable CGO (default `False`).                        |

### `go_test`

Runs Go tests.

```python theme={null}
load("@rbs//go/rules.rbs", "go_test")

go_test(
    name = "utils_test",
    srcs = glob(["*_test.go"]),
    deps = [":utils"],
)
```

## Hermetic Builds

By default, RBS runs Go builds with `GOPROXY=off` and `GOSUMDB=off`, ensuring the Go tool cannot fetch modules from the network at build time. All dependencies must be vendored or pre-fetched.

For stdlib-only builds (no `go.mod`), RBS automatically sets `GO111MODULE=off` so `go build` works without a module root.

## Cross-Compilation

Use the `RBS_TARGET_PLATFORM` environment variable to cross-compile:

```bash theme={null}
# Build for Linux AMD64 from macOS
RBS_TARGET_PLATFORM=linux-amd64 rbs build server

# Build for Linux ARM64
RBS_TARGET_PLATFORM=linux-arm64 rbs build server
```

## Example

```python filename="BUILD.rbs" theme={null}
load("@rbs//go/rules.rbs", "go_binary", "go_library", "go_test")

go_library(
    name = "handlers",
    srcs = ["handlers.go", "middleware.go"],
)

go_binary(
    name = "api_server",
    srcs = ["main.go"],
    deps = [":handlers"],
    goflags = ["-ldflags", "-X main.version=1.0.0"],
)

go_test(
    name = "handlers_test",
    srcs = ["handlers_test.go"],
    deps = [":handlers"],
)
```

```bash theme={null}
rbs build api_server      # Build the server
rbs run api_server        # Run the server
rbs test handlers_test    # Run tests
```