README

gb

Build status

Unix: travis-cs status

Windows: Build status

codecov.io

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.

Project based

gb operates on the concept of a project. A gb project is a workspace for all the Go code that is required to build your project.

A gb project is a folder on disk that contains a subdirectory named src/. That's it, no environment variables to set. For the rest of this document we'll refer to your gb project as $PROJECT.

You can create as many projects as you like and move between them simply by changing directories.

Installation

go get github.com/constabulary/gb/...

Read more

gb has its own site, getgb.io, head over there for more information.

Contributing

Contribution guidelines

We welcome pull requests, bug fixes and issue reports.

Before proposing a large change, please discuss your change by raising an issue.

Road map
Completed
  • Cross Compilation
  • Tag handling, unify -tags, ENVVARS and GOOS/GOARCH into a single format for binary names and pkg cache
  • gb test improvements, test output, test flag handling
  • Race detector support
Todo
  • 0.4 series: gb vendor updates and bug fixes
  • 0.5 series: new package resolver (replace go/build)
Big ticket items

Big ticket items that are not on the road map yet

  • Package BuildID support (make stale detection work like the Go 1.5)
  • gccgo toolchain support.
Expand ▾ Collapse ▴

Documentation

Overview

    Package gb is a tool kit for building Go packages and programs.

    The executable, cmd/gb, is located in the respective subdirectory along with several plugin programs.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Build

    func Build(pkgs ...*Package) error

      Build builds each of pkgs in succession. If pkg is a command, then the results of build include linking the final binary into pkg.Context.Bindir().

      func Execute

      func Execute(a *Action) error

        Execute executes a tree of *Actions sequentually in depth first order.

        func ExecuteConcurrent

        func ExecuteConcurrent(a *Action, n int, interrupt <-chan struct{}) error

          ExecuteConcurrent executes all actions in a tree concurrently. Each Action will wait until its dependant actions are complete.

          func GOARCH

          func GOARCH(goarch string) func(*Context) error

            GOARCH configures the Context to use goarch as the target arch.

            func GOOS

            func GOOS(goos string) func(*Context) error

              GOOS configures the Context to use goos as the target os.

              func GcToolchain

              func GcToolchain() func(c *Context) error

              func Gcflags

              func Gcflags(flags ...string) func(*Context) error

                Gcflags appends flags to the list passed to the compiler.

                func Ldflags

                func Ldflags(flags ...string) func(*Context) error

                  Ldflags appends flags to the list passed to the linker.

                  func Tags

                  func Tags(tags ...string) func(*Context) error

                    Tags configured the context to use these additional build tags

                    func WithRace

                    func WithRace(c *Context) error

                      WithRace enables the race detector and adds the tag "race" to the Context build tags.

                      Types

                      type Action

                      type Action struct {
                      
                      	// Name describes the action.
                      	Name string
                      
                      	// Deps identifies the Actions that this Action depends.
                      	Deps []*Action
                      
                      	// Run identifies the task that this action represents.
                      	Run func() error
                      }

                        An Action describes a task to be performed and a set of Actions that the task depends on.

                        func BuildDependencies

                        func BuildDependencies(targets map[string]*Action, pkg *Package) ([]*Action, error)

                          BuildDependencies returns a slice of Actions representing the steps required to build all dependant packages of this package.

                          func BuildPackage

                          func BuildPackage(targets map[string]*Action, pkg *Package) (*Action, error)

                            BuildPackage returns an Action representing the steps required to build this package.

                            func BuildPackages

                            func BuildPackages(pkgs ...*Package) (*Action, error)

                              BuildPackages produces a tree of *Actions that can be executed to build a *Package. BuildPackages walks the tree of *Packages and returns a corresponding tree of *Actions representing the steps required to build *Package and any of its dependencies

                              func Compile

                              func Compile(pkg *Package, deps ...*Action) (*Action, error)

                                Compile returns an Action representing the steps required to compile this package.

                                type Context

                                type Context struct {
                                	Project
                                
                                	Statistics
                                
                                	Force   bool // force rebuild of packages
                                	Install bool // copy packages into $PROJECT/pkg
                                	Verbose bool // verbose output
                                	Nope    bool // command specific flag, under test it skips the execute action.
                                	// contains filtered or unexported fields
                                }

                                  Context represents an execution of one or more Targets inside a Project.

                                  func NewContext

                                  func NewContext(p Project, opts ...func(*Context) error) (*Context, error)

                                    NewContext returns a new build context from this project. By default this context will use the gc toolchain with the host's GOOS and GOARCH values.

                                    func (*Context) Destroy

                                    func (c *Context) Destroy() error

                                      Destroy removes the temporary working files of this context.

                                      func (*Context) NewPackage

                                      func (c *Context) NewPackage(p *build.Package) (*Package, error)

                                        NewPackage creates a resolved Package for p.

                                        func (*Context) Pkgdir

                                        func (c *Context) Pkgdir() string

                                          Pkgdir returns the path to precompiled packages.

                                          func (*Context) ResolvePackage

                                          func (c *Context) ResolvePackage(path string) (*Package, error)

                                            ResolvePackage resolves the package at path using the current context.

                                            func (*Context) Suffix

                                            func (c *Context) Suffix() string

                                              Suffix returns the suffix (if any) for binaries produced by this context.

                                              func (*Context) Workdir

                                              func (c *Context) Workdir() string

                                                Workdir returns the path to this Context's working directory.

                                                type Importer

                                                type Importer interface {
                                                
                                                	// Import attempts to resolve the package import path, path,
                                                	// to an *importer.Package.
                                                	Import(path string) (*build.Package, error)
                                                }

                                                  Importer resolves package import paths to *importer.Packages.

                                                  type Package

                                                  type Package struct {
                                                  	*Context
                                                  	*build.Package
                                                  	TestScope bool
                                                  	NotStale  bool // this package _and_ all its dependencies are not stale
                                                  	Main      bool // is this a command
                                                  	Imports   []*Package
                                                  }

                                                    Package represents a resolved package from the Project with respect to the Context.

                                                    func (*Package) Binfile

                                                    func (pkg *Package) Binfile() string

                                                      Binfile returns the destination of the compiled target of this command.

                                                      func (*Package) Complete

                                                      func (p *Package) Complete() bool

                                                        Complete indicates if this is a pure Go package

                                                        func (*Package) String

                                                        func (p *Package) String() string

                                                        func (*Package) Workdir

                                                        func (pkg *Package) Workdir() string

                                                        type Project

                                                        type Project interface {
                                                        
                                                        	// Projectdir returns the path root of this project.
                                                        	Projectdir() string
                                                        
                                                        	// Pkgdir returns the path to precompiled packages.
                                                        	Pkgdir() string
                                                        	// contains filtered or unexported methods
                                                        }

                                                          Project represents a gb project. A gb project has a simlar layout to a $GOPATH workspace. Each gb project has a standard directory layout starting at the project root, which we'll refer too as $PROJECT.

                                                          $PROJECT/                       - the project root
                                                          $PROJECT/src/                   - base directory for the source of packages
                                                          $PROJECT/bin/                   - base directory for the compiled binaries
                                                          

                                                          func NewProject

                                                          func NewProject(root string) Project
                                                          Example

                                                          Code:

                                                          package main
                                                          
                                                          import (
                                                          	"log"
                                                          	"path/filepath"
                                                          
                                                          	"github.com/constabulary/gb"
                                                          )
                                                          
                                                          func main() {
                                                          
                                                          	// Every project begins with a project root.
                                                          	// Normally you'd check this out of source control.
                                                          	root := filepath.Join("home", "dfc", "devel", "demo")
                                                          
                                                          	// Create a new Project passing in the source directories
                                                          	// under this project's root.
                                                          	proj := gb.NewProject(root)
                                                          
                                                          	// Create a new Context from the Project. A Context holds
                                                          	// the state of a specific compilation or test within the Project.
                                                          	ctx, err := gb.NewContext(proj)
                                                          	if err != nil {
                                                          		log.Fatal("Could not create new context:", err)
                                                          	}
                                                          
                                                          	// Always remember to clean up your Context
                                                          	ctx.Destroy()
                                                          }
                                                          

                                                          type Statistics

                                                          type Statistics struct {
                                                          	sync.Mutex
                                                          	// contains filtered or unexported fields
                                                          }

                                                            Statistics records the various Durations

                                                            func (*Statistics) Record

                                                            func (s *Statistics) Record(name string, d time.Duration)

                                                            func (*Statistics) String

                                                            func (s *Statistics) String() string

                                                            func (*Statistics) Total

                                                            func (s *Statistics) Total() time.Duration

                                                            type Toolchain

                                                            type Toolchain interface {
                                                            	Gc(pkg *Package, files []string) error
                                                            	Asm(pkg *Package, ofile, sfile string) error
                                                            	Pack(pkg *Package, afiles ...string) error
                                                            	Ld(*Package) error
                                                            	Cc(pkg *Package, ofile string, cfile string) error
                                                            	// contains filtered or unexported methods
                                                            }

                                                              Toolchain represents a standardised set of command line tools used to build and test Go programs.

                                                              Directories

                                                              Path Synopsis
                                                              cmd
                                                              Package command holds support functions and types for writing gb and gb plugins
                                                              Package command holds support functions and types for writing gb and gb plugins
                                                              gb
                                                              gb, a project based build tool for the Go programming language.
                                                              gb, a project based build tool for the Go programming language.
                                                              gb-vendor
                                                              gb-vendor, a gb plugin to manage your vendored dependencies.
                                                              gb-vendor, a gb plugin to manage your vendored dependencies.
                                                              internal
                                                              debug
                                                              debug provides a light weight debug facility.
                                                              debug provides a light weight debug facility.
                                                              depfile
                                                              Package depfile loads a file of tagged key value pairs.
                                                              Package depfile loads a file of tagged key value pairs.
                                                              fileutils
                                                              Package fileutils provides utililty methods to copy and move files and directories.
                                                              Package fileutils provides utililty methods to copy and move files and directories.