Cross-compile Go with C dependencies for ARM
Go includes first-class support for cross-compiling pure Go code to multiple operating systems and architectures simply by specifying the $GOOS and $GOARCH environment variables (see the official environment list).
However, when your project uses C libraries or legacy system APIs via cgo, compilation requires a matching C cross-compiler and target C runtime headers. Configuring this directly on your host machine can quickly lead to conflicting toolchains and package versions.
Using Docker multi-stage builds and Buildx provides a reproducible, hermetic cross-compilation pipeline for both 64-bit ARM (arm64 / aarch64) and 32-bit ARM (armhf).
Prerequisites
Bootstrap a container builder if you haven’t already:
docker buildx create --name arm-builder --driver docker-container --use
docker buildx inspect --bootstrapSetup the Go Project
Initialize a module:
mkdir go-cross && cd go-cross
go mod init github.com/my-username/go-crossCreate a C-backed Go package:
// pkg/hello/hello.go
package hello
// #include <stdlib.h>
// #include "hello.h"
import "C"
import (
"fmt"
"unsafe"
)
func Greet(name string) {
cs := C.CString(name)
size := C.size_t(len(name))
msg := C.greet(cs, size)
fmt.Println(C.GoString(msg))
C.free(unsafe.Pointer(cs))
}The accompanying C header and source:
// pkg/hello/hello.h
#ifndef HELLO_H_
#define HELLO_H_
#include <stdio.h>
#include <stdlib.h>
char *greet(const char *name, size_t size);
#endif// pkg/hello/hello.c
#include "hello.h"
char *greet(const char *name, size_t size) {
char *msg = malloc(size + 16);
if (!msg) return NULL;
sprintf(msg, "Hello, %s!", name);
return msg;
}And the application entrypoint:
// cmd/hello/main.go
package main
import (
"flag"
"github.com/my-username/go-cross/pkg/hello"
)
func main() {
flag.Parse()
name := flag.Arg(0)
if name == "" {
name = "stranger"
}
hello.Greet(name)
}Multi-Architecture Dockerfile
The Dockerfile installs target cross-toolchains from Debian Bookworm and uses BuildKit cache mounts for fast incremental rebuilds:
# syntax=docker/dockerfile:1
# Dockerfile.hello
ARG GO_VERSION=1.23
FROM golang:${GO_VERSION}-bookworm AS toolchain
ARG TARGETARCH=arm64
RUN apt-get update && \
if [ "$TARGETARCH" = "arm64" ]; then \
apt-get install --no-install-recommends -y \
gcc-aarch64-linux-gnu libc6-dev-arm64-cross; \
elif [ "$TARGETARCH" = "arm" ]; then \
apt-get install --no-install-recommends -y \
gcc-arm-linux-gnueabihf libc6-dev-armhf-cross; \
fi && \
rm -rf /var/lib/apt/lists/*
WORKDIR /code
COPY go.mod ./
RUN --mount=type=cache,target=/go/pkg/mod \
go mod download
FROM toolchain AS builder
ARG TARGETARCH=arm64
ARG TARGETOS=linux
ENV CGO_ENABLED=1
ENV GOOS=${TARGETOS}
ENV GOARCH=${TARGETARCH}
# Set cross-compiler based on architecture
ENV CC_arm64=aarch64-linux-gnu-gcc
ENV CC_arm=arm-linux-gnueabihf-gcc
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
--mount=type=cache,target=/go/pkg/mod \
if [ "$TARGETARCH" = "arm64" ]; then \
export CC=$CC_arm64; \
else \
export CC=$CC_arm GOARM=7; \
fi && \
mkdir -p /tmp/bin && \
go build -trimpath -ldflags="-s -w" -o /tmp/bin/hello ./cmd/hello
FROM scratch AS output
COPY --from=builder /tmp/bin/hello /Directory layout:
.
├── Dockerfile.hello
├── cmd
│ └── hello
│ └── main.go
├── go.mod
└── pkg
└── hello
├── hello.c
├── hello.go
└── hello.hBuild and Export
Build for 64-bit ARM (linux/arm64):
docker buildx build \
-f Dockerfile.hello \
--build-arg TARGETARCH=arm64 \
--output type=local,dest=./bin/arm64 \
.Or build for 32-bit ARMv7 (linux/arm):
docker buildx build \
-f Dockerfile.hello \
--build-arg TARGETARCH=arm \
--output type=local,dest=./bin/arm \
.Inspect the compiled binary:
file ./bin/arm64/hello
# ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked ...Testing Locally with QEMU
If you are running on a Linux host (or inside a container with qemu-user), you can execute the target binary directly through user-mode emulation without copying to physical hardware:
qemu-aarch64 -L /usr/aarch64-linux-gnu ./bin/arm64/hello Roland
# Hello, Roland!Source code and additional configurations are available at rolandjitsu/go-cross.