xgo

Go CGO cross compiler

2,142

280

2,142

104

View on GitHub

Top Related Projects

docker-ce

5,754

:warning: This repository is deprecated and will be archived (Docker CE itself is NOT deprecated) see the https://github.com/docker/docker-ce/blob/master/README.md :warning:

moby

68,613

The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems

gox

4,601

A dead simple, no frills Go cross compile tool

goreleaser

13,719

Deliver Go binaries as fast and easily as possible

mkcert

51,244

A simple zero-config tool to make locally trusted development certificates with any names you'd like.

Quick Overview

Xgo is a Go (Golang) cross-compilation tool that allows developers to easily build Go binaries for multiple platforms and architectures. It uses Docker containers to provide a consistent build environment, ensuring that the compiled binaries are compatible with their target systems.

Pros

Simplifies cross-compilation for multiple platforms and architectures
Uses Docker containers for consistent build environments
Supports CGo-enabled packages
Integrates well with existing Go toolchains and build processes

Cons

Requires Docker to be installed and running
May have a steeper learning curve compared to native Go cross-compilation
Limited to the platforms and architectures supported by the tool
Potential performance overhead due to Docker container usage

Getting Started

To use xgo, follow these steps:

Install Docker on your system
Install xgo:
```
go get -u github.com/karalabe/xgo
```

Build your Go project for multiple platforms:

xgo --targets=windows/amd64,linux/amd64,darwin/amd64 github.com/your/package

This will compile your Go package for Windows, Linux, and macOS (64-bit versions). The resulting binaries will be placed in your current directory.

Competitor Comparisons

go

123,517

The Go programming language

Pros of go

Official Go programming language repository
Comprehensive documentation and extensive community support
Regular updates and maintenance by the Go team at Google

Cons of go

Not designed for cross-compilation out of the box
Requires additional setup for building Go projects for multiple platforms

Code comparison

go:

package main

import "fmt"

func main() {
    fmt.Println("Hello, World!")
}

xgo:

// No specific code example needed for xgo, as it uses standard Go code
// The difference is in the build process, not the code itself

Summary

go is the official Go programming language repository, offering comprehensive documentation and regular updates. However, it's not primarily designed for cross-compilation.

xgo, on the other hand, is a Go cross-compilation tool that simplifies building Go projects for multiple platforms. It doesn't modify the Go code itself but provides an easier way to compile for different architectures and operating systems.

While go requires additional setup for cross-compilation, xgo streamlines this process, making it more convenient for developers working on multi-platform projects. However, xgo is a third-party tool and may not always be in sync with the latest Go updates.

docker-ce

5,754

:warning: This repository is deprecated and will be archived (Docker CE itself is NOT deprecated) see the https://github.com/docker/docker-ce/blob/master/README.md :warning:

Pros of docker-ce

Comprehensive container platform with a wide range of features
Large community support and extensive documentation
Robust ecosystem with numerous integrations and tools

Cons of docker-ce

Larger footprint and more complex setup compared to xgo
May be overkill for simple cross-compilation tasks
Steeper learning curve for users new to containerization

Code Comparison

xgo:

xgo --targets=windows/amd64,darwin/amd64 github.com/example/project

docker-ce:

docker build -t myapp .
docker run --rm myapp

Key Differences

xgo focuses specifically on Go cross-compilation, while docker-ce is a full container platform
xgo provides a simpler interface for cross-compilation tasks
docker-ce offers more flexibility and can be used for various languages and applications

Use Cases

xgo: Ideal for Go developers needing quick and easy cross-compilation
docker-ce: Suitable for complex applications, microservices, and multi-language projects

Community and Support

xgo: Smaller community, focused on Go developers
docker-ce: Large, diverse community with extensive resources and third-party support

moby

68,613

The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems

Pros of Moby

Larger, more active community with frequent updates and contributions
Comprehensive container ecosystem with broader functionality
Extensive documentation and resources for users and developers

Cons of Moby

More complex architecture and larger codebase
Steeper learning curve for newcomers
Potentially overkill for simple cross-compilation tasks

Code Comparison

Xgo (simplified cross-compilation):

xgo --targets=windows/amd64,darwin/amd64 github.com/example/project

Moby (Docker build example):

FROM golang:1.16
WORKDIR /app
COPY . .
RUN go build -o myapp
CMD ["./myapp"]

Key Differences

Xgo focuses specifically on Go cross-compilation, while Moby is a comprehensive container platform
Xgo is more lightweight and easier to use for simple cross-compilation tasks
Moby offers a complete container ecosystem with advanced features beyond just building binaries

Use Cases

