gb

README

gb

Build status

Unix:

Windows:

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.

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

• func Build(pkgs ...*Package) error
• func Execute(a *Action) error
• func ExecuteConcurrent(a *Action, n int, interrupt <-chan struct{}) error
• func GOARCH(goarch string) func(*Context) error
• func GOOS(goos string) func(*Context) error
• func GcToolchain() func(c *Context) error
• func Gcflags(flags ...string) func(*Context) error
• func Ldflags(flags ...string) func(*Context) error
• func Tags(tags ...string) func(*Context) error
• func WithRace(c *Context) error
• func Workdir(pkg *Package) string
• type Action
  • func BuildDependencies(targets map[string]*Action, pkg *Package) ([]*Action, error)
  • func BuildPackage(targets map[string]*Action, pkg *Package) (*Action, error)
  • func BuildPackages(pkgs ...*Package) (*Action, error)
  • func Compile(pkg *Package, deps ...*Action) (*Action, error)
• type Context
  • func NewContext(p Project, opts ...func(*Context) error) (*Context, error)
  • func (c *Context) AddImporter(i Importer)
  • func (c *Context) Destroy() error
  • func (c *Context) IncludePaths() []string
  • func (c *Context) NewPackage(p *importer.Package) (*Package, error)
  • func (c *Context) Pkgdir() string
  • func (c *Context) ResolvePackage(path string) (*Package, error)
  • func (c *Context) Suffix() string
  • func (c *Context) Workdir() string
• type Importer
• type Package
  • func (pkg *Package) Binfile() string
  • func (p *Package) Complete() bool
  • func (p *Package) String() string
• type Project
  • func NewProject(root string) Project
• type Statistics
  • func (s *Statistics) Record(name string, d time.Duration)
  • func (s *Statistics) String() string
  • func (s *Statistics) Total() time.Duration
• type Toolchain

Examples

• NewProject

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.

func Workdir

func Workdir(pkg *Package) string

Workdir returns the working directory for a package.

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
	*importer.Context // TODO(dfc) this is a hack

	Statistics

	Force   bool // force rebuild of packages
	Install bool // copy packages into $PROJECT/pkg
	Verbose bool // verbose output
	Nope    bool // command specfic 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) AddImporter

func (c *Context) AddImporter(i Importer)

AddImporter adds an additional Importer to the Context.

func (*Context) Destroy

func (c *Context) Destroy() error

Destroy removes the temporary working files of this context.

func (*Context) IncludePaths

func (c *Context) IncludePaths() []string

IncludePaths returns the include paths visible in this context.

func (*Context) NewPackage

func (c *Context) NewPackage(p *importer.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) (*importer.Package, error)
}

Importer resolves package import paths to *importer.Packages.

type Package

type Package struct {
	*Context
	*importer.Package
	TestScope     bool
	ExtraIncludes string // hook for test
	Stale         bool   // is the package out of date wrt. its cached copy
	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

type Project

type Project interface {

	// Projectdir returns the path root of this project.
	Projectdir() string

	// Pkgdir returns the path to precompiled packages.
	Pkgdir() string

	// Bindir returns the path for compiled programs.
	Bindir() string

	// Srcdirs returns the path to the source directories.
	Srcdirs() []string
}

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

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, searchpaths []string, importpath, srcdir, outfile string, files []string) error
	Asm(pkg *Package, srcdir, ofile, sfile string) error
	Pack(pkg *Package, afiles ...string) error
	Ld(*Package, []string, string, string) 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.