{"id":13587436,"url":"https://github.com/crazy-max/goxx","last_synced_at":"2026-04-02T23:51:13.083Z","repository":{"id":38403360,"uuid":"441964279","full_name":"crazy-max/goxx","owner":"crazy-max","description":"Go CGO cross-compiler Docker image","archived":false,"fork":false,"pushed_at":"2024-03-14T14:04:29.000Z","size":143,"stargazers_count":41,"open_issues_count":3,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-02T01:01:57.171Z","etag":null,"topics":["cgo","cross-compiler","docker","golang"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crazy-max.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"crazy-max","custom":"https://www.paypal.me/crazyws"}},"created_at":"2021-12-26T19:04:43.000Z","updated_at":"2024-06-23T12:29:05.544Z","dependencies_parsed_at":"2024-02-16T07:23:30.072Z","dependency_job_id":"d280f9d7-fe07-4661-974b-dc59ccd5d855","html_url":"https://github.com/crazy-max/goxx","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazy-max%2Fgoxx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazy-max%2Fgoxx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazy-max%2Fgoxx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crazy-max%2Fgoxx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crazy-max","download_url":"https://codeload.github.com/crazy-max/goxx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251722826,"owners_count":21633023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cgo","cross-compiler","docker","golang"],"created_at":"2024-08-01T15:06:12.738Z","updated_at":"2026-04-02T23:51:13.052Z","avatar_url":"https://github.com/crazy-max.png","language":"Shell","funding_links":["https://github.com/sponsors/crazy-max","https://www.paypal.me/crazyws"],"categories":["Shell"],"sub_categories":[],"readme":"[![GitHub release](https://img.shields.io/github/release/crazy-max/goxx.svg?style=flat-square)](https://github.com/crazy-max/goxx/releases/latest)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/crazy-max/goxx/build.yml?branch=main\u0026label=build\u0026logo=github\u0026style=flat-square)](https://github.com/crazy-max/goxx/actions?query=workflow%3Abuild)\n[![Test Status](https://img.shields.io/github/actions/workflow/status/crazy-max/goxx/test.yml?branch=main\u0026label=test\u0026logo=github\u0026style=flat-square)](https://github.com/crazy-max/goxx/actions?query=workflow%3Atest)\n[![Docker Stars](https://img.shields.io/docker/stars/crazymax/goxx?style=flat-square\u0026logo=docker)](https://hub.docker.com/r/crazymax/goxx/)\n[![Docker Pulls](https://img.shields.io/docker/pulls/crazymax/goxx?style=flat-square\u0026logo=docker)](https://hub.docker.com/r/crazymax/goxx/)\n\n[![Become a sponsor](https://img.shields.io/badge/sponsor-crazy--max-181717.svg?logo=github\u0026style=flat-square)](https://github.com/sponsors/crazy-max)\n[![Donate Paypal](https://img.shields.io/badge/donate-paypal-00457c.svg?logo=paypal\u0026style=flat-square)](https://www.paypal.me/crazyws)\n\n___\n\n* [About](#about)\n* [Projects using goxx](#projects-using-goxx)\n* [Docker image](#docker-image)\n* [Supported platforms](#supported-platforms)\n* [Usage](#usage)\n* [Build](#build)\n* [Notes](#notes)\n  * [MacOSX cross toolchain](#macosx-cross-toolchain)\n  * [Wrappers](#wrappers)\n  * [CGO](#cgo)\n  * [Install cross-compilers for all platforms](#install-cross-compilers-for-all-platforms)\n* [Contributing](#contributing)\n* [License](#license)\n\n## About\n\nThis repo contains a Dockerfile for building an image which can be used as a\nbase for building your Go project using CGO. All the necessary Go tool-chains,\nC/C++ cross-compilers and platform headers/libraries can be installed with the\nspecially crafted [wrappers](#wrappers). This project is heavily inspired by\n[`xx` project](https://github.com/tonistiigi/xx/).\n\n## Projects using goxx\n\n* [goreleaser-xx](https://github.com/crazy-max/goreleaser-xx)\n* [xgo](https://github.com/crazy-max/xgo)\n\n## Docker image\n\n| Registry                                                                                        | Image                        |\n|-------------------------------------------------------------------------------------------------|------------------------------|\n| [Docker Hub](https://hub.docker.com/r/crazymax/goxx/)                                           | `crazymax/goxx`              |\n| [GitHub Container Registry](https://github.com/users/crazy-max/packages/container/package/goxx) | `ghcr.io/crazy-max/goxx`     |\n\n```\n$ docker run --rm mplatform/mquery crazymax/goxx:latest\nImage: crazymax/goxx:latest\n * Manifest List: Yes\n * Supported platforms:\n   - linux/amd64\n   - linux/arm64\n```\n\n## Supported platforms\n\n| Platform             | `CC`                           | `CXX`                          |\n|----------------------|--------------------------------|--------------------------------|\n| `darwin/amd64`¹      | `o64-clang`                    | `o64-clang++`                  |\n| `darwin/arm64`¹      | `o64-clang`                    | `o64-clang++`                  |\n| `linux/386`          | `i686-linux-gnu-gcc`           | `i686-linux-gnu-g++`           |\n| `linux/amd64`        | `x86_64-linux-gnu-gcc`         | `x86_64-linux-gnu-g++`         |\n| `linux/arm64`        | `aarch64-linux-gnu-gcc`        | `aarch64-linux-gnu-g++`        |\n| `linux/arm/v5`       | `arm-linux-gnueabi-gcc`        | `arm-linux-gnueabi-g++`        |\n| `linux/arm/v6`       | `arm-linux-gnueabi-gcc`        | `arm-linux-gnueabi-g++`        |\n| `linux/arm/v7`       | `arm-linux-gnueabihf-gcc`      | `arm-linux-gnueabihf-g++`      |\n| `linux/mips`²        | `mips-linux-gnu-gcc`           | `mips-linux-gnu-g++`           |\n| `linux/mipsle`²      | `mipsel-linux-gnu-gcc`         | `mipsel-linux-gnu-g++`         |\n| `linux/mips64`²      | `mips64-linux-gnuabi64-gcc`    | `mips64-linux-gnuabi64-g++`    |\n| `linux/mips64le`²    | `mips64el-linux-gnuabi64-gcc`  | `mips64el-linux-gnuabi64-g++`  |\n| `linux/ppc64le`      | `powerpc64le-linux-gnu-gcc`    | `powerpc64le-linux-gnu-g++`    |\n| `linux/riscv64`      | `riscv64-linux-gnu-gcc`        | `riscv64-linux-gnu-g++`        |\n| `linux/s390x`        | `s390x-linux-gnu-gcc`          | `s390x-linux-gnu-g++`          |\n| `windows/386`        | `i686-w64-mingw32-gcc`         | `i686-w64-mingw32-g++`         |\n| `windows/amd64`      | `x86_64-w64-mingw32-gcc`       | `x86_64-w64-mingw32-g++`       |\n\n\u003e ¹ `darwin*` platform requires the [MacOSX cross toolchain](#macosx-cross-toolchain)\n\u003e if using CGO.\n\u003e\n\u003e ² compilers for `mips*` archs are not available with `linux/arm64` image.\n\n## Usage\n\nIn order to use this image effectively, we will use the `docker buildx` command.\n[Buildx](https://github.com/docker/buildx) is a Docker component that enables\nmany powerful build features. All builds executed via buildx run with\n[Moby BuildKit](https://github.com/moby/buildkit) builder engine.\n\n```dockerfile\n# syntax=docker/dockerfile:1\n\nFROM --platform=$BUILDPLATFORM crazymax/goxx:1.17 AS base\nENV GO111MODULE=auto\nENV CGO_ENABLED=1\nWORKDIR /go/src/hello\n\nFROM base AS build\nARG TARGETPLATFORM\nRUN --mount=type=cache,sharing=private,target=/var/cache/apt \\\n  --mount=type=cache,sharing=private,target=/var/lib/apt/lists \\\n  goxx-apt-get install -y binutils gcc g++ pkg-config\nRUN --mount=type=bind,source=. \\\n  --mount=type=cache,target=/root/.cache \\\n  --mount=type=cache,target=/go/pkg/mod \\\n  goxx-go build -o /out/hello ./hello.go\n\nFROM scratch AS artifact\nCOPY --from=build /out /\n\nFROM scratch\nCOPY --from=build /out/hello /hello\nENTRYPOINT [ \"/hello\" ]\n```\n\n* `FROM --platform=$BUILDPLATFORM ...` command will pull an image that will\n  always match the native platform of your machine (e.g., `linux/amd64`).\n  `BUILDPLATFORM` is part of the [ARGs in the global scope](https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope).\n* `ARG TARGETPLATFORM` is also an ARG in the global scope that will be set\n  to the platform of the target that will default to your current platform or\n  can be defined via the [`--platform` flag](https://docs.docker.com/engine/reference/commandline/buildx_build/#platform)\n  of buildx so [`goxx-*` wrappers](#wrappers) will be able to automatically\n  build against the right platform.\n\n\u003e More details about multi-platform builds in this [blog post](https://medium.com/@tonistiigi/faster-multi-platform-builds-dockerfile-cross-compilation-guide-part-1-ec087c719eaf).\n\nLet's run a simple build against the `artifact` target in our Dockerfile:\n\n```shell\n# build and output content of the artifact stage that contains the binaries in ./dist\ndocker buildx build \\\n  --platform \"linux/amd64,linux/arm64,linux/arm/v7,darwin/amd64\" \\\n  --output \"./dist\" \\\n  --target \"artifact\" .\n\n$ tree ./dist\n./dist\n├── darwin_amd64\n│ ├── hello\n├── linux_amd64\n│ ├── hello\n├── linux_arm64\n│ ├── hello\n├── linux_arm_v7\n│ ├── hello\n```\n\nYou can also create a multi-platform image in addition to the artifacts:\n\n```shell\ndocker buildx build \\\n  --platform \"linux/amd64,linux/arm64,linux/arm/v7\" \\\n  --tag \"hello:latest\" \\\n  --push .\n```\n\nMore examples can be found in the [`examples` folder](examples).\n\n## Build\n\nBuild goxx yourself using Docker [`buildx bake`](https://github.com/docker/buildx/blob/master/docs/reference/buildx_bake.md):\n\n```shell\ngit clone https://github.com/crazy-max/goxx.git goxx\ncd goxx\n\n# create docker container builder\ndocker buildx create --name goxx --use\n\n# build goxx image and output to docker with goxx:local tag (default)\ndocker buildx bake image-local\n\n# examples\n(cd ./examples/c ; docker buildx bake artifact-all)\n(cd ./examples/cpp ; docker buildx bake artifact-all)\n(cd ./examples/echo ; docker buildx bake artifact-all)\n(cd ./examples/gorm ; docker buildx bake artifact-all)\n(cd ./examples/jq ; docker buildx bake artifact-all)\n```\n\n## Notes\n\n### MacOSX cross toolchain\n\nYou can use the MacOSX cross toolchain provided by [`crazymax/osxcross`](https://github.com/crazy-max/docker-osxcross)\nimage to build against the `darwin` platform with CGO.\n\nUsing the `COPY` command:\n\n```dockerfile\nFROM --platform=$BUILDPLATFORM crazymax/osxcross:11.3 AS osxcross\nFROM base AS build\nCOPY --from=osxcross /osxcross /osxcross\nARG TARGETPLATFORM\nRUN --mount=type=bind,source=. \\\n  --mount=type=cache,target=/root/.cache \\\n  --mount=type=cache,target=/go/pkg/mod \\\n  goxx-go build -o /out/hello ./hello.go\n```\n\nOr a `RUN` mount:\n\n```dockerfile\nFROM --platform=$BUILDPLATFORM crazymax/osxcross:11.3 AS osxcross\nFROM base AS build\nARG TARGETPLATFORM\nRUN --mount=type=bind,source=. \\\n  --mount=from=osxcross,target=/osxcross,src=/osxcross,rw \\\n  --mount=type=cache,target=/root/.cache \\\n  --mount=type=cache,target=/go/pkg/mod \\\n  goxx-go build -o /out/hello ./hello.go\n```\n\n### Wrappers\n\nWrappers are a significant part of this repo to dynamically handle the build\nprocess with a `go` wrapper named [`goxx-go`](rootfs/usr/local/bin/goxx-go) which\nwill automatically sets values for `GOOS`, `GOARCH`, `GOARM`, `GOMIPS`, etc. but\nalso `AR`, `CC`, `CXX` if building with CGO based on defined [ARGs in the global scope](https://docs.docker.com/engine/reference/builder/#automatic-platform-args-in-the-global-scope)\nlike `TARGETPLATFORM`.\n\nIt also manages debian packages for cross-compiling for non-native architectures with\n[`goxx-apt-get`](rootfs/usr/local/bin/goxx-apt-get) and [`goxx-macports`](rootfs/usr/local/bin/goxx-macports)\nto install MacPorts packages.\n\n### CGO\n\nBy default, CGO is enabled in Go when compiling for native architecture and\ndisabled when cross-compiling. It's therefore recommended to always set\n`CGO_ENABLED=0` or `CGO_ENABLED=1` when cross-compiling depending on whether\nyou need to use CGO or not.\n\n### Install cross-compilers for all platforms\n\nIn some case you may want to install cross-compilers for all supported platforms\ninto a fat image:\n\n```dockerfile\n# syntax=docker/dockerfile:1-labs\n\nARG PLATFORMS=\"linux/386 linux/amd64 linux/arm64 linux/arm/v5 linux/arm/v6 linux/arm/v7 linux/mips linux/mipsle linux/mips64 linux/mips64le linux/ppc64le linux/riscv64 linux/s390x windows/386 windows/amd64\"\n\nFROM --platform=$BUILDPLATFORM crazymax/goxx:1.17 AS base\nARG PLATFORMS\nRUN \u003c\u003cEOT\nexport GOXX_SKIP_APT_PORTS=1\ngoxx-apt-get update\nfor p in $PLATFORMS; do\n  TARGETPLATFORM=$p goxx-apt-get install -y binutils gcc g++ pkg-config\ndone\nEOT\n```\n\n\u003e **Note**: This is not recommended for production use.\n\n## Contributing\n\nWant to contribute? Awesome! The most basic way to show your support is to star\nthe project, or to raise issues. You can also support this project by\n[**becoming a sponsor on GitHub**](https://github.com/sponsors/crazy-max) or by\nmaking a [Paypal donation](https://www.paypal.me/crazyws) to ensure this journey\ncontinues indefinitely!\n\nThanks again for your support, it is much appreciated! :pray:\n\n## License\n\nMIT. See `LICENSE` for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrazy-max%2Fgoxx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrazy-max%2Fgoxx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrazy-max%2Fgoxx/lists"}