Building the code

Purpose

This is the authoritative guide for building Radius from source. It covers building the binaries (including the rad CLI), building the container images for the control-plane services, and regenerating checked-in generated code. Radius uses a GNU Make Makefile (split into includes under build/) to automate these tasks. If you are making your first contribution, the first-commit walkthrough links here for the canonical steps.

Prerequisites

• The repository cloned locally. See Creating your own fork.
• The tools listed in the prerequisites guide — at minimum Go (the version pinned in go.mod) and GNU Make.
• For building container images: a working Docker daemon and a registry you can push to.
• For make generate: the extra code-generation tools listed under Install code-generation tools.

Run make (or make help) with no arguments at any time to print every target and its description.

Steps

Build the repository

Build all packages and binaries with:

make build

This runs build-packages, build-binaries, and build-bicep. The first run may take a few minutes because it downloads and builds dependencies; later builds reuse cached output. Binaries are written to ./dist/<GOOS>_<GOARCH>/release/.

To build a single binary instead of everything — useful when iterating on the CLI — use its build-<name> target. For example, to build only the rad CLI:

make build-rad

To build with debug symbols (-gcflags "all=-N -l"), set DEBUG=1:

DEBUG=1 make build-rad

Build, test, lint, and check formatting

This combined command builds the code, runs unit tests, runs the Go linters, and checks JSON/TS/JS/MJS formatting. Run it to verify your local changes before opening a pull request:

make build test lint format-check

If format-check reports issues, or if you added or changed any .ts, .js, .mjs, or .json files, reformat them with:

make format-write

If you changed any shell scripts, lint them with ShellCheck — install the pinned version once with make install-shellcheck, then run make lint-shell. See the shell scripts and Makefiles guide for details.

See the tests guide for the full test matrix and the writing code guide for linting details.

Build the container images

Build the control-plane service images with make docker-build, and push them with make docker-push. By default the registry is your OS username and the tag is latest; override them with environment variables:

• DOCKER_REGISTRY — destination registry.
• DOCKER_TAG_VERSION — image tag.

These commands assume you are already logged in to the target registry (docker login, az acr login, etc.). For example, to build and push to a specific registry:

DOCKER_REGISTRY=ghcr.io/my-registry make docker-build docker-push

If you work with Radius frequently, set DOCKER_REGISTRY in your shell profile. The radius-build-images skill wraps this workflow, including single-image and multi-architecture builds.

Build multi-architecture images

The multi-architecture targets build linux/amd64, linux/arm64, and linux/arm images with Docker Buildx. Initialize the QEMU and Buildx builder once:

make configure-buildx
docker buildx use radius-builder

The Make target creates and bootstraps the radius-builder builder when needed; docker buildx use selects it for the commands that follow. Then build and push a multi-architecture image index:

DOCKER_REGISTRY=ghcr.io/my-registry DOCKER_TAG_VERSION=latest make docker-multi-arch-push

Use make docker-multi-arch-build to build without pushing, or append an image name such as make docker-multi-arch-push-applications-rp to build and push one image.

Generate code

When you change API schemas or Go APIs that have mocks, regenerate the checked-in generated code as part of your commit. Radius checks in generated code so that not every contributor has to install the generators. The PR process validates that the generated files are up to date.

After installing the code-generation prerequisites, run:

make generate

This runs several generators in sequence and may take a few minutes. Commit the resulting changes alongside your code change. For details on the TypeSpec → Swagger → Go pipeline, see the schema changes guide.

Verification

• make build completes without errors and produces binaries under ./dist/<GOOS>_<GOARCH>/release/ (for example rad, applications-rp, ucpd, dynamic-rp, controller).
• make build test lint format-check passes end to end.
• After make docker-build, the images appear in docker images.
• After make generate, git status shows only the generated changes you expect, and no generated files remain stale.

Troubleshooting

• A make command fails on a missing dependency. Review the prerequisites guide and install the missing tool.
• Docker push fails with an authentication error. Confirm you are logged in to the registry named in DOCKER_REGISTRY.
• A multi-architecture build cannot find a builder or emulator. Run make configure-buildx, select it with docker buildx use radius-builder, then confirm it is active in docker buildx ls.
• You need to report a build problem. Dump every Makefile variable with make dump (the output is large, so redirect it to a file) and include it in your report.
• Still stuck. Ask in the Radius Discord forum, or open an issue so we can improve the tooling and these instructions.