blob: 09959e43d61fcfdf2c3c81aff7b6d193755b0365 [file] [log] [blame]
Jaewoong Jung525443a2019-02-28 15:35:54 -08001// 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)
Jaewoong Jungb639a6a2019-05-10 15:16:29 -070087 getOverriddenBy() string
Jaewoong Jung525443a2019-02-28 15:35:54 -080088
89 setOverridesProperty(overridesProperties *[]string)
Jaewoong Jungb639a6a2019-05-10 15:16:29 -070090
91 // Due to complications with incoming dependencies, overrides are processed after DepsMutator.
92 // So, overridable properties need to be handled in a separate, dedicated deps mutator.
93 OverridablePropertiesDepsMutator(ctx BottomUpMutatorContext)
Jaewoong Jung525443a2019-02-28 15:35:54 -080094}
95
96// Base module struct for overridable module types
97type OverridableModuleBase struct {
Jaewoong Jung525443a2019-02-28 15:35:54 -080098 // List of OverrideModules that override this base module
99 overrides []OverrideModule
100 // Used to parallelize registerOverrideMutator executions. Note that only addOverride locks this
101 // mutex. It is because addOverride and getOverride are used in different mutators, and so are
102 // guaranteed to be not mixed. (And, getOverride only reads from overrides, and so don't require
103 // mutex locking.)
104 overridesLock sync.Mutex
105
106 overridableProperties []interface{}
107
108 // If an overridable module has a property to list other modules that itself overrides, it should
109 // set this to a pointer to the property through the InitOverridableModule function, so that
110 // override information is propagated and aggregated correctly.
111 overridesProperty *[]string
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700112
113 overriddenBy string
Jaewoong Jung525443a2019-02-28 15:35:54 -0800114}
115
116func InitOverridableModule(m OverridableModule, overridesProperty *[]string) {
117 m.setOverridableProperties(m.(Module).GetProperties())
118 m.setOverridesProperty(overridesProperty)
119}
120
121func (b *OverridableModuleBase) setOverridableProperties(prop []interface{}) {
122 b.overridableProperties = prop
123}
124
125func (b *OverridableModuleBase) addOverride(o OverrideModule) {
126 b.overridesLock.Lock()
127 b.overrides = append(b.overrides, o)
128 b.overridesLock.Unlock()
129}
130
131// Should NOT be used in the same mutator as addOverride.
132func (b *OverridableModuleBase) getOverrides() []OverrideModule {
133 return b.overrides
134}
135
136func (b *OverridableModuleBase) setOverridesProperty(overridesProperty *[]string) {
137 b.overridesProperty = overridesProperty
138}
139
140// Overrides a base module with the given OverrideModule.
141func (b *OverridableModuleBase) override(ctx BaseModuleContext, o OverrideModule) {
Jaewoong Junga641ee92019-03-27 11:17:14 -0700142 // Adds the base module to the overrides property, if exists, of the overriding module. See the
143 // comment on OverridableModuleBase.overridesProperty for details.
144 if b.overridesProperty != nil {
Jaewoong Jung8985d522019-06-19 11:22:25 -0700145 *b.overridesProperty = append(*b.overridesProperty, ctx.ModuleName())
Jaewoong Junga641ee92019-03-27 11:17:14 -0700146 }
Jaewoong Jung525443a2019-02-28 15:35:54 -0800147 for _, p := range b.overridableProperties {
148 for _, op := range o.getOverridingProperties() {
149 if proptools.TypeEqual(p, op) {
Jaewoong Junga641ee92019-03-27 11:17:14 -0700150 err := proptools.AppendProperties(p, op, nil)
Jaewoong Jung525443a2019-02-28 15:35:54 -0800151 if err != nil {
152 if propertyErr, ok := err.(*proptools.ExtendPropertyError); ok {
153 ctx.PropertyErrorf(propertyErr.Property, "%s", propertyErr.Err.Error())
154 } else {
155 panic(err)
156 }
157 }
158 }
159 }
160 }
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700161 b.overriddenBy = o.Name()
162}
163
164func (b *OverridableModuleBase) getOverriddenBy() string {
165 return b.overriddenBy
166}
167
168func (b *OverridableModuleBase) OverridablePropertiesDepsMutator(ctx BottomUpMutatorContext) {
Jaewoong Jung525443a2019-02-28 15:35:54 -0800169}
170
171// Mutators for override/overridable modules. All the fun happens in these functions. It is critical
172// to keep them in this order and not put any order mutators between them.
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700173func RegisterOverridePostDepsMutators(ctx RegisterMutatorsContext) {
Jaewoong Jung525443a2019-02-28 15:35:54 -0800174 ctx.BottomUp("override_deps", overrideModuleDepsMutator).Parallel()
175 ctx.TopDown("register_override", registerOverrideMutator).Parallel()
176 ctx.BottomUp("perform_override", performOverrideMutator).Parallel()
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700177 ctx.BottomUp("overridable_deps", overridableModuleDepsMutator).Parallel()
Jaewoong Jung26dedd32019-06-06 08:45:58 -0700178 ctx.BottomUp("replace_deps_on_override", replaceDepsOnOverridingModuleMutator).Parallel()
Jaewoong Jung525443a2019-02-28 15:35:54 -0800179}
180
181type overrideBaseDependencyTag struct {
182 blueprint.BaseDependencyTag
183}
184
185var overrideBaseDepTag overrideBaseDependencyTag
186
187// Adds dependency on the base module to the overriding module so that they can be visited in the
188// next phase.
189func overrideModuleDepsMutator(ctx BottomUpMutatorContext) {
190 if module, ok := ctx.Module().(OverrideModule); ok {
191 ctx.AddDependency(ctx.Module(), overrideBaseDepTag, *module.getOverrideModuleProperties().Base)
192 }
193}
194
195// Visits the base module added as a dependency above, checks the module type, and registers the
196// overriding module.
197func registerOverrideMutator(ctx TopDownMutatorContext) {
198 ctx.VisitDirectDepsWithTag(overrideBaseDepTag, func(base Module) {
199 if o, ok := base.(OverridableModule); ok {
200 o.addOverride(ctx.Module().(OverrideModule))
201 } else {
202 ctx.PropertyErrorf("base", "unsupported base module type")
203 }
204 })
205}
206
207// Now, goes through all overridable modules, finds all modules overriding them, creates a local
208// variant for each of them, and performs the actual overriding operation by calling override().
209func performOverrideMutator(ctx BottomUpMutatorContext) {
210 if b, ok := ctx.Module().(OverridableModule); ok {
211 overrides := b.getOverrides()
212 if len(overrides) == 0 {
213 return
214 }
215 variants := make([]string, len(overrides)+1)
216 // The first variant is for the original, non-overridden, base module.
217 variants[0] = ""
218 for i, o := range overrides {
219 variants[i+1] = o.(Module).Name()
220 }
221 mods := ctx.CreateLocalVariations(variants...)
Jaewoong Jung26dedd32019-06-06 08:45:58 -0700222 // Make the original variation the default one to depend on if no other override module variant
223 // is specified.
224 ctx.AliasVariation(variants[0])
Jaewoong Jung525443a2019-02-28 15:35:54 -0800225 for i, o := range overrides {
226 mods[i+1].(OverridableModule).override(ctx, o)
227 }
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700228 } else if o, ok := ctx.Module().(OverrideModule); ok {
229 // Create a variant of the overriding module with its own name. This matches the above local
230 // variant name rule for overridden modules, and thus allows ReplaceDependencies to match the
231 // two.
232 ctx.CreateLocalVariations(o.Name())
Jaewoong Jung26dedd32019-06-06 08:45:58 -0700233 // To allow dependencies to be added without having to know the above variation.
234 ctx.AliasVariation(o.Name())
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700235 }
236}
237
238func overridableModuleDepsMutator(ctx BottomUpMutatorContext) {
239 if b, ok := ctx.Module().(OverridableModule); ok {
Jaewoong Jung26dedd32019-06-06 08:45:58 -0700240 b.OverridablePropertiesDepsMutator(ctx)
241 }
242}
243
244func replaceDepsOnOverridingModuleMutator(ctx BottomUpMutatorContext) {
245 if b, ok := ctx.Module().(OverridableModule); ok {
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700246 if o := b.getOverriddenBy(); o != "" {
247 // Redirect dependencies on the overriding module to this overridden module. Overriding
248 // modules are basically pseudo modules, and all build actions are associated to overridden
249 // modules. Therefore, dependencies on overriding modules need to be forwarded there as well.
250 ctx.ReplaceDependencies(o)
251 }
Jaewoong Jung525443a2019-02-28 15:35:54 -0800252 }
253}