go-xbuild-go

Table Of Contents

• Introduction
• Background and Motivation
• How to use
• Features
• Synopsis
• Version
• Installation
  • Download
  • Building from source
• Usage
  • Legacy mode (single binary)
  • Multi-binary mode
• Multi-Binary Configuration
• Output Structure
  • Legacy mode:
  • Multi-binary mode:
• Included Files
• How to release your project to github
• Contributing
• License
• Author

Introduction

A multi-platform program to cross compile go projects without the complexity of GoReleaser. The program can be used to:

• Cross compile go projects for various platforms - with ease
• Build multi-binary Go projects - handle projects with multiple main packages like cmd/cli/, cmd/server/, etc.
• Make releases to github - with ease. Not just go projects, any project can be released to github, just copy the assets to ./bin directory. Please look at Look at How to release your project to github for details.

Background and Motivation

It was written from the frustration of using GoReleaser. I don't release often, whenever the time comes to release using GoReleaser, something has changed. I got tired of dealing with GoReleaser's complexity when I only release software occasionally. When I release every 6-12 months or so, GoReleaser's config often needs updates due to changes. This simple program just works. Hope you will find it useful and fun to use.

This is a go port of my bash script https://github.com/muquit/go-xbuild

Pull requests, suggestions are always welcome.

How to use

There are two ways to use go-xbuild-go:

For simple projects (legacy mode):

• Copy go-xbuild-go somewhere in your PATH
• Copy platforms.txt to your go project's root directory
• Create a VERSION file with your version (e.g., v1.0.1)
• Edit platforms.txt to uncomment the platforms you want to build for
• Run: go-xbuild-go

For complex projects with multiple binaries (new in v1.0.5):

• Copy go-xbuild-go somewhere in your PATH
• Create a build-config.json file (see Multi-Binary Configuration)
• Run: go-xbuild-go -config build-config.json

Look at How to release your project to github

Note: go programs can be cross compiled for more than 40 platforms. go tool dist list for the list supported by your version of go.

A few lines of platforms.txt is shown below:

########################################################################
# GOOS/GOARCH
# generated by running: go tool dist list
# Uncomment or add platforms if needed
########################################################################
#aix/ppc64
#android/386
darwin/amd64
darwin/arm64
windows/amd64
#linux/386
linux/amd64
#linux/arm
#linux/arm64
...

Features

• Simple to use and maintain
• Cross compile for multiple platforms
• NEW in v1.0.5: Multi-binary project support with JSON configuration
• NEW in v1.0.5: Build multiple main packages from cmd/ directory structure
• NEW in v1.0.5: Per-target customization (ldflags, build flags, output names)
• NEW in v1.0.5: List available build targets with -list-targets
• Special handling for Raspberry Pi (modern and Jessie)
• Generates checksums
• Creates archives (ZIP for Windows, tar.gz for others)
• No complex configuration files (for simple projects)
• Just uncomment platforms in platforms.txt to build for them
• Make release of the project to github
• Full backward compatibility - existing projects work unchanged

Synopsis

./go-xbuild-go v1.0.5
A program to cross compile go programs

Environment variables (for github release):
  GITHUB_TOKEN     GitHub API token (required for -release)
  GH_CLI_PATH      Custom path to GitHub CLI executable (optional)

Usage:
  Legacy mode (single binary):
  - Copy platforms.txt at the root of your project
  - Edit platforms.txt to uncomment the platforms you want to build for
  - Create a VERSION file with your version (e.g. v1.0.1)
  - Then run ./go-xbuild-go

  Multi-binary mode:
  - Create a build-config.json file (see example below)
  - Run ./go-xbuild-go -config build-config.json

