openkylin
/
platform_build_soong
mirror of https://gitee.com/openkylin/platform_build_soong.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

Copy documentation from Blueprint interfaces into Soong interfaces 

Copy documentation from Blueprint for interface methods that are
wrapped into Soong interfaces.

Test: m checkbuild
Change-Id: Ib58c9201b8e7dfbf900a252e709f0a3cfed73286
This commit is contained in:
Colin Cross 2020-09-16 19:04:41 -07:00
parent a018b3df16
commit 9f35c3d6dd
2 changed files with 216 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
android/module.go
View File

@ -61,18 +61,44 @@ type ModuleBuildParams BuildParams
// EarlyModuleContext provides methods that can be called early, as soon as the properties have
// been parsed into the module and before any mutators have run.
type EarlyModuleContext interface {
// Module returns the current module as a Module. It should rarely be necessary, as the module already has a
// reference to itself.
Module() Module
// ModuleName returns the name of the module. This is generally the value that was returned by Module.Name() when
// the module was created, but may have been modified by calls to BaseMutatorContext.Rename.
ModuleName() string
// ModuleDir returns the path to the directory that contains the definition of the module.
ModuleDir() string
// ModuleType returns the name of the module type that was used to create the module, as specified in
// RegisterModuleType.
ModuleType() string
// BlueprintFile returns the name of the blueprint file that contains the definition of this
// module.
BlueprintsFile() string
// ContainsProperty returns true if the specified property name was set in the module definition.
ContainsProperty(name string) bool
// Errorf reports an error at the specified position of the module definition file.
Errorf(pos scanner.Position, fmt string, args ...interface{})
// ModuleErrorf reports an error at the line number of the module type in the module definition.
ModuleErrorf(fmt string, args ...interface{})
// PropertyErrorf reports an error at the line number of a property in the module definition.
PropertyErrorf(property, fmt string, args ...interface{})
// Failed returns true if any errors have been reported. In most cases the module can continue with generating
// build rules after an error, allowing it to report additional errors in a single run, but in cases where the error
// has prevented the module from creating necessary data it can return early when Failed returns true.
Failed() bool
// AddNinjaFileDeps adds dependencies on the specified files to the rule that creates the ninja manifest. The
// primary builder will be rerun whenever the specified files are modified.
AddNinjaFileDeps(deps ...string)
DeviceSpecific() bool
@ -98,6 +124,8 @@ type EarlyModuleContext interface {
IsSymlink(path Path) bool
Readlink(path Path) string
// Namespace returns the Namespace object provided by the NameInterface set by Context.SetNameInterface, or the
// default SimpleNameInterface if Context.SetNameInterface was not called.
Namespace() *Namespace
}
@ -110,29 +138,109 @@ type BaseModuleContext interface {
blueprintBaseModuleContext() blueprint.BaseModuleContext
// OtherModuleName returns the name of another Module. See BaseModuleContext.ModuleName for more information.
// It is intended for use inside the visit functions of Visit* and WalkDeps.
OtherModuleName(m blueprint.Module) string
// OtherModuleDir returns the directory of another Module. See BaseModuleContext.ModuleDir for more information.
// It is intended for use inside the visit functions of Visit* and WalkDeps.
OtherModuleDir(m blueprint.Module) string
// OtherModuleErrorf reports an error on another Module. See BaseModuleContext.ModuleErrorf for more information.
// It is intended for use inside the visit functions of Visit* and WalkDeps.
OtherModuleErrorf(m blueprint.Module, fmt string, args ...interface{})
// OtherModuleDependencyTag returns the dependency tag used to depend on a module, or nil if there is no dependency
// on the module. When called inside a Visit* method with current module being visited, and there are multiple
// dependencies on the module being visited, it returns the dependency tag used for the current dependency.
OtherModuleDependencyTag(m blueprint.Module) blueprint.DependencyTag
// OtherModuleExists returns true if a module with the specified name exists, as determined by the NameInterface
// passed to Context.SetNameInterface, or SimpleNameInterface if it was not called.
OtherModuleExists(name string) bool
// OtherModuleDependencyVariantExists returns true if a module with the
// specified name and variant exists. The variant must match the given
// variations. It must also match all the non-local variations of the current
// module. In other words, it checks for the module AddVariationDependencies
// would add a dependency on with the same arguments.
OtherModuleDependencyVariantExists(variations []blueprint.Variation, name string) bool
// OtherModuleReverseDependencyVariantExists returns true if a module with the
// specified name exists with the same variations as the current module. In
// other words, it checks for the module AddReverseDependency would add a
// dependency on with the same argument.
OtherModuleReverseDependencyVariantExists(name string) bool
// OtherModuleType returns the type of another Module. See BaseModuleContext.ModuleType for more information.
// It is intended for use inside the visit functions of Visit* and WalkDeps.
OtherModuleType(m blueprint.Module) string
GetDirectDepsWithTag(tag blueprint.DependencyTag) []Module
// GetDirectDepWithTag returns the Module the direct dependency with the specified name, or nil if
// none exists. It panics if the dependency does not have the specified tag. It skips any
// dependencies that are not an android.Module.
GetDirectDepWithTag(name string, tag blueprint.DependencyTag) blueprint.Module
// GetDirectDep returns the Module and DependencyTag for the direct dependency with the specified
// name, or nil if none exists. If there are multiple dependencies on the same module it returns
// the first DependencyTag. It skips any dependencies that are not an android.Module.
GetDirectDep(name string) (blueprint.Module, blueprint.DependencyTag)
// VisitDirectDepsBlueprint calls visit for each direct dependency. If there are multiple
// direct dependencies on the same module visit will be called multiple times on that module
// and OtherModuleDependencyTag will return a different tag for each.
//
// The Module passed to the visit function should not be retained outside of the visit
// function, it may be invalidated by future mutators.
VisitDirectDepsBlueprint(visit func(blueprint.Module))
// VisitDirectDeps calls visit for each direct dependency. If there are multiple
// direct dependencies on the same module visit will be called multiple times on that module
// and OtherModuleDependencyTag will return a different tag for each. It skips any
// dependencies that are not an android.Module.
//
// The Module passed to the visit function should not be retained outside of the visit
// function, it may be invalidated by future mutators.
VisitDirectDeps(visit func(Module))
VisitDirectDepsWithTag(tag blueprint.DependencyTag, visit func(Module))
// VisitDirectDepsIf calls pred for each direct dependency, and if pred returns true calls visit. If there are
// multiple direct dependencies on the same module pred and visit will be called multiple times on that module and
// OtherModuleDependencyTag will return a different tag for each. It skips any
// dependencies that are not an android.Module.
//
// The Module passed to the visit function should not be retained outside of the visit function, it may be
// invalidated by future mutators.
VisitDirectDepsIf(pred func(Module) bool, visit func(Module))
// Deprecated: use WalkDeps instead to support multiple dependency tags on the same module
VisitDepsDepthFirst(visit func(Module))
// Deprecated: use WalkDeps instead to support multiple dependency tags on the same module
VisitDepsDepthFirstIf(pred func(Module) bool, visit func(Module))
// WalkDeps calls visit for each transitive dependency, traversing the dependency tree in top down order. visit may
// be called multiple times for the same (child, parent) pair if there are multiple direct dependencies between the
// child and parent with different tags. OtherModuleDependencyTag will return the tag for the currently visited
// (child, parent) pair. If visit returns false WalkDeps will not continue recursing down to child. It skips
// any dependencies that are not an android.Module.
//
// The Modules passed to the visit function should not be retained outside of the visit function, they may be
// invalidated by future mutators.
WalkDeps(visit func(Module, Module) bool)
// WalkDepsBlueprint calls visit for each transitive dependency, traversing the dependency
// tree in top down order. visit may be called multiple times for the same (child, parent)
// pair if there are multiple direct dependencies between the child and parent with different
// tags. OtherModuleDependencyTag will return the tag for the currently visited
// (child, parent) pair. If visit returns false WalkDeps will not continue recursing down
// to child.
//
// The Modules passed to the visit function should not be retained outside of the visit function, they may be
// invalidated by future mutators.
WalkDepsBlueprint(visit func(blueprint.Module, blueprint.Module) bool)
// GetWalkPath is supposed to be called in visit function passed in WalkDeps()
// and returns a top-down dependency path from a start module to current child module.
GetWalkPath() []Module
@ -216,10 +324,26 @@ type ModuleContext interface {
// additional dependencies.
Phony(phony string, deps ...Path)
// PrimaryModule returns the first variant of the current module. Variants of a module are always visited in
// order by mutators and GenerateBuildActions, so the data created by the current mutator can be read from the
// Module returned by PrimaryModule without data races. This can be used to perform singleton actions that are
// only done once for all variants of a module.
PrimaryModule() Module
// FinalModule returns the last variant of the current module. Variants of a module are always visited in
// order by mutators and GenerateBuildActions, so the data created by the current mutator can be read from all
// variants using VisitAllModuleVariants if the current module == FinalModule(). This can be used to perform
// singleton actions that are only done once for all variants of a module.
FinalModule() Module
// VisitAllModuleVariants calls visit for each variant of the current module. Variants of a module are always
// visited in order by mutators and GenerateBuildActions, so the data created by the current mutator can be read
// from all variants if the current module == FinalModule(). Otherwise, care must be taken to not access any
// data modified by the current mutator.
VisitAllModuleVariants(visit func(Module))
// GetMissingDependencies returns the list of dependencies that were passed to AddDependencies or related methods,
// but do not exist.
GetMissingDependencies() []string
}

102
android/mutator.go
View File

@ -179,15 +179,24 @@ func FinalDepsMutators(f RegisterMutatorFunc) {
finalDeps = append(finalDeps, f)
}
type BaseMutatorContext interface {
BaseModuleContext
// MutatorName returns the name that this mutator was registered with.
MutatorName() string
// Rename all variants of a module. The new name is not visible to calls to ModuleName,
// AddDependency or OtherModuleName until after this mutator pass is complete.
Rename(name string)
}
type TopDownMutator func(TopDownMutatorContext)
type TopDownMutatorContext interface {
BaseModuleContext
MutatorName() string
Rename(name string)
BaseMutatorContext
// CreateModule creates a new module by calling the factory method for the specified moduleType, and applies
// the specified property structs to it as if the properties were set in a blueprint file.
CreateModule(ModuleFactory, ...interface{}) Module
}
@ -199,24 +208,97 @@ type topDownMutatorContext struct {
type BottomUpMutator func(BottomUpMutatorContext)
type BottomUpMutatorContext interface {
BaseModuleContext
MutatorName() string
Rename(name string)
BaseMutatorContext
// AddDependency adds a dependency to the given module.
// Does not affect the ordering of the current mutator pass, but will be ordered
// correctly for all future mutator passes.
AddDependency(module blueprint.Module, tag blueprint.DependencyTag, name ...string)
// AddReverseDependency adds a dependency from the destination to the given module.
// Does not affect the ordering of the current mutator pass, but will be ordered
// correctly for all future mutator passes. All reverse dependencies for a destination module are
// collected until the end of the mutator pass, sorted by name, and then appended to the destination
// module's dependency list.
AddReverseDependency(module blueprint.Module, tag blueprint.DependencyTag, name string)
// CreateVariations splits a module into multiple variants, one for each name in the variationNames
// parameter. It returns a list of new modules in the same order as the variationNames
// list.
//
// If any of the dependencies of the module being operated on were already split
// by calling CreateVariations with the same name, the dependency will automatically
// be updated to point the matching variant.
//
// If a module is split, and then a module depending on the first module is not split
// when the Mutator is later called on it, the dependency of the depending module will
// automatically be updated to point to the first variant.
CreateVariations(...string) []Module
// CreateLocationVariations splits a module into multiple variants, one for each name in the variantNames
// parameter. It returns a list of new modules in the same order as the variantNames
// list.
//
// Local variations do not affect automatic dependency resolution - dependencies added
// to the split module via deps or DynamicDependerModule must exactly match a variant
// that contains all the non-local variations.
CreateLocalVariations(...string) []Module
// SetDependencyVariation sets all dangling dependencies on the current module to point to the variation
// with given name. This function ignores the default variation set by SetDefaultDependencyVariation.
SetDependencyVariation(string)
// SetDefaultDependencyVariation sets the default variation when a dangling reference is detected
// during the subsequent calls on Create*Variations* functions. To reset, set it to nil.
SetDefaultDependencyVariation(*string)
// AddVariationDependencies adds deps as dependencies of the current module, but uses the variations
// argument to select which variant of the dependency to use. A variant of the dependency must
// exist that matches the all of the non-local variations of the current module, plus the variations
// argument.
AddVariationDependencies([]blueprint.Variation, blueprint.DependencyTag, ...string)
// AddFarVariationDependencies adds deps as dependencies of the current module, but uses the
// variations argument to select which variant of the dependency to use. A variant of the
// dependency must exist that matches the variations argument, but may also have other variations.
// For any unspecified variation the first variant will be used.
//
// Unlike AddVariationDependencies, the variations of the current module are ignored - the
// dependency only needs to match the supplied variations.
AddFarVariationDependencies([]blueprint.Variation, blueprint.DependencyTag, ...string)
// AddInterVariantDependency adds a dependency between two variants of the same module. Variants are always
// ordered in the same orderas they were listed in CreateVariations, and AddInterVariantDependency does not change
// that ordering, but it associates a DependencyTag with the dependency and makes it visible to VisitDirectDeps,
// WalkDeps, etc.
AddInterVariantDependency(tag blueprint.DependencyTag, from, to blueprint.Module)
// ReplaceDependencies replaces all dependencies on the identical variant of the module with the
// specified name with the current variant of this module. Replacements don't take effect until
// after the mutator pass is finished.
ReplaceDependencies(string)
// ReplaceDependencies replaces all dependencies on the identical variant of the module with the
// specified name with the current variant of this module as long as the supplied predicate returns
// true.
//
// Replacements don't take effect until after the mutator pass is finished.
ReplaceDependenciesIf(string, blueprint.ReplaceDependencyPredicate)
// AliasVariation takes a variationName that was passed to CreateVariations for this module,
// and creates an alias from the current variant (before the mutator has run) to the new
// variant. The alias will be valid until the next time a mutator calls CreateVariations or
// CreateLocalVariations on this module without also calling AliasVariation. The alias can
// be used to add dependencies on the newly created variant using the variant map from
// before CreateVariations was run.
AliasVariation(variationName string)
// CreateAliasVariation takes a toVariationName that was passed to CreateVariations for this
// module, and creates an alias from a new fromVariationName variant the toVariationName
// variant. The alias will be valid until the next time a mutator calls CreateVariations or
// CreateLocalVariations on this module without also calling AliasVariation. The alias can
// be used to add dependencies on the toVariationName variant using the fromVariationName
// variant.
CreateAliasVariation(fromVariationName, toVariationName string)
}