bazel

Documentation

Overview

Package bazel implements the internal plumbing of a configurable Bazel compilation unit extractor.

Index

• func AddDetail(unit *apb.CompilationUnit, msg proto.Message) error
• func CheckFileSize(path string, maxSize datasize.Size) bool
• func FindSourceArgs(r *regexp.Regexp) func(*apb.CompilationUnit) error
• func LoadAction(path string) (*xapb.ExtraActionInfo, error)
• func NewKZIP(path string) (*kzip.Writer, error)
• func PackageName(label string) string
• func PathInPackage(path, pkg string) bool
• func SetTarget(target, rule string, unit *apb.CompilationUnit) error
• func Write(w io.WriterTo, path string) error
• type ActionInfo
  • func SpawnAction(info *xapb.ExtraActionInfo) (*ActionInfo, error)
  • func (a *ActionInfo) Setenv(key, value string)
• type Config
  • func NewFromSettings(s Settings) (*Config, *xapb.ExtraActionInfo, error)
  • func (c *Config) ExtractToFile(ctx context.Context, info *ActionInfo, w *kzip.Writer) (string, error)
  • func (c *Config) ExtractToKzip(ctx context.Context, ai *ActionInfo, outputPath string) error
• type Settings
  • func (s *Settings) SetFlags(f *flag.FlagSet, prefix string) func()

Functions

func AddDetail

func AddDetail(unit *apb.CompilationUnit, msg proto.Message) error

AddDetail adds the specified message to the details field of unit.

func CheckFileSize

func CheckFileSize(path string, maxSize datasize.Size) bool

CheckFileSize returns true if maxSize == 0 or the size of the file at path exists and is less than or equal to maxSize.

func FindSourceArgs

func FindSourceArgs(r *regexp.Regexp) func(*apb.CompilationUnit) error

FindSourceArgs returns a fixup that scans the argument list of a compilation unit for strings matching r. Any that are found, and which also match the names of required input files, are added to the source files of the unit. If the pattern has a single capturing group, the contents of that group will be used rather than the entire matchin.

func LoadAction

func LoadAction(path string) (*xapb.ExtraActionInfo, error)

LoadAction loads and parses a wire-format ExtraActionInfo message from the specified path, or aborts the program with an error.

func NewKZIP

func NewKZIP(path string) (*kzip.Writer, error)

NewKZIP creates a kzip writer at path, replacing any existing file at that location. Closing the returned writer also closes the underlying file.

func PackageName

func PackageName(label string) string

PackageName extracts the base name of a Bazel package from a target label, for example //foo/bar:baz ⇒ foo/bar.

func PathInPackage

func PathInPackage(path, pkg string) bool

PathInPackage reports whether path contains pkg as a directory fragment.

func SetTarget

func SetTarget(target, rule string, unit *apb.CompilationUnit) error

SetTarget adds a details message to unit with the specified build target name and rule type.

func Write

func Write(w io.WriterTo, path string) error

Write writes w to path, creating the path if necessary and replacing any existing file at that location.

Types

type ActionInfo

type ActionInfo struct {
	Arguments   []string          // command-line arguments
	Inputs      []string          // input file paths
	Outputs     []string          // output file paths
	Sources     []string          // source file paths
	Environment map[string]string // environment variables
	Target      string            // build target name
	Rule        string            // rule class name

}

ActionInfo represents the action metadata relevant to the extraction process.

func SpawnAction

func SpawnAction(info *xapb.ExtraActionInfo) (*ActionInfo, error)

SpawnAction generates an *ActionInfo from a spawn action. It is an error if info does not contain a SpawnInfo.

func (*ActionInfo) Setenv

func (a *ActionInfo) Setenv(key, value string)

Setenv updates the Environment field with the specified key-value pair.

type Config