Options:
  -additional-files string
    	Comma-separated list of additional files to include in archives
  -config string
    	Path to build configuration file (JSON)
  -help
    	Show help information and exit
  -list-targets
    	List available build targets and exit
  -pi
    	Build Raspberry Pi (default true)
  -release
    	Create a GitHub release
  -release-note string
    	Release note text (required if -release-note-file not specified and release_notes.md doesn't exist)
  -release-note-file string
    	File containing release notes (required if -release-note not specified and release_notes.md doesn't exist)
  -version
    	Show version information and exit
Notes:
 The following files are automatically included if they exist:
 README.md, LICENSE.txt, LICENSE, platforms.txt, <project>.1
 Do not specify these files in -additional-files as they will conflict.


For single-main project, there is no need for any configuration
But configuration is required for multi-main project
Example build-config.json for multi-main project:
{
  "project_name": "myproject",
  "version_file": "VERSION",
  "platforms_file": "platforms.txt",
  "default_ldflags": "-s -w",
  "default_build_flags": "-trimpath",
  "targets": [
    {
      "name": "cli",
      "path": "./cmd/cli"
	  "output_name": "mycli"
    },
    {
      "name": "server",
      "path": "./cmd/server",
      "output_name": "myserver"
    }
  ]
}

Version

The current version is 1.0.5

Please look at ChangeLog for what has changed in the current version.

Installation

Download

Download pre-compiled binaries from Releases page

Please look at How to use

Building from source

Install go first

git clone https://github.com/muquit/go-xbuild-go
cd go-xbuild-go
go build .

Please look at How to use

Usage

Legacy mode (single binary)

Run go-xbuild-go from the root of your project. Update VERSION file if needed. Then, compile the binaries:

go-xbuild-go

The program will:

1. Detect your project name from the directory
2. Read version from VERSION file
3. Build for all uncommented platforms in platforms.txt
4. Create appropriate archives (ZIP for Windows, tar.gz for others)
5. Generate checksums for all archives
6. Place all artifacts in ./bin directory

Multi-binary mode

For projects with multiple main packages (e.g., cmd/cli/, cmd/server/), create a build-config.json file and run:

# List available targets
go-xbuild-go -config build-config.json -list-targets

# Build all targets
go-xbuild-go -config build-config.json

# Create GitHub release
go-xbuild-go -release -release-note "Multi-binary release"

Multi-Binary Configuration

The JSON configuration file supports the following structure:

{
  "project_name": "myproject",
  "version_file": "VERSION",
  "platforms_file": "platforms.txt",
  "default_ldflags": "-s -w -X main.version={{.Version}} -X main.commit={{.Commit}}",
  "default_build_flags": "-trimpath",
  "targets": [
    {
      "name": "cli",
      "path": "./cmd/cli",
      "output_name": "mycli"
    },
    {
      "name": "server", 
      "path": "./cmd/server",
      "output_name": "myserver"
    },
    {
      "name": "admin",
      "path": "./cmd/admin"
    }
  ]
}

Configuration options:

• project_name: Project name used in archive names
• version_file: Path to file containing version (default: "VERSION")
• platforms_file: Path to platforms definition file (default: "platforms.txt")
• default_ldflags: Default linker flags applied to all targets
• default_build_flags: Default build flags applied to all targets
• targets: Array of build targets

Target options:

• name: Target identifier (used in -list-targets)
• path: Path to main package (e.g., "./cmd/cli")
• output_name: Custom binary name (optional, defaults to target name)

Variable substitution in ldflags:

• {{.Version}}: Replaced with version from VERSION file
• {{.Commit}}: Replaced with current git commit hash
• {{.Date}}: Replaced with build timestamp

Example project structure:

myproject/
├── cmd/
│   ├── cli/main.go
│   ├── server/main.go
│   └── admin/main.go
├── build-config.json
├── platforms.txt
├── VERSION
└── README.md

For a complete working example, see: go-multi-main-example

Output Structure

Legacy mode:

bin/
├── project-v1.0.1-darwin-amd64.d.tar.gz
├── project-v1.0.1-darwin-arm64.d.tar.gz
├── project-v1.0.1-windows-amd64.d.zip
├── project-v1.0.1-linux-amd64.d.tar.gz
├── project-v1.0.1-raspberry-pi.d.tar.gz
├── project-v1.0.1-raspberry-pi-jessie.d.tar.gz
└── project-v1.0.1-checksums.txt

Multi-binary mode:

bin/
├── mycli-v1.0.1-darwin-amd64.d.tar.gz
├── mycli-v1.0.1-linux-amd64.d.tar.gz
├── myserver-v1.0.1-darwin-amd64.d.tar.gz
├── myserver-v1.0.1-linux-amd64.d.tar.gz
├── admin-v1.0.1-darwin-amd64.d.tar.gz
├── admin-v1.0.1-linux-amd64.d.tar.gz
└── myproject-v1.0.1-checksums.txt

Included Files

The following files will be included in archives if they exist:

• Compiled binary
• README.md
• LICENSE.txt
• docs/project-name.1 (man page)
• platforms.txt
• Add extra files with -additional-files (Do not add these default: README.md, LICENSE.txt, LICENSE, platforms.txt, .1)

How to release your project to github

Now that you cross-compiled and created archives for your go project, you can use go-xbuild-go to publish it to GitHub. Note: any project can be released to github using this tool, not just go projects.

1. Make sure you have the GitHub CLI gh is installed. By default, the path will be searched to find it. However, the environment variable GH_CLI_PATH can be set to specify an alternate path.

2. Set up your GitHub token:

   • Get a GitHub token from Profile image -> Settings -> Developer Settings

   • Click on Personal access tokens

   • Select Tokens (classic)

   • Select the Checkbox at the left side of repo

   • Click on Generate token at the bottom

   • Save the token securely

   • Export it: export GITHUB_TOKEN=your_github_token

   • Create a release notes file release_notes.md at the root of your project. The options -release-note or -release-notes-file can be used to specify the release notes.

3. Update VERSION file if needed. The Release and tag with the content of VERSION file will be created.

Now Run:

go-xbuild-go \
        -release \
        -release-note "Release v1.0.1"

go-xbuild-go -release

By default, it looks file release_notes.md in the current working directory.

Contributing

Pull requests welcome! Please keep it simple.

License

MIT License - See LICENSE file for details.

Author

Developed with Claude AI Sonnet 4, working under my guidance and instructions.

_{TOC is created by https://github.com/muquit/markdown-toc-go on Jun-22-2025}