Mar 09th

On-demand Go binaries

Go Binaries is an open-source server which compiles Go binaries on-demand, allowing non-Go users to quickly install tools written in Go, without installing the Go compiler or a package manager — all you need is curl. Let’s take a look at how to use it, and how it works!

Installing programs

Suppose you want to install the fantastic hey HTTP benchmarking tool, you could install the latest release with the following command. In a few seconds you’ll have the hey command available on your machine, installed to /usr/local/bin by default.

$ curl -sf https://gobinaries.com/rakyll/hey | sh

  ==> Downloading github.com/rakyll/hey@master
  ==> Resolved version master to v0.1.3
  ==> Downloading binary for darwin amd64
  ==> Installing hey to /usr/local/bin
  ==> Installation complete

$ hey https://apex.sh

Response time histogram:
  0.008 [1]   |■
  0.018 [76]  |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  0.027 [73]  |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
  0.036 [0]   |

...

In scenarios such as continuous integration you may want to lock down a particular version to prevent any surprises using semver. Go Binaries currently supports the following syntax for matching versions:

  • Exact version: v1.2.3, 1.2.3
  • Wildcards: v1.x, v1.2.x, 1.x, 1.2.x
  • Wildcards (implicit): v1, v1.2, 1.2
  • Leading v is optional, regardless of the Git tag

Here are a few examples:

$ curl -sf https://gobinaries.com/rakyll/hey@v0.1.2 | sh
$ curl -sf https://gobinaries.com/rakyll/hey@v0.1.x | sh
$ curl -sf https://gobinaries.com/rakyll/hey@v0.1 | sh
$ curl -sf https://gobinaries.com/rakyll/hey@v0.x | sh

The path provided to gobinaries.com should be the full path to your main package, for example, my staticgen project has the main in cmd/staticgen/main.go, so it is installed as the following:

$ curl -sf https://gobinaries.com/tj/staticgen/cmd/staticgen | sh

Specifying the output directory

By default, binaries are installed to /usr/local/bin, however, you can change the target directory using the PREFIX environment variable.

Here we install to the current working directory, which can be useful for continuous integration such as GitHub Actions:

$ curl -sf https://gobinaries.com/rakyll/hey | PREFIX=. sh
$ ./hey https://apex.sh
...

If the directory doesn’t exist it will be created.

How the server works

The request for a package resolves the requested version to a Git tag, and responds with a shell script which should be piped to sh. This is necessary because the server needs to determine your operating system and architecture to cross-compile the Go binary appropriately.

$ curl -sf https://gobinaries.com/rakyll/hey | sh

The shell script performs a second request to gobinaries.com to fetch and install the actual binary, with the OS, architecture, and a concrete version number. If the package was not previously built, it will be cross-compiled be stored in Google Cloud Storage for up to 30 days, and cached in a CDN. This secondary request looks like this:

https://gobinaries.com/binary/github.com/rakyll/hey?os=darwin&arch=amd64&version=v0.1.3

Open source

As I mentioned this is a hosted service, however, the source is also available over at tj/gobinaries, so feel free to take a look and contribute if you’d like.


Thanks to CTO.ai and my GitHub Sponsors for sponsoring the time to create this project!

Subscribe