xgo

In addition to binaries, xgo can build library archives:

• Android: android/aar
• iOS: ios/framework

Note: Unlike gomobile, xgo does not derive APIs from Go code. You must define proper CGO C external methods within your package.

For iOS frameworks, xgo bundles armv7 and arm64 by default. To include x86_64 simulator builds, you must inject the iPhoneSimulator.sdk into your Docker environment:

1. Use a base image: FROM karalabe/xgo-latest
2. Add the SDK: ADD iPhoneSimulator9.3.sdk.tar.xz /iPhoneSimulator9.3.sdk.tar.xz
3. Bootstrap: $UPDATE_IOS /iPhoneSimulator9.3.sdk.tar.xz

To cross-compile a Go package, provide its import path as the primary argument. xgo will automatically build the package for all supported platforms and architectures.

If you provide a local path (starting with . or /), xgo will use the contents of your local GOPATH for the compilation.

Example:

$ xgo github.com/project-iris/iris

You can use xgo in two ways: by pulling the Docker container directly, or by using the lightweight Go wrapper which simplifies the Docker command execution.

Option 1: Docker Container

Pull the official image from Docker's registry:

docker pull karalabe/xgo-latest

Option 2: Go Wrapper (Recommended)

Install the Go wrapper to avoid managing complex Docker commands manually:

go get github.com/karalabe/xgo

To build from a specific Git branch or a different remote repository while maintaining the original import path, use the --branch and --remote flags.

• --branch <name>: Specifies the branch to use (defaults to master).
• --remote <url>: Specifies the remote repository URL.

Example (Branch):

$ xgo --branch release-branch.go1.4 golang.org/x/tools/cmd/goimports

Example (Remote):

$ xgo --remote github.com/golang/tools golang.org/x/tools/cmd/goimports

You can build Go programs that require external C/C++ libraries using the --deps flag. The dependency must be a configure/make based project provided as a downloadable tarball (.tar, .tar.gz, or .tar.bz2). xgo will download, cross-compile, and cache these dependencies.

Use --depsargs to pass arguments to the dependency's configure script.

Example (with dependency and specific targets):

$ xgo --deps=https://gmplib.org/download/gmp/gmp-6.1.0.tar.bz2  \ 
    --targets=windows/* github.com/ethereum/go-ethereum/cmd/geth

Example (with dependency arguments):

$ 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

By default, xgo uses the package name as the prefix for the generated binaries. Use the -out flag to specify a custom prefix.

Example:

$ xgo -out iris-v0.3.2 github.com/project-iris/iris

By default, xgo builds for all supported platforms and architectures. Use the --targets flag with a comma-separated list to restrict the build.

Target Syntax:

• platform/arch: e.g., --targets=linux/arm (builds ARMv5 Linux binaries).
• platform/*: e.g., --targets=windows/*,darwin/* (builds all Windows and OSX binaries).
• */arch: e.g., --targets=*/arm (builds ARM binaries for all platforms).
• */*: Builds all supported targets (default).

Supported Platforms: android, darwin, ios, linux, windows
Supported Architectures: 386, amd64, arm-5, arm-6, arm-7, arm64, mips, mipsle, mips64, mips64le

Use the -go flag to specify which Go version to use for the build. If the requested version is not already integrated, xgo will attempt to retrieve and install it automatically. Only Go 1.3 and above are supported.

Supported release strings:

• latest: Uses the latest Go release (default).
• 1.6.x: Uses the latest point release of version 1.6.
• 1.6-develop: Uses the develop branch of version 1.6.
• develop: Uses the develop branch of the entire Go repository.

Example:

$ xgo -go 1.6.1 github.com/project-iris/iris

To ensure compatibility with specific OS versions, append the version to the platform string in the --targets flag. This is useful if dependencies require newer system APIs.

Examples:

• --targets=ios-8.1/*: Cross-compile to iOS 8.1.
• --targets=android-16/*: Cross-compile to Android Jelly Bean.
• --targets=darwin-10.9/*: Cross-compile to Mac OS X Mavericks.
• --targets=windows-6.0/*: Cross-compile to Windows Vista.

Supported Ranges:

• Android: All APIs up to Android Lollipop 5.0.
• Windows: All APIs up to Windows 8.1 (limited by mingw-w64).
• OSX: APIs in the range 10.6 - 10.11.
• iOS: All APIs up to iOS 9.3.

If you are using --branch or --remote and the target package is not in the default location, use the --pkg flag to specify the exact package path within the selected repository.

Example:

$ xgo --pkg cmd/goimports golang.org/x/tools

You can pass several standard go build flags through xgo to control the compilation process. Supported flags include:

• -v: Prints package names as they are compiled.
• -x: Prints build commands as compilation progresses.
• -race: Enables data race detection (supported only on amd64; other architectures are built without it).
• -tags='tag list': Specifies build tags.
• -ldflags='flag list': Arguments for the Go tool link invocation.
• -buildmode=mode: Specifies the binary type to produce.