Improve RuleBuilder documentation and methods (758290d7) · Commits · e / os / android_build_soong

android/rule_builder.go

+107 −4

Original line number	Diff line number	Diff line
		@@ -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
		}

android/rule_builder_test.go

+90 −2

Original line number	Diff line number	Diff line
		@@ -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 (t *testRuleBuilderSingleton) GenerateBuildActions(ctx SingletonContext) {
		}

		func testRuleBuilder_Build(ctx BuilderContext, in Path, out WritablePath) {
		rule := RuleBuilder{}
		rule := NewRuleBuilder()

		rule.Command().Tool("cp").Input(in.String()).Output(out.String())

dexpreopt/dexpreopt.go

+2 −2

Original line number	Diff line number	Diff line
		@@ -63,7 +63,7 @@ func GenerateStripRule(global GlobalConfig, module ModuleConfig) (rule *android.

		tools := global.Tools

		rule = &android.RuleBuilder{}
		rule = android.NewRuleBuilder()

		strip := shouldStripDex(module, global)

		@@ -95,7 +95,7 @@ func GenerateDexpreoptRule(global GlobalConfig, module ModuleConfig) (rule *andr
		}
		}()

		rule = &android.RuleBuilder{}
		rule = android.NewRuleBuilder()

		generateProfile := module.ProfileClassListing != "" && !global.DisableGenerateProfile