build

Documentation

Overview

Package build gathers information about Go packages.

Go Path

TODO: Document GOPATH.

Build Constraints

A build constraint is a line comment beginning with the directive +build that lists the conditions under which a file should be included in the package. Constraints may appear in any kind of source file (not just Go), but they must be appear near the top of the file, preceded only by blank lines and other line comments.

A build constraint is evaluated as the OR of space-separated options; each option evaluates as the AND of its comma-separated terms; and each term is an alphanumeric word or, preceded by !, its negation. That is, the build constraint:

// +build linux,386 darwin,!cgo

corresponds to the boolean formula:

(linux AND 386) OR (darwin AND (NOT cgo))

During a particular build, the following words are satisfied:

• the target operating system, as spelled by runtime.GOOS
• the target architecture, as spelled by runtime.GOARCH
• "cgo", if ctxt.CgoEnabled is true
• any additional words listed in ctxt.BuildTags

If a file's name, after stripping the extension and a possible _test suffix, matches *_GOOS, *_GOARCH, or *_GOOS_GOARCH for any known operating system and architecture values, then the file is considered to have an implicit build constraint requiring those terms.

To keep a file from being considered for the build:

// +build ignore

(any other unsatisfied word will work as well, but “ignore” is conventional.)

To build a file only when using cgo, and only on Linux and OS X:

// +build linux,cgo darwin,cgo

Such a file is usually paired with another file implementing the default functionality for other systems, which in this case would carry the constraint:

// +build !linux !darwin !cgo

Naming a file dns_windows.go will cause it to be included only when building the package for Windows; similarly, math_386.s will be included only when building the package for 32-bit x86.

Index

• Variables
• func ArchChar(goarch string) (string, error)
• type Context
  • func (ctxt *Context) ScanDir(dir string) (info *DirInfo, err error)
• type DirInfo
  • func ScanDir(dir string) (info *DirInfo, err error)
  • func (d *DirInfo) IsCommand() bool
• type Tree
  • func FindTree(path string) (tree *Tree, pkg string, err error)
  • func (t *Tree) BinDir() string
  • func (t *Tree) HasPkg(pkg string) bool
  • func (t *Tree) HasSrc(pkg string) bool
  • func (t *Tree) PkgDir() string
  • func (t *Tree) SrcDir() string

Variables

var (
	ErrNotFound     = errors.New("package could not be found locally")
	ErrTreeNotFound = errors.New("no valid GOROOT or GOPATH could be found")
)

var Path []*Tree

Path is a validated list of Trees derived from $GOROOT and $GOPATH at init.

var ToolDir = filepath.Join(runtime.GOROOT(), "pkg/tool/"+runtime.GOOS+"_"+runtime.GOARCH)

ToolDir is the directory containing build tools.

Functions

func ArchChar

func ArchChar(goarch string) (string, error)

ArchChar returns the architecture character for the given goarch. For example, ArchChar("amd64") returns "6".

Types

type Context

type Context struct {
	GOARCH      string   // target architecture
	GOOS        string   // target operating system
	CgoEnabled  bool     // whether cgo can be used
	BuildTags   []string // additional tags to recognize in +build lines
	UseAllFiles bool     // use files regardless of +build lines, file names

	// ReadDir returns a slice of os.FileInfo, sorted by Name,
	// describing the content of the named directory.
	// The dir argument is the argument to ScanDir.
	// If ReadDir is nil, ScanDir uses io.ReadDir.
	ReadDir func(dir string) (fi []os.FileInfo, err error)

	// ReadFile returns the content of the file named file
	// in the directory named dir.  The dir argument is the
	// argument to ScanDir, and the file argument is the
	// Name field from an os.FileInfo returned by ReadDir.
	// The returned path is the full name of the file, to be
	// used in error messages.
	//
	// If ReadFile is nil, ScanDir uses filepath.Join(dir, file)
	// as the path and ioutil.ReadFile to read the data.
	ReadFile func(dir, file string) (path string, content []byte, err error)
}

A Context specifies the supporting context for a build.

var DefaultContext Context = defaultContext()

The DefaultContext is the default Context for builds. It uses the GOARCH and GOOS environment variables if set, or else the compiled code's GOARCH and GOOS.

func (*Context) ScanDir

func (ctxt *Context) ScanDir(dir string) (info *DirInfo, err error)

ScanDir returns a structure with details about the Go package found in the given directory.

Most .go, .c, .h, and .s files in the directory are considered part of the package. The exceptions are:

• .go files in package main (unless no other package is found)
• .go files in package documentation
• files starting with _ or .
• files with build constraints not satisfied by the context

type DirInfo

type DirInfo struct {
	Package        string                      // Name of package in dir
	PackageComment *ast.CommentGroup           // Package comments from GoFiles
	ImportPath     string                      // Import path of package in dir
	Imports        []string                    // All packages imported by GoFiles
	ImportPos      map[string][]token.Position // Source code location of imports

	// Source files
	GoFiles  []string // .go files in dir (excluding CgoFiles, TestGoFiles, XTestGoFiles)
	HFiles   []string // .h files in dir
	CFiles   []string // .c files in dir
	SFiles   []string // .s (and, when using cgo, .S files in dir)
	CgoFiles []string // .go files that import "C"

	// Cgo directives
	CgoPkgConfig []string // Cgo pkg-config directives
	CgoCFLAGS    []string // Cgo CFLAGS directives
	CgoLDFLAGS   []string // Cgo LDFLAGS directives

	// Test information
	TestGoFiles   []string // _test.go files in package
	XTestGoFiles  []string // _test.go files outside package
	TestImports   []string // All packages imported by (X)TestGoFiles
	TestImportPos map[string][]token.Position
}

func ScanDir

func ScanDir(dir string) (info *DirInfo, err error)

ScanDir calls DefaultContext.ScanDir.

func (*DirInfo) IsCommand

func (d *DirInfo) IsCommand() bool

type Tree

type Tree struct {
	Path   string
	Goroot bool
}

Tree describes a Go source tree, either $GOROOT or one from $GOPATH.

func FindTree

func FindTree(path string) (tree *Tree, pkg string, err error)

FindTree takes an import or filesystem path and returns the tree where the package source should be and the package import path.

func (*Tree) BinDir

func (t *Tree) BinDir() string

BinDir returns the tree's binary executable directory.

func (*Tree) HasPkg

func (t *Tree) HasPkg(pkg string) bool

HasPkg returns whether the given package's object file can be found inside this Tree.

func (*Tree) HasSrc

func (t *Tree) HasSrc(pkg string) bool

HasSrc returns whether the given package's source can be found inside this Tree.

func (*Tree) PkgDir

func (t *Tree) PkgDir() string

PkgDir returns the tree's package object directory.

func (*Tree) SrcDir

func (t *Tree) SrcDir() string

SrcDir returns the tree's package source directory.