Choose Xgo for straightforward Go cross-compilation projects
Opt for Moby when building containerized applications or requiring a full container ecosystem

gox

4,601

A dead simple, no frills Go cross compile tool

Pros of gox

Simpler setup and usage, requiring fewer dependencies
Faster build times for single-platform compilations
Lightweight and easy to integrate into existing workflows

Cons of gox

Limited cross-compilation capabilities compared to xgo
Lacks support for CGo and more complex build scenarios
May require manual setup for certain target platforms

Code Comparison

gox:

package main

import "github.com/mitchellh/gox"

func main() {
    gox.Build()
}

xgo:

package main

import "github.com/karalabe/xgo"

func main() {
    xgo.Build()
}

Summary

gox is a straightforward tool for Go cross-compilation, offering simplicity and speed for basic use cases. It's ideal for projects with minimal dependencies and straightforward build requirements. However, it falls short in handling complex scenarios involving CGo or extensive cross-platform support.

xgo, on the other hand, provides more robust cross-compilation capabilities, including CGo support and a wider range of target platforms. It uses Docker containers to ensure consistent build environments, making it more suitable for complex projects with diverse dependencies and platform requirements.

While gox is easier to set up and use for simple projects, xgo offers greater flexibility and power for more demanding cross-compilation needs. The choice between the two depends on the specific requirements of your project and the level of cross-platform support needed.

goreleaser

13,719

Deliver Go binaries as fast and easily as possible

Pros of GoReleaser

Comprehensive release automation tool, handling multiple aspects of the release process
Supports various package formats and distribution platforms
Extensive configuration options for customizing the release process

Cons of GoReleaser

Primarily focused on release management, not cross-compilation
May have a steeper learning curve due to its extensive feature set
Requires more setup and configuration for cross-platform builds

Code Comparison

GoReleaser configuration example:

builds:
  - env:
      - CGO_ENABLED=0
    goos:
      - linux
      - windows
      - darwin
    goarch:
      - amd64
      - arm64

xgo usage example:

xgo --targets=linux/amd64,windows/amd64,darwin/amd64 .

Summary

GoReleaser is a comprehensive release automation tool that handles various aspects of the release process, including cross-compilation. It offers extensive configuration options and supports multiple package formats and distribution platforms. However, it may have a steeper learning curve and requires more setup for cross-platform builds.

xgo, on the other hand, is specifically designed for easy cross-compilation of Go projects. It provides a simpler interface for building Go binaries for multiple platforms and architectures, but lacks the broader release management features offered by GoReleaser.

mkcert

51,244

A simple zero-config tool to make locally trusted development certificates with any names you'd like.

Pros of mkcert

Focused on local HTTPS development, making it easier to set up secure local environments
Automatically installs the generated certificate as a trusted root CA on the system
Supports multiple platforms and browsers out of the box

Cons of mkcert

Limited to certificate generation and installation, not a full cross-compilation tool
May require additional configuration for complex development environments
Does not provide direct support for cross-platform binary compilation

Code Comparison

mkcert:

cert, err := x509.CreateCertificate(rand.Reader, &template, &template, &priv.PublicKey, priv)
if err != nil {
    return nil, nil, err
}

xgo:

cmd := exec.Command("docker", append([]string{"run", "--rm", "-v", volume + ":/build", image}, args...)...)
if out, err := cmd.CombinedOutput(); err != nil {
    return fmt.Errorf("failed to cross compile: %v\n%s", err, out)
}

Summary

mkcert is a specialized tool for generating locally-trusted development certificates, while xgo is a Go cross-compilation tool using Docker. mkcert excels in simplifying HTTPS setup for local development, whereas xgo focuses on building Go binaries for multiple platforms. The code snippets highlight their different purposes: mkcert deals with certificate creation, while xgo manages Docker-based cross-compilation processes.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

xgo - Go CGO cross compiler

Although Go strives to be a cross platform language, cross compilation from one platform to another is not as simple as it could be, as you need the Go sources bootstrapped to each platform and architecture.

The first step towards cross compiling was Dave Cheney's golang-crosscompile package, which automatically bootstrapped the necessary sources based on your existing Go installation. Although this was enough for a lot of cases, certain drawbacks became apparent where the official libraries used CGO internally: any dependency to third party platform code is unavailable, hence those parts don't cross compile nicely (native DNS resolution, system certificate access, etc).

A step forward in enabling cross compilation was Alan Shreve's gonative package, which instead of bootstrapping the different platforms based on the existing Go installation, downloaded the official pre-compiled binaries from the golang website and injected those into the local toolchain. Since the pre-built binaries already contained the necessary platform specific code, the few missing dependencies were resolved, and true cross compilation could commence... of pure Go code.

