StrixOS/build_soong
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve RuleBuilder documentation and methods

Browse Source 
Add a few convenience methods, document all the methods and add
examples that would show up in the godoc if we were to actually
generate it.

Test: rule_builder_test.go
Change-Id: I270fed605ffec34e6f5b36fde0dc9ca52694b741
This commit is contained in:
Colin Cross
2019-02-01 16:42:32 -08:00
parent 786cd6dc13
commit 758290d7ff
3 changed files with 199 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
android/rule_builder.go
View File

@@ -24,31 +24,48 @@ import (
"github.com/google/blueprint/proptools"
)
type RuleBuilderInstall struct {
From, To string
}
// RuleBuilder provides an alternative to ModuleContext.Rule and ModuleContext.Build to add a command line to the build
// graph.
type RuleBuilder struct {
commands []*RuleBuilderCommand
installs []RuleBuilderInstall
restat bool
}
// NewRuleBuilder returns a newly created RuleBuilder.
func NewRuleBuilder() *RuleBuilder {
return &RuleBuilder{}
}
// RuleBuilderInstall is a tuple of install from and to locations.
type RuleBuilderInstall struct {
From, To string
}
// Restat marks the rule as a restat rule, which will be passed to ModuleContext.Rule in BuildParams.Restat.
func (r *RuleBuilder) Restat() *RuleBuilder {
r.restat = true
return r
}
// Install associates an output of the rule with an install location, which can be retrieved later using
// RuleBuilder.Installs.
func (r *RuleBuilder) Install(from, to string) {
r.installs = append(r.installs, RuleBuilderInstall{from, to})
}
// Command returns a new RuleBuilderCommand for the rule. The commands will be ordered in the rule by when they were
// created by this method. That can be mutated through their methods in any order, as long as the mutations do not
// race with any call to Build.
func (r *RuleBuilder) Command() *RuleBuilderCommand {
command := &RuleBuilderCommand{}
r.commands = append(r.commands, command)
return command
}
// Inputs returns the list of paths that were passed to the RuleBuilderCommand methods that take input paths, such
// as RuleBuilderCommand.Input, RuleBuilderComand.Implicit, or RuleBuilderCommand.FlagWithInput. Inputs to a command
// that are also outputs of another command in the same RuleBuilder are filtered out.
func (r *RuleBuilder) Inputs() []string {
outputs := r.outputSet()
@@ -80,6 +97,8 @@ func (r *RuleBuilder) outputSet() map[string]bool {
return outputs
}
// Outputs returns the list of paths that were passed to the RuleBuilderCommand methods that take output paths, such
// as RuleBuilderCommand.Output, RuleBuilderCommand.ImplicitOutput, or RuleBuilderCommand.FlagWithInput.
func (r *RuleBuilder) Outputs() []string {
outputs := r.outputSet()
@@ -91,10 +110,12 @@ func (r *RuleBuilder) Outputs() []string {
return outputList
}
// Installs returns the list of tuples passed to Install.
func (r *RuleBuilder) Installs() []RuleBuilderInstall {
return append([]RuleBuilderInstall(nil), r.installs...)
}
// Tools returns the list of paths that were passed to the RuleBuilderCommand.Tool method.
func (r *RuleBuilder) Tools() []string {
var tools []string
for _, c := range r.commands {
@@ -103,6 +124,7 @@ func (r *RuleBuilder) Tools() []string {
return tools
}
// Commands returns a slice containing a the built command line for each call to RuleBuilder.Command.
func (r *RuleBuilder) Commands() []string {
var commands []string
for _, c := range r.commands {
@@ -111,12 +133,18 @@ func (r *RuleBuilder) Commands() []string {
return commands
}
// BuilderContext is a subset of ModuleContext and SingletonContext.
type BuilderContext interface {
PathContext
Rule(PackageContext, string, blueprint.RuleParams, ...string) blueprint.Rule
Build(PackageContext, BuildParams)
}
var _ BuilderContext = ModuleContext(nil)
var _ BuilderContext = SingletonContext(nil)
// Build adds the built command line to the build graph, with dependencies on Inputs and Tools, and output files for
// Outputs.
func (r *RuleBuilder) Build(pctx PackageContext, ctx BuilderContext, name string, desc string) {
// TODO: convert RuleBuilder arguments and storage to Paths
mctx, _ := ctx.(ModuleContext)
@@ -166,6 +194,10 @@ func (r *RuleBuilder) Build(pctx PackageContext, ctx BuilderContext, name string
}
}
// RuleBuilderCommand is a builder for a command in a command line. It can be mutated by its methods to add to the
// command and track dependencies. The methods mutate the RuleBuilderCommand in place, as well as return the
// RuleBuilderCommand, so they can be used chained or unchained. All methods that add text implicitly add a single
// space as a separator from the previous method.
type RuleBuilderCommand struct {
buf []byte
inputs []string
@@ -173,6 +205,8 @@ type RuleBuilderCommand struct {
tools []string
}
// Text adds the specified raw text to the command line. The text should not contain input or output paths or the
// rule will not have them listed in its dependencies or outputs.
func (c *RuleBuilderCommand) Text(text string) *RuleBuilderCommand {
if len(c.buf) > 0 {
c.buf = append(c.buf, ' ')
@@ -181,67 +215,136 @@ func (c *RuleBuilderCommand) Text(text string) *RuleBuilderCommand {
return c
}
// Textf adds the specified formatted text to the command line. The text should not contain input or output paths or
// the rule will not have them listed in its dependencies or outputs.
func (c *RuleBuilderCommand) Textf(format string, a ...interface{}) *RuleBuilderCommand {
return c.Text(fmt.Sprintf(format, a...))
}
// Flag adds the specified raw text to the command line. The text should not contain input or output paths or the
// rule will not have them listed in its dependencies or outputs.
func (c *RuleBuilderCommand) Flag(flag string) *RuleBuilderCommand {
return c.Text(flag)
}
// FlagWithArg adds the specified flag and argument text to the command line, with no separator between them. The flag
// and argument should not contain input or output paths or the rule will not have them listed in its dependencies or
// outputs.
func (c *RuleBuilderCommand) FlagWithArg(flag, arg string) *RuleBuilderCommand {
return c.Text(flag + arg)
}
// FlagWithArg adds the specified flag and list of arguments to the command line, with the arguments joined by sep
// and no separator between the flag and arguments. The flag and arguments should not contain input or output paths or
// the rule will not have them listed in its dependencies or outputs.
func (c *RuleBuilderCommand) FlagWithList(flag string, list []string, sep string) *RuleBuilderCommand {
return c.Text(flag + strings.Join(list, sep))
}
// Tool adds the specified tool path to the command line. The path will be also added to the dependencies returned by
// RuleBuilder.Tools.
func (c *RuleBuilderCommand) Tool(path string) *RuleBuilderCommand {
c.tools = append(c.tools, path)
return c.Text(path)
}
// Input adds the specified input path to the command line. The path will also be added to the dependencies returned by
// RuleBuilder.Inputs.
func (c *RuleBuilderCommand) Input(path string) *RuleBuilderCommand {
c.inputs = append(c.inputs, path)
return c.Text(path)
}
// Inputs adds the specified input paths to the command line, separated by spaces. The paths will also be added to the
// dependencies returned by RuleBuilder.Inputs.
func (c *RuleBuilderCommand) Inputs(paths []string) *RuleBuilderCommand {
for _, path := range paths {
c.Input(path)
}
return c
}
// Implicit adds the specified input path to the dependencies returned by RuleBuilder.Inputs without modifying the
// command line.
func (c *RuleBuilderCommand) Implicit(path string) *RuleBuilderCommand {
c.inputs = append(c.inputs, path)
return c
}
// Implicits adds the specified input paths to the dependencies returned by RuleBuilder.Inputs without modifying the
// command line.
func (c *RuleBuilderCommand) Implicits(paths []string) *RuleBuilderCommand {
c.inputs = append(c.inputs, paths...)
return c
}
// Output adds the specified output path to the command line. The path will also be added to the outputs returned by
// RuleBuilder.Outputs.
func (c *RuleBuilderCommand) Output(path string) *RuleBuilderCommand {
c.outputs = append(c.outputs, path)
return c.Text(path)
}
// Outputs adds the specified output paths to the command line, separated by spaces. The paths will also be added to
// the outputs returned by RuleBuilder.Outputs.
func (c *RuleBuilderCommand) Outputs(paths []string) *RuleBuilderCommand {
for _, path := range paths {
c.Output(path)
}
return c
}
// ImplicitOutput adds the specified output path to the dependencies returned by RuleBuilder.Outputs without modifying
// the command line.
func (c *RuleBuilderCommand) ImplicitOutput(path string) *RuleBuilderCommand {
c.outputs = append(c.outputs, path)
return c
}
// ImplicitOutputs adds the specified output paths to the dependencies returned by RuleBuilder.Outputs without modifying
// the command line.
func (c *RuleBuilderCommand) ImplicitOutputs(paths []string) *RuleBuilderCommand {
c.outputs = append(c.outputs, paths...)
return c
}
// FlagWithInput adds the specified flag and input path to the command line, with no separator between them. The path
// will also be added to the dependencies returned by RuleBuilder.Inputs.
func (c *RuleBuilderCommand) FlagWithInput(flag, path string) *RuleBuilderCommand {
c.inputs = append(c.inputs, path)
return c.Text(flag + path)
}
// FlagWithInputList adds the specified flag and input paths to the command line, with the inputs joined by sep
// and no separator between the flag and inputs. The input paths will also be added to the dependencies returned by
// RuleBuilder.Inputs.
func (c *RuleBuilderCommand) FlagWithInputList(flag string, paths []string, sep string) *RuleBuilderCommand {
c.inputs = append(c.inputs, paths...)
return c.FlagWithList(flag, paths, sep)
}
// FlagForEachInput adds the specified flag joined with each input path to the command line. The input paths will also
// be added to the dependencies returned by RuleBuilder.Inputs. The result is identical to calling FlagWithInput for
// each input path.
func (c *RuleBuilderCommand) FlagForEachInput(flag string, paths []string) *RuleBuilderCommand {
for _, path := range paths {
c.FlagWithInput(flag, path)
}
return c
}
// FlagWithOutput adds the specified flag and output path to the command line, with no separator between them. The path
// will also be added to the outputs returned by RuleBuilder.Outputs.
func (c *RuleBuilderCommand) FlagWithOutput(flag, path string) *RuleBuilderCommand {
c.outputs = append(c.outputs, path)
return c.Text(flag + path)
}
// String returns the command line.
func (c *RuleBuilderCommand) String() string {
return string(c.buf)
}
type unknownRulePath struct {
path string
}