Using Binary-Only Packages In Go

When I provide consulting on Go to larger enterprises they’re often ask for a feature to distribute their Go packages as a binary-only packages without including the source code used for compiling the packages. I do understand that this feature is required for some enterprise organizations and also for commercial distribution of packages. Recently one organization told me that they are working on projects by leveraging various teams of different business units within the organization, where one team share the source to another team in binary form and don’t want to include the source code.

Go 1.7 adds an experimental feature to distribute packages in binary form without sharing the source code. To do this, you need to distribute the following files:

  1. Package binary for specific platforms.
  2. Include a source file not excluded by build constraints, and containing a “//go:binary-only-package” comment near the top of the file.

Note that binary only packages don’t work with “go get” command, thus you need to distribute the package as a zip file. The image below shows the directory structure of an example package that distributes as a binary-only package.

Directory structure of a binary-only package

Inside the directory binarypkg, we write source code for the package to compile into binary. Two sub-directories - pkg and src, are included for distributing the package in binary form. The pkg directory is used for providing the package binary and src directory is used for containing the source file with “//go:binary-only-package” comment. The command below from the directory binarypkg compiles the source and generates the output into pkg directory:

go build -o pkg/darwin_amd64/github.com/shijuvar/binarypkg.a -x

The package binary is generated to be used as the package name github.com/shijuvar/binarypkg when it distributes to package consumers. Thus, we write a source file into the src/github.com/shijuvar/binarypkg directory inside the directory binarypkg, to include the “//go:binary-only-package” comment. Here is the entire source of the file to containing the “//go:binary-only-package” comment.

//go:binary-only-package
package binarypkg

Just including the “//go:binary-only-package” comment in a single source file, you don’t need to distribute the source code. The command below zip the src and pkg directories to distribute the binary-only package to package consumers:

zip -r binarypkg.zip src/* pkg/*

Since binary-only packages don’t work with “go get” command, you need to distribute it as a zip file by including the pkg directory that contains package binary and src directory that contains a source file with the “//go:binary-only-package” comment. The package consumers should copies the src and pkg directories to their GOPATH by extracting the zip file you distribute as binary-only package as shown below:

unzip binarypkg.zip -d $GOPATH/

When you compile a program that includes a binary-only package, the go command will refuse to recompile the package source if it found the “//go:binary-only-package” comment and will use the suitable binary form of the package.

You can see an example for a binary-only package at https://github.com/shijuvar/go-recipes/tree/master/binarypkg

You can follow me on twitter at @shijucv. I do provide training and consulting on Go programming language (Golang) and distributed systems architectures, in India.