gb

README

gb

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

Road map

In rough order

• Cross Compilation
• gb test improvements, test output, flag handling
• gb vendor updates and bug fixes
• new package resolver (replace go/build)

Big ticket items

Big ticket items that are not on the road map yet

• Race detector support
• Tag handling, unify -tags, ENVVARS and GOOS/GOARCH into a single format for binary names and pkg cache
• Package BuildID support (make stale detection work like the Go 1.5)
• gccgo toolchain support.

We welcome pull requests, bug fixes and issue reports.

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

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

• Variables
• func Build(pkgs ...*Package) error
• func Debugf(format string, args ...interface{})
• func Errorf(format string, args ...interface{})
• func Execute(a *Action) error
• func ExecuteConcurrent(a *Action, n int) error
• func Fatalf(format string, args ...interface{})
• 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 Infof(format string, args ...interface{})
• func Ldflags(flags string) func(*Context) error
• func SourceDir(root string) func(*Project)
• func Warnf(format string, args ...interface{})
• 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 (c *Context) AllPackages(pattern string) []string
  • func (c *Context) Destroy() error
  • func (c *Context) IncludePaths() []string
  • func (c *Context) Pkgdir() string
  • func (c *Context) ResolvePackage(path string) (*Package, error)
  • func (c *Context) ResolvePackageWithTests(path string) (*Package, error)
  • func (c *Context) Workdir() string
• type Package
  • func NewPackage(ctx *Context, p *build.Package) *Package
  • func (pkg *Package) Binfile() string
  • func (p *Package) Complete() bool
  • func (p *Package) Imports() []*Package
  • func (pkg *Package) Objdir() string
  • func (p *Package) String() string
• type Project
  • func NewProject(root string, options ...func(*Project)) *Project
  • func (p *Project) Bindir() string
  • func (p *Project) NewContext(opts ...func(*Context) error) (*Context, error)
  • func (p *Project) Pkgdir() string
  • func (p *Project) Projectdir() string
  • func (p *Project) Srcdirs() []string
• type Srcdir
• type Statistics
  • func (s *Statistics) Record(name string, d time.Duration)
  • func (s *Statistics) String() string
  • func (s *Statistics) Total() time.Duration
• type Task
• type TaskFn
  • func (fn TaskFn) Run() error
• type Toolchain

Examples

• NewPackage

Variables

var (
	// Quiet suppresses all logging output below ERROR
	Quiet bool

	// Verbose enables logging output below INFO
	Verbose bool
)

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 Debugf

func Debugf(format string, args ...interface{})

func Errorf

func Errorf(format string, args ...interface{})

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) error

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

func Fatalf

func Fatalf(format string, args ...interface{})

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 sets options passed to the compiler.

func Infof

func Infof(format string, args ...interface{})

func Ldflags

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

Ldflags sets options passed to the linker.

func SourceDir

func SourceDir(root string) func(*Project)

func Warnf

func Warnf(format string, args ...interface{})

Types

type Action

type Action struct {

	// Name describes the action.
	Name string

	// Deps identifies the Actions that this Action depends.
	Deps []*Action

	// Task identifies the that this action represents.
	Task
}

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)

BuildAction produces a tree of *Actions that can be executed to build a *Package. BuildAction 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
	Context *build.Context

	Statistics

	Force       bool // force rebuild of packages
	SkipInstall bool // do not cache compiled packages
	// contains filtered or unexported fields
}

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

func (*Context) AllPackages

func (c *Context) AllPackages(pattern string) []string

AllPackages returns all the packages that can be found under the $PROJECT/src directory. The pattern is a path including "...".

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) 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) ResolvePackageWithTests

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

ResolvePackageWithTests resolves the package at path using the current context it also resolves the internal and external test dependenices, although these are not returned, only cached in the Context.

func (*Context) Workdir

func (c *Context) Workdir() string

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

type Package

type Package struct {
	*Context
	*build.Package
	Scope         string // scope: build, test, etc
	ExtraIncludes string // hook for test
	Stale         bool   // is the package out of date wrt. its cached copy
	Standard      bool   // is this package part of the standard library
}

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

func NewPackage

func NewPackage(ctx *Context, p *build.Package) *Package

NewPackage creates a resolved Package.

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,
		gb.SourceDir(filepath.Join(root, "src")),           // $PROJECT/src
		gb.SourceDir(filepath.Join(root, "vendor", "src")), // $PROJECT/vendor/src
	)

	// Create a new Context from the Project. A Context holds
	// the state of a specific compilation or test within the Project.
	ctx, err := proj.NewContext()
	if err != nil {
		log.Fatal("Could not create new context:", err)
	}

	// Always remember to clean up your Context
	ctx.Destroy()
}

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) Imports

func (p *Package) Imports() []*Package

Imports returns the Pacakges that this Package depends on.

func (*Package) Objdir

func (pkg *Package) Objdir() string

Objdir returns the destination for object files compiled for this Package.

func (*Package) String

func (p *Package) String() string

type Project

type Project struct {
	// contains filtered or unexported fields
}

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, options ...func(*Project)) *Project

func (*Project) Bindir

func (p *Project) Bindir() string

Bindir returns the path for compiled programs.

func (*Project) NewContext

func (p *Project) NewContext(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 (*Project) Pkgdir

func (p *Project) Pkgdir() string

Pkgdir returns the path to precompiled packages.

func (*Project) Projectdir

func (p *Project) Projectdir() string

Projectdir returns the path root of this project.

func (*Project) Srcdirs

func (p *Project) Srcdirs() []string

Srcdirs returns the path to the source directories. The first source directory will always be filepath.Join(Projectdir(), "src") but there may be additional directories.

type Srcdir

type Srcdir struct {
	// Root is the root directory of this Srcdir.
	Root string

	// Prefix is an optional import path prefix applied
	// to any package resolved via this Srcdir.
	Prefix string
}

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 Task

type Task interface {

	// Run will initiate the work that this task represents and
	// block until the work is complete.
	Run() error
}

Task represents some work to be performed. It contains a single method Run, which is expected to be executed at most once.

type TaskFn

type TaskFn func() error

TaskFn is a Task that can execute itself.

func (TaskFn) Run

func (fn TaskFn) Run() error

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.