Improve RuleBuilder documentation and methods
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
diff --git a/android/rule_builder.go b/android/rule_builder.go
index a743a86..c2e5989 100644
--- a/android/rule_builder.go
+++ b/android/rule_builder.go
@@ -24,31 +24,48 @@
"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 @@
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 @@
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 @@
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 @@
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 @@
}
}
+// 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 @@
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 @@
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
}
diff --git a/android/rule_builder_test.go b/android/rule_builder_test.go
index 533b090..c896719 100644
--- a/android/rule_builder_test.go
+++ b/android/rule_builder_test.go
@@ -15,15 +15,103 @@
package android
import (
+ "fmt"
"io/ioutil"
"os"
"path/filepath"
"reflect"
+ "strings"
"testing"
)
+func ExampleRuleBuilder() {
+ rule := NewRuleBuilder()
+
+ rule.Command().Tool("ld").Inputs([]string{"a.o", "b.o"}).FlagWithOutput("-o ", "linked")
+ rule.Command().Text("echo success")
+
+ // To add the command to the build graph:
+ // rule.Build(pctx, ctx, "link", "link")
+
+ fmt.Printf("commands: %q\n", strings.Join(rule.Commands(), " && "))
+ fmt.Printf("tools: %q\n", rule.Tools())
+ fmt.Printf("inputs: %q\n", rule.Inputs())
+ fmt.Printf("outputs: %q\n", rule.Outputs())
+
+ // Output:
+ // commands: "ld a.o b.o -o linked && echo success"
+ // tools: ["ld"]
+ // inputs: ["a.o" "b.o"]
+ // outputs: ["linked"]
+}
+
+func ExampleRuleBuilderCommand() {
+ rule := NewRuleBuilder()
+
+ // chained
+ rule.Command().Tool("ld").Inputs([]string{"a.o", "b.o"}).FlagWithOutput("-o ", "linked")
+
+ // unchained
+ cmd := rule.Command()
+ cmd.Tool("ld")
+ cmd.Inputs([]string{"a.o", "b.o"})
+ cmd.FlagWithOutput("-o ", "linked")
+
+ // mixed:
+ cmd = rule.Command().Tool("ld")
+ cmd.Inputs([]string{"a.o", "b.o"})
+ cmd.FlagWithOutput("-o ", "linked")
+}
+
+func ExampleRuleBuilderCommand_Flag() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("ls").Flag("-l"))
+ // Output:
+ // ls -l
+}
+
+func ExampleRuleBuilderCommand_FlagWithArg() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("ls").
+ FlagWithArg("--sort=", "time"))
+ // Output:
+ // ls --sort=time
+}
+
+func ExampleRuleBuilderCommand_FlagForEachInput() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("turbine").
+ FlagForEachInput("--classpath ", []string{"a.jar", "b.jar"}))
+ // Output:
+ // turbine --classpath a.jar --classpath b.jar
+}
+
+func ExampleRuleBuilderCommand_FlagWithInputList() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("java").
+ FlagWithInputList("-classpath=", []string{"a.jar", "b.jar"}, ":"))
+ // Output:
+ // java -classpath=a.jar:b.jar
+}
+
+func ExampleRuleBuilderCommand_FlagWithInput() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("java").
+ FlagWithInput("-classpath=", "a"))
+ // Output:
+ // java -classpath=a
+}
+
+func ExampleRuleBuilderCommand_FlagWithList() {
+ fmt.Println(NewRuleBuilder().Command().
+ Tool("ls").
+ FlagWithList("--sort=", []string{"time", "size"}, ","))
+ // Output:
+ // ls --sort=time,size
+}
+
func TestRuleBuilder(t *testing.T) {
- rule := RuleBuilder{}
+ rule := NewRuleBuilder()
cmd := rule.Command().
Flag("Flag").
@@ -112,7 +200,7 @@
}
func testRuleBuilder_Build(ctx BuilderContext, in Path, out WritablePath) {
- rule := RuleBuilder{}
+ rule := NewRuleBuilder()
rule.Command().Tool("cp").Input(in.String()).Output(out.String())