Documentation
¶
Overview ¶
Package buildutil provides utilities related to the go/build package in the standard library.
All I/O is done via the build.Context file system interface, which must be concurrency-safe.
Index ¶
- Constants
- func AllPackages(ctxt *build.Context) []string
- func ContainingPackage(ctxt *build.Context, dir, filename string) (*build.Package, error)
- func ExpandPatterns(ctxt *build.Context, patterns []string) map[string]bool
- func FakeContext(pkgs map[string]map[string]string) *build.Context
- func FileExists(ctxt *build.Context, path string) bool
- func ForEachPackage(ctxt *build.Context, found func(importPath string, err error))
- func HasSubdir(ctxt *build.Context, root, dir string) (rel string, ok bool)
- func IsAbsPath(ctxt *build.Context, path string) bool
- func IsDir(ctxt *build.Context, path string) bool
- func JoinPath(ctxt *build.Context, path ...string) string
- func OpenFile(ctxt *build.Context, path string) (io.ReadCloser, error)
- func OverlayContext(orig *build.Context, overlay map[string][]byte) *build.Context
- func ParseFile(fset *token.FileSet, ctxt *build.Context, displayPath func(string) string, ...) (*ast.File, error)
- func ParseOverlayArchive(archive io.Reader) (map[string][]byte, error)
- func ReadDir(ctxt *build.Context, path string) ([]os.FileInfo, error)
- func SplitPathList(ctxt *build.Context, s string) []string
- type TagsFlag
Constants ¶
const TagsFlagDoc = "a list of `build tags` to consider satisfied during the build. " +
"For more information about build tags, see the description of " +
"build constraints in the documentation for the go/build package"
Variables ¶
This section is empty.
Functions ¶
func AllPackages ¶
AllPackages returns the package path of each Go package in any source directory of the specified build context (e.g. $GOROOT or an element of $GOPATH). Errors are ignored. The results are sorted. All package paths are canonical, and thus may contain "/vendor/".
The result may include import paths for directories that contain no *.go files, such as "archive" (in $GOROOT/src).
All I/O is done via the build.Context file system interface, which must be concurrency-safe.
func ContainingPackage ¶
ContainingPackage returns the package containing filename.
If filename is not absolute, it is interpreted relative to working directory dir. All I/O is via the build context's file system interface, if any.
The '...Files []string' fields of the resulting build.Package are not populated (build.FindOnly mode).
func ExpandPatterns ¶
ExpandPatterns returns the set of packages matched by patterns, which may have the following forms:
golang.org/x/tools/cmd/guru # a single package golang.org/x/tools/... # all packages beneath dir ... # the entire workspace.
Order is significant: a pattern preceded by '-' removes matching packages from the set. For example, these patterns match all encoding packages except encoding/xml:
encoding/... -encoding/xml
A trailing slash in a pattern is ignored. (Path components of Go package names are separated by slash, not the platform's path separator.)
func FakeContext ¶
FakeContext returns a build.Context for the fake file tree specified by pkgs, which maps package import paths to a mapping from file base names to contents.
The fake Context has a GOROOT of "/go" and no GOPATH, and overrides the necessary file access methods to read from memory instead of the real file system.
Unlike a real file tree, the fake one has only two levels---packages and files---so ReadDir("/go/src/") returns all packages under /go/src/ including, for instance, "math" and "math/big". ReadDir("/go/src/math/big") would return all the files in the "math/big" package.
func FileExists ¶
FileExists returns true if the specified file exists, using the build context's file system interface.
func ForEachPackage ¶
ForEachPackage calls the found function with the package path of each Go package it finds in any source directory of the specified build context (e.g. $GOROOT or an element of $GOPATH). All package paths are canonical, and thus may contain "/vendor/".
If the package directory exists but could not be read, the second argument to the found function provides the error.
All I/O is done via the build.Context file system interface, which must be concurrency-safe.
func HasSubdir ¶
hasSubdir calls ctxt.HasSubdir (if not nil) or else uses the local file system to answer the question.
func IsAbsPath ¶
IsAbsPath behaves like filepath.IsAbs, but uses the build context's file system interface, if any.
func IsDir ¶
IsDir behaves like os.Stat plus IsDir, but uses the build context's file system interface, if any.
func JoinPath ¶
JoinPath behaves like filepath.Join, but uses the build context's file system interface, if any.
func OpenFile ¶
OpenFile behaves like os.Open, but uses the build context's file system interface, if any.
func OverlayContext ¶
OverlayContext overlays a build.Context with additional files from a map. Files in the map take precedence over other files.
In addition to plain string comparison, two file names are considered equal if their base names match and their directory components point at the same directory on the file system. That is, symbolic links are followed for directories, but not files.
A common use case for OverlayContext is to allow editors to pass in a set of unsaved, modified files.
Currently, only the Context.OpenFile function will respect the overlay. This may change in the future.
func ParseFile ¶
func ParseFile(fset *token.FileSet, ctxt *build.Context, displayPath func(string) string, dir string, file string, mode parser.Mode) (*ast.File, error)
ParseFile behaves like parser.ParseFile, but uses the build context's file system interface, if any.
If file is not absolute (as defined by IsAbsPath), the (dir, file) components are joined using JoinPath; dir must be absolute.
The displayPath function, if provided, is used to transform the filename that will be attached to the ASTs.
TODO(adonovan): call this from go/loader.parseFiles when the tree thaws.
func ParseOverlayArchive ¶
ParseOverlayArchive parses an archive containing Go files and their contents. The result is intended to be used with OverlayContext.
Archive format ¶
The archive consists of a series of files. Each file consists of a name, a decimal file size and the file contents, separated by newlines. No newline follows after the file contents.
Types ¶
type TagsFlag ¶
type TagsFlag []string
TagsFlag is an implementation of the flag.Value and flag.Getter interfaces that parses a flag value in the same manner as go build's -tags flag and populates a []string slice.
See $GOROOT/src/go/build/doc.go for description of build tags. See $GOROOT/src/cmd/go/doc.go for description of 'go build -tags' flag.
Example:
flag.Var((*buildutil.TagsFlag)(&build.Default.BuildTags), "tags", buildutil.TagsFlagDoc)
Source Files