However, there was still one feature missing: cross compiling Go code that used CGO itself, which isn't trivial since you need access to OS specific headers and libraries. This becomes very annoying when you need access only to some trivial OS specific functionality (e.g. query the CPU load), but need to configure and maintain separate build environments to do it.

Enter xgo

My solution to the challenge of cross compiling Go code with embedded C/C++ snippets (i.e. CGO_ENABLED=1) is based on the concept of lightweight Linux containers. All the necessary Go tool-chains, C cross compilers and platform headers/libraries have been assembled into a single Docker container, which can then be called as if a single command to compile a Go package to various platforms and architectures.

Installation

Although you could build the container manually, it is available as an automatic trusted build from Docker's container registry (not insignificant in size):

docker pull karalabe/xgo-latest

To prevent having to remember a potentially complex Docker command every time, a lightweight Go wrapper was written on top of it.

go get github.com/karalabe/xgo

Usage

Simply specify the import path you want to build, and xgo will do the rest:

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

$ ls -al
-rwxr-xr-x  1 root  root    9995000 Nov 24 16:44 iris-android-16-arm
-rwxr-xr-x  1 root  root    6776500 Nov 24 16:44 iris-darwin-10.6-386
-rwxr-xr-x  1 root  root    8755532 Nov 24 16:44 iris-darwin-10.6-amd64
-rwxr-xr-x  1 root  root    7114176 Nov 24 16:45 iris-ios-5.0-arm
-rwxr-xr-x  1 root  root   10135248 Nov 24 16:44 iris-linux-386
-rwxr-xr-x  1 root  root   12598472 Nov 24 16:44 iris-linux-amd64
-rwxr-xr-x  1 root  root   10040464 Nov 24 16:44 iris-linux-arm
-rwxr-xr-x  1 root  root    7516368 Nov 24 16:44 iris-windows-4.0-386.exe
-rwxr-xr-x  1 root  root    9549416 Nov 24 16:44 iris-windows-4.0-amd64.exe

If the path is not a canonical import path, but rather a local path (starts with a dot . or a dash /), xgo will use the local GOPATH contents for the cross compilation.

Build flags

A handful of flags can be passed to go build. The currently supported ones are

-v: prints the names of packages as they are compiled
-x: prints the build commands as compilation progresses
-race: enables data race detection (supported only on amd64, rest built without)
-tags='tag list': list of build tags to consider satisfied during the build
-ldflags='flag list': arguments to pass on each go tool link invocation
-buildmode=mode: binary type to produce by the compiler

Go releases

As newer versions of the language runtime, libraries and tools get released, these will get incorporated into xgo too as extensions layers to the base cross compilation image (only Go 1.3 and above will be supported).

You can select which Go release to work with through the -go command line flag to xgo and if the specific release was already integrated, it will automatically be retrieved and installed.

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

Additionally, a few wildcard release strings are also supported:

latest will use the latest Go release (this is the default)
1.6.x will use the latest point release of a specific Go version
1.6-develop will use the develop branch of a specific Go version
develop will use the develop branch of the entire Go repository

Output prefixing

xgo by default uses the name of the package being cross compiled as the output file prefix. This can be overridden with the -out flag.

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

$ ls -al
-rwxr-xr-x  1 root  root   9995000 Nov 24 16:44 iris-v0.3.2-android-16-arm
-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   7114176 Nov 24 16:45 iris-v0.3.2-ios-5.0-arm
-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

Branch selection

Similarly to go get, xgo also uses the master branch of a repository during source code retrieval. To switch to a different branch before compilation pass the desired branch name through the --branch argument.

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

$ ls -al
-rwxr-xr-x  1 root  root   4171248 Nov 24 16:40 goimports-android-16-arm
-rwxr-xr-x  1 root  root   4139868 Nov 24 16:40 goimports-darwin-10.6-386
-rwxr-xr-x  1 root  root   5186720 Nov 24 16:40 goimports-darwin-10.6-amd64
-rwxr-xr-x  1 root  root   3202364 Nov 24 16:40 goimports-ios-5.0-arm
-rwxr-xr-x  1 root  root   4189456 Nov 24 16:40 goimports-linux-386
-rwxr-xr-x  1 root  root   5264136 Nov 24 16:40 goimports-linux-amd64
-rwxr-xr-x  1 root  root   4209416 Nov 24 16:40 goimports-linux-arm
-rwxr-xr-x  1 root  root   4348416 Nov 24 16:40 goimports-windows-4.0-386.exe
-rwxr-xr-x  1 root  root   5415424 Nov 24 16:40 goimports-windows-4.0-amd64.exe

