cttttt / multi-go-go

A template for repos containing multiple go programs

Multiple Go Binaries

Sometimes all you need is a repo full of Golang.

Specifically, a repository containing a bunch of Go source used to build a bunch of Go programs.

This can be handy for a "hack" repo containing one-off programs that share common packages, and is a great alternative to cobra.

Cobra is great for designing monolithic programs with related subcommands, but the pattern demostrated in this repo is more for building smaller, discrete binaries from a large pool of packages without creating a tonne of repositories.

It's a great home for ideas that are still in the oven 🤓.

Getting Started

To get started on a new program, make a new subdirectory of cmd/ and write a new main package.

Getting Really Started

To get rid of the trivial programs included in this repo and actually start from scratch, simple delete all subdirectories of cmd/ and pkg/, and recreate your go.mod:

$ rm -rf pkg/*
$ rm -rf cmd/*
$ rm go.mod go.sum
$ go mod init whatever_name_you_want

Build

The included Makefile is designed to discover and build binaries for all of the main packages within subdirectories of cmd.

To discover what needs to be built, and to test and build all programs, simply run make.

$ make
go test ./...
<<<<<<< HEAD
?       github.com/cttttt/multi-go-go/cmd/goodbye  [no test files]
ok      github.com/cttttt/multi-go-go/cmd/goodbye/pkg/goodbye      (cached)
?       github.com/cttttt/multi-go-go/cmd/hello    [no test files]
ok      github.com/cttttt/multi-go-go/pkg/hello    (cached)
=======
?       everything/cmd/goodbye  [no test files]
ok      everything/cmd/goodbye/pkg/goodbye      (cached)
?       everything/cmd/hello    [no test files]
ok      everything/pkg/hello    (cached)
>>>>>>> 239d150 (add a readme)
go build -C "cmd/goodbye"
ln -sf "../cmd/goodbye/goodbye" bin/
go build -C "cmd/hello"
ln -sf "../cmd/hello/hello" bin/

To build a specific program, run make bin/program_name.

For example, to run tests and only build bin/hello, run make bin/hello.

$ make bin/hello
go test ./...
<<<<<<< HEAD
?       github.com/cttttt/multi-go-go/cmd/goodbye  [no test files]
ok      github.com/cttttt/multi-go-go/cmd/goodbye/pkg/goodbye      (cached)
?       github.com/cttttt/multi-go-go/cmd/hello    [no test files]
ok      github.com/cttttt/multi-go-go/pkg/hello    (cached)
=======
?       everything/cmd/goodbye  [no test files]
ok      everything/cmd/goodbye/pkg/goodbye      (cached)
?       everything/cmd/hello    [no test files]
ok      everything/pkg/hello    (cached)
>>>>>>> 239d150 (add a readme)
go build -C "cmd/hello"
ln -sf "../cmd/hello/hello" bin/

Install

To "install" all binaries, simply add the bin/ directory to the PATH. For example, if your shell is bash:

$ echo "export PATH=$PWD/bin:\$PATH" >> ~/.bashrc
$ source ~/.bashrc

Sharing

To have someone else install a binary without having to clone your repo, push a tag, and have them install it using go install. For example, if you want to install the hello program from this repository, run:

$ go install github.com/cttttt/multi-go-go/cmd/[email protected]
go: downloading github.com/cttttt/multi-go-go v0.0.1
$

Note that versions are actually globally cached (centrally, by the Go maintainers), so tags may not be reused.

Internal package dependencies

Although the convension here is to have each binary depend on common packages within pkg/, if a package will never be used across binaries, simply place it within a pkg/ subdirectory of its cmd/... directory.

Although this subdirectory could have any name, pkg/ is preferred as it's unlikely to share a name with a command's built binary. For example, the package cmd/goodbye/goodbye would not be suitable, as a file with the same name will be generated by the Makefile.

See cmd/goodbye for an example of a command that depends on an unshared package (cmd/goodbye/pkg/goodbye).

See cmd/hello for an example of a command that depends on a shared package (pkg/hello).

Testing

Since tests are run using the go toolchain's test runner, follow the Go convensions and place your _test packages within _test.go files within each package dir with fixtures placed into adjacent testdata/ directories.

Although not required, a fantastic suite of testing related packages is testify.

License

Creative Commons Attribution-ShareAlike 4.0 International License.

You should have received a copy of the license along with this work. If not, see http://creativecommons.org/licenses/by-sa/4.0/.