Repository files navigation

A Docker-based Go cross compiler that enables easy compilation of Go projects with CGO dependencies across multiple platforms and architectures.

• xgo - Go CGO Cross Compiler
  • Table of Contents
  • Overview
  • Quick Start
  • Installation
    • Docker Image
    • Go Wrapper
  • Usage
    • Basic Usage
    • Build Flags
    • Go Releases
    • Limit Build Targets
    • Platform Versions
    • CGO Dependencies
    • Hooks
  • Supporters
  • Contributing
  • License
  • Acknowledgments

Although Go strives to be a cross-platform language, cross-compilation with CGO enabled isn't straightforward. You need Go sources bootstrapped to each platform and architecture, plus access to OS-specific headers and libraries.

xgo solves this by packaging all necessary Go toolchains, C cross compilers, and platform headers/libraries into a single Docker container. This enables seamless cross-compilation of Go code with embedded C/C++ snippets (CGO_ENABLED=1) to various platforms and architectures.

1. Install Docker and pull the xgo image:

   docker pull techknowlogick/xgo:latest

2. Install the xgo wrapper:

   go install src.techknowlogick.com/xgo@latest

3. Cross-compile your project:

   cd your-projectxgo.

That's it! You'll get binaries for all supported platforms and architectures.

Pull the pre-built Docker image:

docker pull techknowlogick/xgo:latest

Install the xgo command-line wrapper:

go install src.techknowlogick.com/xgo@latest

Simply specify the import path you want to build:

$ xgo -out iris-v0.3.2 github.com/project-iris/iris...$ ls -al-rwxr-xr-x  1 root  root   6776500 Nov 24 16:44 iris-v0.3.2-darwin-10.6-386-rwxr-xr-x  1 root  root   8755532 Nov 24 16:44 iris-v0.3.2-darwin-10.6-amd64-rwxr-xr-x  1 root  root  10135248 Nov 24 16:44 iris-v0.3.2-linux-386-rwxr-xr-x  1 root  root  12598472 Nov 24 16:44 iris-v0.3.2-linux-amd64-rwxr-xr-x  1 root  root  10040464 Nov 24 16:44 iris-v0.3.2-linux-arm-rwxr-xr-x  1 root  root   7516368 Nov 24 16:44 iris-v0.3.2-windows-4.0-386.exe-rwxr-xr-x  1 root  root   9549416 Nov 24 16:44 iris-v0.3.2-windows-4.0-amd64.exe

For local projects, use paths starting with. or/:

xgo.

xgo supports the following command-line flags:

The followinggo build flags are supported:

Select specific Go versions using the-go flag:

xgo -go go-1.24.x github.com/your-username/your-project

Supported release strings:

• latest - Latest Go release (default)
• go-1.24.x - Latest point release of Go 1.24
• go-1.24.3 - Specific Go version

Restrict builds to specific platforms/architectures:

# Build only ARM Linux binariesxgo --targets=linux/arm github.com/your-username/your-project# Build all Windows and macOS binariesxgo --targets=windows/*,darwin/* github.com/your-username/your-project# Build ARM binaries for all platformsxgo --targets=*/arm github.com/your-username/your-project

Supported targets:

• Platforms:darwin,linux,windows,freebsd
• Architectures:386,amd64,arm-5,arm-6,arm-7,arm64,mips,mipsle,mips64,mips64le,riscv64

Target specific platform versions:

# Cross-compile to macOS Montereyxgo --targets=darwin-12.0/* github.com/your-username/your-project# Cross-compile to Windows 10xgo --targets=windows-10.0/* github.com/your-username/your-project

Supported platforms:

• Windows: All APIs up to Windows 11 (limited by mingw-w64)
• macOS: APIs from 10.6 to latest

Build projects with external C/C++ library dependencies using--deps:

$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.1.0.tar.bz2  \    --targets=windows/* github.com/ethereum/go-ethereum/cmd/geth...$ ls -al-rwxr-xr-x 1 root root 16315679 Nov 24 16:39 geth-windows-4.0-386.exe-rwxr-xr-x 1 root root 19452036 Nov 24 16:38 geth-windows-4.0-amd64.exe

Pass arguments to dependency configure scripts:

$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.1.0.tar.bz2  \    --targets=ios/* --depsargs=--disable-assembly               \    github.com/ethereum/go-ethereum/cmd/geth...$ ls -al-rwxr-xr-x 1 root root 14804160 Nov 24 16:32 geth-ios-5.0-arm

Supported dependency formats:.tar,.tar.gz,.tar.bz2

Use custom build hooks by providing a hooks directory:

xgo --hooksdir ./hooks github.com/your-username/your-project

Available hook scripts:

• setup.sh - Sourced after environment setup (install additional packages)
• build.sh - Sourced before each target build

Environment variables inbuild.sh:

• XGOOS andXGOARCH - Target OS and architecture
• CC - C cross compiler for the target
• HOST - Target platform identifier
• PREFIX - Installation path for built binaries

Thanks to these projects for supporting xgo:

• Gitea - A painless self-hosted Git service
• Offen - Fair and lightweight web analytics
• Vikunja - The to-do app to organize your life
• Woodpecker CI - Simple CI engine with great extensibility

You cansponsor this project to ensure its continued maintenance.

Contributions are welcome! Please feel free to submit issues and enhancement requests.

This project is licensed under the MIT License - see theLICENSE file for details.

Special thanks to@karalabe for starting this project and making Go cross-compilation with CGO seamless.