diff --git a/android/module.go b/android/module.go index bfb87fa75..1424f7694 100644 --- a/android/module.go +++ b/android/module.go @@ -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 } diff --git a/android/mutator.go b/android/mutator.go index 521255328..738b2ba0a 100644 --- a/android/mutator.go +++ b/android/mutator.go @@ -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) }