Remote selection

Yet again similarly to go get, xgo uses the repository remote corresponding to the import path being built. To switch to a different remote while preserving the original import path, use the --remote argument.

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

Package selection

If you used the above branch or remote selection machanisms, it may happen that the path you are trying to build is only present in the specific branch and not the default repository, causing Go to fail at locating it. To circumvent this, you may specify only the repository root for xgo, and use an additional --pkg parameter to select the exact package within, honoring any prior branch and remote selections.

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

$ ls -al
-rwxr-xr-x  1 root  root   4194956 Nov 24 16:38 goimports-android-16-arm
-rwxr-xr-x  1 root  root   4164448 Nov 24 16:38 goimports-darwin-10.6-386
-rwxr-xr-x  1 root  root   5223584 Nov 24 16:38 goimports-darwin-10.6-amd64
-rwxr-xr-x  1 root  root   3222848 Nov 24 16:39 goimports-ios-5.0-arm
-rwxr-xr-x  1 root  root   4217184 Nov 24 16:38 goimports-linux-386
-rwxr-xr-x  1 root  root   5295768 Nov 24 16:38 goimports-linux-amd64
-rwxr-xr-x  1 root  root   4233120 Nov 24 16:38 goimports-linux-arm
-rwxr-xr-x  1 root  root   4373504 Nov 24 16:38 goimports-windows-4.0-386.exe
-rwxr-xr-x  1 root  root   5450240 Nov 24 16:38 goimports-windows-4.0-amd64.exe

This argument may at some point be integrated into the import path itself, but for now it exists as an independent build parameter. Also, there is not possibility for now to build mulitple commands in one go.

Limit build targets

By default xgo will try and build the specified package to all platforms and architectures supported by the underlying Go runtime. If you wish to restrict the build to only a few target systems, use the comma separated --targets CLI argument:

--targets=linux/arm: builds only the ARMv5 Linux binaries (arm-6/arm-7 allowed)
--targets=windows/*,darwin/*: builds all Windows and OSX binaries
--targets=*/arm: builds ARM binaries for all platforms
--targets=*/*: builds all suppoted targets (default)

The supported targets are:

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

Platform versions

By default xgo tries to cross compile to the lowest possible versions of every supported platform, in order to produce binaries that are portable among various versions of the same operating system. This however can lead to issues if a used dependency is only supported by more recent systems. As such, xgo supports the selection of specific platform versions by appending them to the OS target string.

--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

The supported platforms are:

All Android APIs up to Android Lollipop 5.0 (API level ids)
All Windows APIs up to Windows 8.1 limited by mingw-w64 (API level ids)
OSX APIs in the range of 10.6 - 10.11
All iOS APIs up to iOS 9.3

Mobile libraries

Apart from the usual runnable binaries, xgo also supports building library archives for Android (android/aar) and iOS (ios/framework). Opposed to gomobile however xgo does not derive library APIs from the Go code, so proper CGO C external methods must be defined within the package.

In the case of Android archives, all architectures will be bundled that are supported by the requested Android platform version. For iOS frameworks xgo will bundle armv7 and arm64 by default, and also the x86_64 simulator builds if the iPhoneSimulator.sdk was injected by the user:

Create a new docker image based on xgo: FROM karalabe/xgo-latest
Inject the simulator SDK: ADD iPhoneSimulator9.3.sdk.tar.xz /iPhoneSimulator9.3.sdk.tar.xz
Bootstrap the simulator SDK: $UPDATE_IOS /iPhoneSimulator9.3.sdk.tar.xz

CGO dependencies

The main differentiator of xgo versus other cross compilers is support for basic embedded C/C++ code and target-platform specific OS SDK availability. The current xgo release introduces an experimental CGO dependency cross compilation, enabling building Go programs that require external C/C++ libraries.

It is assumed that the dependent C/C++ library is configure/make based, was properly prepared for cross compilation and is available as a tarball download (.tar, .tar.gz or .tar.bz2). Further plans include extending this to cmake based projects, if need arises (please open an issue if it's important to you).

Such dependencies can be added via the --deps argument. They will be retrieved prior to starting the cross compilation and the packages cached to save bandwidth on subsequent calls.

A complex sample for such a scenario is building the Ethereum CLI node, which has the GNU Multiple Precision Arithmetic Library as it's dependency.

$ 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

Some trivial arguments may be passed to the dependencies' configure script via --depsargs.

$ 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

Note, that since xgo needs to cross compile the dependencies for each platform and architecture separately, build time can increase significantly.

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot