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.

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 Fatalf(format string, args ...interface{})
• func Gc(pkg *Package, gofiles []string, deps ...Target) objpkgtarget
• func GcToolchain(opts ...func(*gcoption)) func(c *Context) error
• func Infof(format string, args ...interface{})
• func Ldflags(flags string) func(*Context) error
• func Warnf(format string, args ...interface{})
• 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) Run(cmd *exec.Cmd, deps ...Target) Target
  • func (c *Context) Workdir() string
• type ErrTarget
  • func (e ErrTarget) Objfile() string
  • func (e ErrTarget) Pkgfile() string
  • func (e ErrTarget) Result() error
• type ObjTarget
  • func Asm(pkg *Package, sfile string) ObjTarget
• 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 PkgTarget
  • func Compile(pkg *Package, deps ...Target) PkgTarget
  • func Install(pkg *Package, t PkgTarget) PkgTarget
  • func Pack(pkg *Package, deps ...ObjTarget) PkgTarget
• type Project
  • func NewProject(root string) *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 Statistics
  • func (s *Statistics) Record(name string, d time.Duration)
  • func (s *Statistics) String() string
  • func (s *Statistics) Total() time.Duration
• type Target
  • func BuildDependencies(targets map[string]PkgTarget, pkg *Package) []Target
  • func Ld(pkg *Package, afile PkgTarget) Target
• type Toolchain

Variables

var (
	// Quiet suppresses all logging output below ERROR
	Quiet = false

	// Verbose enables logging output below INFO
	Verbose = false
)

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 Fatalf

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

func Gc

func Gc(pkg *Package, gofiles []string, deps ...Target) objpkgtarget

Gc returns a Target representing the result of compiling a set of gofiles with the Context specified gc Compiler.

func GcToolchain

func GcToolchain(opts ...func(*gcoption)) func(c *Context) error

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 Warnf

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

Types

type Context

type Context struct {
	*Project
	*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) Run

func (c *Context) Run(cmd *exec.Cmd, deps ...Target) Target

Run returns a Target representing the result of executing a CmdTarget.

func (*Context) Workdir

func (c *Context) Workdir() string

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

type ErrTarget

type ErrTarget struct {
	Err error
}

func (ErrTarget) Objfile

func (e ErrTarget) Objfile() string

func (ErrTarget) Pkgfile

func (e ErrTarget) Pkgfile() string

func (ErrTarget) Result

func (e ErrTarget) Result() error

type ObjTarget

type ObjTarget interface {
	Target

	// Objfile is the name of the file that is produced if the target is successful.
	Objfile() string
}

ObjTarget represents a compiled Go object (.5, .6, etc)

func Asm

func Asm(pkg *Package, sfile string) ObjTarget

Asm returns a Target representing the result of assembling sfile with the Context specified asssembler.

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
}

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.

func (*Package) Binfile

func (pkg *Package) Binfile() string

Binfile returns the destination of the compiled target of this command. TODO(dfc) this should be Target.

func (*Package) Complete

func (p *Package) Complete() bool

Complete indicates if this is a pure Go package TODO(dfc) this should be pure go with respect to tags and scope

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 PkgTarget

type PkgTarget interface {
	Target

	// Pkgfile returns the name of the file that is produced by the Target if successful.
	Pkgfile() string
}

PkgTarget represents a Target that produces a pkg (.a) file.

func Compile

func Compile(pkg *Package, deps ...Target) PkgTarget

Compile returns a Target representing all the steps required to build a go package.

func Install

func Install(pkg *Package, t PkgTarget) PkgTarget

Install stores a copy of the compiled file in Project.Pkgdir

func Pack

func Pack(pkg *Package, deps ...ObjTarget) PkgTarget

Pack returns a Target representing the result of packing a set of Context specific object files into an archive.

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/.gogo/                 - used internally by gogo and identifies
                                  the root of the project.
$PROJECT/src/                   - base directory for the source of packages
$PROJECT/bin/                   - base directory for the compiled binaries

func NewProject

func NewProject(root string) *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 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 Target

type Target interface {
	// Result returns the result of the work as an error, or nil if the work
	// was performed successfully.
	// Implementers must observe these invariants
	// 1. There may be multiple concurrent callers to Result, or Result may
	//    be called many times in sequence, it must always return the same
	// 2. Result blocks until the work has been performed.
	Result() error
}

A Target is a placeholder for work which is completed asyncronusly.

func BuildDependencies

func BuildDependencies(targets map[string]PkgTarget, pkg *Package) []Target

BuildDependencies returns a []Target representing the results of compiling the dependencies of pkg.

func Ld

func Ld(pkg *Package, afile PkgTarget) Target

Ld returns a Target representing the result of linking a Package into a command with the Context provided linker.

type Toolchain

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