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
diff --git a/android/mutator.go b/android/mutator.go
index 5212553..738b2ba 100644
--- a/android/mutator.go
+++ b/android/mutator.go
@@ -179,15 +179,24 @@
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
+ BaseMutatorContext
- MutatorName() string
-
- Rename(name string)
-
+ // 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 BottomUpMutator func(BottomUpMutatorContext)
type BottomUpMutatorContext interface {
- BaseModuleContext
+ BaseMutatorContext
- MutatorName() string
-
- Rename(name string)
-
+ // 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)
}