type Config struct {
	Corpus   string          // the default corpus label to use
	Language string          // the language label to apply
	Rules    vnameutil.Rules // rules for rewriting file VNames
	Verbose  bool            // whether to emit verbose (per-file) logging

	// If set, this function checks whether the given spawn action should be
	// further processed. If it returns an error, the action will be rejected.
	// Otherwise, all actions will be processed.
	//
	// This function may modify its argument, and such changes will be
	// preserved as this is invoked before further processing.
	CheckAction func(context.Context, *ActionInfo) error

	// If set, this function reports whether an input path should be kept in
	// the resulting compilation unit, and returns an optionally-modified
	// version of the path. Otherwise, all inputs are kept.
	CheckInput func(string) (string, bool)

	// If set, this function reports whether an environment variable should be
	// kept in the resulting compilation unit. Otherwise, all environment
	// variables are kept.
	CheckEnv func(name, value string) bool

	// If set, this function reports whether an input path should be considered
	// a source file. Otherwise, no inputs are recorded as sources. The path
	// given to this function reflects any modifications made by CheckInput.
	IsSource func(string) bool

	// If set, this function is called with the updated compilation prior to
	// returning it, and may edit the result. If the function reports an error,
	// that error is propagated along with the compilation.
	FixUnit func(*apb.CompilationUnit) error

	// If set, this function is used to open files for reading.  If nil,
	// os.Open is used.
	OpenRead func(context.Context, string) (io.ReadCloser, error)
}

A Config carries settings that control the extraction process.

By default, all input files are captured as required inputs, all specified environment variables are stored, all command-line arguments are recorded, and the "owner" of the extra action is marked as the build target in a build details message.

The caller may override these behaviours by providing callbacks to handle various stages of the extraction process. Schematically, the extractor does the following steps:

CheckAction .. CheckInputs/Env .. Fetch .. Fixup

The "CheckAction" stage gives the caller an opportunity to preprocess the action and decide whether to continue. The caller may modify the ActionInfo during this process if it wishes.

Next, each input file is checked for inclusion in the compilation, and for whether it should be counted as a source file for the compilation. Also, each environment variable is checked for inclusion.

The "Fetch" stage reads the contents of the required input files selected during the previous stage, computes their digests, and packs them into the compilation record.

Finally, the "Fixup" stage gives the caller a final opportunity to edit the resulting compilation record before it is returned.

func NewFromSettings

func NewFromSettings(s Settings) (*Config, *xapb.ExtraActionInfo, error)

NewFromSettings constructs a new *Config from the given settings, and returns the extra action info fetched from the corresponding file.

An error is reported if the settings are invalid, or the inputs to the config could not be loaded.

func (*Config) ExtractToFile

func (c *Config) ExtractToFile(ctx context.Context, info *ActionInfo, w *kzip.Writer) (string, error)

ExtractToFile extracts a compilation from the specified extra action info, and writes it along with its required inputs to w. The unit digest of the stored compilation is returned.

func (*Config) ExtractToKzip

func (c *Config) ExtractToKzip(ctx context.Context, ai *ActionInfo, outputPath string) error

ExtractToKzip extracts a spawn action through c and writes the results to the specified output file in kzip format. The outputPath must have a suffix of ".kzip".

type Settings

type Settings struct {
	Corpus      string // the corpus label to assign
	Language    string // the language label to assign (required)
	ExtraAction string // path of blaze.ExtraActionInfo file (required)
	VNameRules  string // path of vnames.json file (optional)
	Include     string // include files matching this RE2 ("" includes all files)
	Exclude     string // exclude files matching this RE2 ("" excludes no files)
	SourceFiles string // mark files matching this RE2 as sources ("" marks none)
	SourceArgs  string // mark arguments matching this RE2 as sources ("" marks none)

	Scoped  bool          // only match source paths within the target package
	Verbose bool          // enable verbose per-file logging
	MaxSize datasize.Size // maximum file size (0 marks no maximum)
}

Settings control the construction of an extractor config from common path and name filtering settings.

func (*Settings) SetFlags

func (s *Settings) SetFlags(f *flag.FlagSet, prefix string) func()

SetFlags adds flags to f for each of the fields of s. The specified prefix is prepended to each base flag name. If f == nil, flag.CommandLine is used.

The returned function provides a default usage message that can be used to populate flag.Usage or discarded at the caller's discretion.