1// Copyright (C) 2019 The Android Open Source Project 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15package android 16 17// This file contains all the foundation components for override modules and their base module 18// types. Override modules are a kind of opposite of default modules in that they override certain 19// properties of an existing base module whereas default modules provide base module data to be 20// overridden. However, unlike default and defaultable module pairs, both override and overridable 21// modules generate and output build actions, and it is up to product make vars to decide which one 22// to actually build and install in the end. In other words, default modules and defaultable modules 23// can be compared to abstract classes and concrete classes in C++ and Java. By the same analogy, 24// both override and overridable modules act like concrete classes. 25// 26// There is one more crucial difference from the logic perspective. Unlike default pairs, most Soong 27// actions happen in the base (overridable) module by creating a local variant for each override 28// module based on it. 29 30import ( 31 "sync" 32 33 "github.com/google/blueprint" 34 "github.com/google/blueprint/proptools" 35) 36 37// Interface for override module types, e.g. override_android_app, override_apex 38type OverrideModule interface { 39 Module 40 41 getOverridingProperties() []interface{} 42 setOverridingProperties(properties []interface{}) 43 44 getOverrideModuleProperties() *OverrideModuleProperties 45} 46 47// Base module struct for override module types 48type OverrideModuleBase struct { 49 moduleProperties OverrideModuleProperties 50 51 overridingProperties []interface{} 52} 53 54type OverrideModuleProperties struct { 55 // Name of the base module to be overridden 56 Base *string 57 58 // TODO(jungjw): Add an optional override_name bool flag. 59} 60 61func (o *OverrideModuleBase) getOverridingProperties() []interface{} { 62 return o.overridingProperties 63} 64 65func (o *OverrideModuleBase) setOverridingProperties(properties []interface{}) { 66 o.overridingProperties = properties 67} 68 69func (o *OverrideModuleBase) getOverrideModuleProperties() *OverrideModuleProperties { 70 return &o.moduleProperties 71} 72 73func InitOverrideModule(m OverrideModule) { 74 m.setOverridingProperties(m.GetProperties()) 75 76 m.AddProperties(m.getOverrideModuleProperties()) 77} 78 79// Interface for overridable module types, e.g. android_app, apex 80type OverridableModule interface { 81 setOverridableProperties(prop []interface{}) 82 83 addOverride(o OverrideModule) 84 getOverrides() []OverrideModule 85 86 override(ctx BaseModuleContext, o OverrideModule) 87 88 setOverridesProperty(overridesProperties *[]string) 89} 90 91// Base module struct for overridable module types 92type OverridableModuleBase struct { 93 // List of OverrideModules that override this base module 94 overrides []OverrideModule 95 // Used to parallelize registerOverrideMutator executions. Note that only addOverride locks this 96 // mutex. It is because addOverride and getOverride are used in different mutators, and so are 97 // guaranteed to be not mixed. (And, getOverride only reads from overrides, and so don't require 98 // mutex locking.) 99 overridesLock sync.Mutex 100 101 overridableProperties []interface{} 102 103 // If an overridable module has a property to list other modules that itself overrides, it should 104 // set this to a pointer to the property through the InitOverridableModule function, so that 105 // override information is propagated and aggregated correctly. 106 overridesProperty *[]string 107} 108 109func InitOverridableModule(m OverridableModule, overridesProperty *[]string) { 110 m.setOverridableProperties(m.(Module).GetProperties()) 111 m.setOverridesProperty(overridesProperty) 112} 113 114func (b *OverridableModuleBase) setOverridableProperties(prop []interface{}) { 115 b.overridableProperties = prop 116} 117 118func (b *OverridableModuleBase) addOverride(o OverrideModule) { 119 b.overridesLock.Lock() 120 b.overrides = append(b.overrides, o) 121 b.overridesLock.Unlock() 122} 123 124// Should NOT be used in the same mutator as addOverride. 125func (b *OverridableModuleBase) getOverrides() []OverrideModule { 126 return b.overrides 127} 128 129func (b *OverridableModuleBase) setOverridesProperty(overridesProperty *[]string) { 130 b.overridesProperty = overridesProperty 131} 132 133// Overrides a base module with the given OverrideModule. 134func (b *OverridableModuleBase) override(ctx BaseModuleContext, o OverrideModule) { 135 // Adds the base module to the overrides property, if exists, of the overriding module. See the 136 // comment on OverridableModuleBase.overridesProperty for details. 137 if b.overridesProperty != nil { 138 *b.overridesProperty = append(*b.overridesProperty, ctx.ModuleName()) 139 } 140 for _, p := range b.overridableProperties { 141 for _, op := range o.getOverridingProperties() { 142 if proptools.TypeEqual(p, op) { 143 err := proptools.AppendProperties(p, op, nil) 144 if err != nil { 145 if propertyErr, ok := err.(*proptools.ExtendPropertyError); ok { 146 ctx.PropertyErrorf(propertyErr.Property, "%s", propertyErr.Err.Error()) 147 } else { 148 panic(err) 149 } 150 } 151 } 152 } 153 } 154} 155 156// Mutators for override/overridable modules. All the fun happens in these functions. It is critical 157// to keep them in this order and not put any order mutators between them. 158func RegisterOverridePreArchMutators(ctx RegisterMutatorsContext) { 159 ctx.BottomUp("override_deps", overrideModuleDepsMutator).Parallel() 160 ctx.TopDown("register_override", registerOverrideMutator).Parallel() 161 ctx.BottomUp("perform_override", performOverrideMutator).Parallel() 162} 163 164type overrideBaseDependencyTag struct { 165 blueprint.BaseDependencyTag 166} 167 168var overrideBaseDepTag overrideBaseDependencyTag 169 170// Adds dependency on the base module to the overriding module so that they can be visited in the 171// next phase. 172func overrideModuleDepsMutator(ctx BottomUpMutatorContext) { 173 if module, ok := ctx.Module().(OverrideModule); ok { 174 ctx.AddDependency(ctx.Module(), overrideBaseDepTag, *module.getOverrideModuleProperties().Base) 175 } 176} 177 178// Visits the base module added as a dependency above, checks the module type, and registers the 179// overriding module. 180func registerOverrideMutator(ctx TopDownMutatorContext) { 181 ctx.VisitDirectDepsWithTag(overrideBaseDepTag, func(base Module) { 182 if o, ok := base.(OverridableModule); ok { 183 o.addOverride(ctx.Module().(OverrideModule)) 184 } else { 185 ctx.PropertyErrorf("base", "unsupported base module type") 186 } 187 }) 188} 189 190// Now, goes through all overridable modules, finds all modules overriding them, creates a local 191// variant for each of them, and performs the actual overriding operation by calling override(). 192func performOverrideMutator(ctx BottomUpMutatorContext) { 193 if b, ok := ctx.Module().(OverridableModule); ok { 194 overrides := b.getOverrides() 195 if len(overrides) == 0 { 196 return 197 } 198 variants := make([]string, len(overrides)+1) 199 // The first variant is for the original, non-overridden, base module. 200 variants[0] = "" 201 for i, o := range overrides { 202 variants[i+1] = o.(Module).Name() 203 } 204 mods := ctx.CreateLocalVariations(variants...) 205 for i, o := range overrides { 206 mods[i+1].(OverridableModule).override(ctx, o) 207 } 208 } 209} 210