gb
is a proof of concept replacement build tool for the Go programming language.
I gave a talk about gb
and the rational for its creation at GDG Berlin in April 2015, video and slides.
gb
operates on the concept of a project. A project has the following properties:
- A project is the consumer of your own source code, and possibly dependencies that your code consumes; nothing consumes the code from a project. Another way of thinking about it is, a project is where package
main
is. - A project is conceptually a
$GOPATH
workspace dedicated to your project's code. - A project supports multiple locations for source code, at the moment
src/
for your source code, andvendor/src/
for third party code that you have copied, cloned, forked, or otherwise included in the project. - The code that represents an
import
path is controlled by the project, by virtue of being present in one of the source code directories in the project.
go get github.com/constabulary/gb/...
See the getting started document.
gb
is the main command. It supports subcommands, of which there are currently two:
build
- which takes one or more import paths, iegb build github.com/constabulary/gb/cmd/gb
, if executed inside$PROJECT/src/some/path/
,gb build
will build that path.test
- behaves identically togb build
, but runs tests.
Arguments to gb
subcommands are package import paths or globs relative to the project src/
directory
gb build github.com/a/b
- buildsgithub.com/a/b
gb build github.com/a/b/...
- buildsgithub.com/a/b
and all packages below itgb build .../cmd/...
- builds anything that matches.*/cmd/.*
gb build
- builds the package in the current directory.
Other subcommands, like test
, vendor
, etc follow the same rule.
note: only import paths within the src/
directory will match, it is not possible to build source from the vendor/src/
directory; it will be built if needed by virtue of being imported by a package in the src/
directory.
By default gb
always performs incremental compilation and caches the results in $PROJECT/pkg/
. See the Flags section for options to alter this behaviour.
The following flags are supported by gb
. Note that these are flags to subcommands, so must come after the subcommand.
-v
- increases verbosity, effectively lowering the output level from INFO to DEBUG.-q
- decreases verbosity, effectively raising the output level to ERROR. In a successful build, no output will be displayed.-goroot
- alters the path to the go toolchain in use, eggb build -goroot=$HOME/go1.4
.-goos
,-goarch
- analogous toenv GOOS=... GOARCH=... gb
.-f
- ignore cached packages if present, new packages built will overwrite any cached packages. This effectively disables incremental compilation.-F
- do not cache packages, cached packages will still be used for incremental compilation,-f -F
is advised to disable the package caching system.
gb
supports git style plugins, anything in the path that starts with gb-
is considered a plugin. Plugins are executed from the main gb
tool. At the moment there are two plugins shipped with gb
.
env
- analogous togo env
, useful for debugging the environment passed togb
plugins, tranditionally all environment variables in this set begin withGB_
.vendor
- is a simple wrapper aroundgo get
to allow easy bootstrapping of a project by fetching dependencies in to thevendor/src/
directory.