blob: f9bf360141a67a9efe6733508ebbb7651f701c47 [file] [log] [blame]
Colin Cross6362e272015-10-29 15:25:03 -07001// Copyright 2015 Google Inc. All rights reserved.
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
Colin Cross635c3b02016-05-18 15:37:25 -070015package android
Colin Cross6362e272015-10-29 15:25:03 -070016
Colin Cross795c3772017-03-16 16:50:10 -070017import (
Colin Cross984223f2024-02-01 17:10:23 -080018 "sync"
19
Colin Cross795c3772017-03-16 16:50:10 -070020 "github.com/google/blueprint"
21)
Colin Cross6362e272015-10-29 15:25:03 -070022
Jeff Gastonaf3cc2d2017-09-27 17:01:44 -070023// Phases:
24// run Pre-arch mutators
25// run archMutator
26// run Pre-deps mutators
27// run depsMutator
28// run PostDeps mutators
Colin Cross1e954b62024-09-13 13:50:00 -070029// run FinalDeps mutators (TransitionMutators disallowed in this phase)
Jeff Gastonaf3cc2d2017-09-27 17:01:44 -070030// continue on to GenerateAndroidBuildActions
Colin Cross1e676be2016-10-12 14:38:15 -070031
Paul Duffinc05b0342021-03-06 13:28:13 +000032// collateGloballyRegisteredMutators constructs the list of mutators that have been registered
33// with the InitRegistrationContext and will be used at runtime.
34func collateGloballyRegisteredMutators() sortableComponents {
35 return collateRegisteredMutators(preArch, preDeps, postDeps, finalDeps)
36}
37
38// collateRegisteredMutators constructs a single list of mutators from the separate lists.
39func collateRegisteredMutators(preArch, preDeps, postDeps, finalDeps []RegisterMutatorFunc) sortableComponents {
Colin Crosscec81712017-07-13 14:43:27 -070040 mctx := &registerMutatorsContext{}
Nan Zhangdb0b9a32017-02-27 10:12:13 -080041
42 register := func(funcs []RegisterMutatorFunc) {
43 for _, f := range funcs {
Colin Crosscec81712017-07-13 14:43:27 -070044 f(mctx)
Nan Zhangdb0b9a32017-02-27 10:12:13 -080045 }
46 }
47
Colin Crosscec81712017-07-13 14:43:27 -070048 register(preArch)
Nan Zhangdb0b9a32017-02-27 10:12:13 -080049
Colin Crosscec81712017-07-13 14:43:27 -070050 register(preDeps)
51
Liz Kammer356f7d42021-01-26 09:18:53 -050052 register([]RegisterMutatorFunc{registerDepsMutator})
Colin Crosscec81712017-07-13 14:43:27 -070053
54 register(postDeps)
55
Martin Stjernholm710ec3a2020-01-16 15:12:04 +000056 mctx.finalPhase = true
57 register(finalDeps)
58
Paul Duffinc05b0342021-03-06 13:28:13 +000059 return mctx.mutators
Colin Cross795c3772017-03-16 16:50:10 -070060}
61
62type registerMutatorsContext struct {
Colin Crossb63d7b32023-12-07 16:54:51 -080063 mutators sortableComponents
64 finalPhase bool
Colin Cross795c3772017-03-16 16:50:10 -070065}
Colin Cross1e676be2016-10-12 14:38:15 -070066
67type RegisterMutatorsContext interface {
Colin Cross25de6c32019-06-06 14:29:25 -070068 TopDown(name string, m TopDownMutator) MutatorHandle
69 BottomUp(name string, m BottomUpMutator) MutatorHandle
Colin Cross617b88a2020-08-24 18:04:09 -070070 BottomUpBlueprint(name string, m blueprint.BottomUpMutator) MutatorHandle
Lukacs T. Berki6c716762022-06-13 20:50:39 +020071 Transition(name string, m TransitionMutator)
Colin Cross1e676be2016-10-12 14:38:15 -070072}
73
74type RegisterMutatorFunc func(RegisterMutatorsContext)
75
Colin Crosscec81712017-07-13 14:43:27 -070076var preArch = []RegisterMutatorFunc{
Dan Willemsen6e72ef72018-01-26 18:27:02 -080077 RegisterNamespaceMutator,
Paul Duffinaa4162e2020-05-05 11:35:43 +010078
Paul Duffinaa4162e2020-05-05 11:35:43 +010079 // Check the visibility rules are valid.
80 //
81 // This must run after the package renamer mutators so that any issues found during
82 // validation of the package's default_visibility property are reported using the
83 // correct package name and not the synthetic name.
84 //
85 // This must also be run before defaults mutators as the rules for validation are
86 // different before checking the rules than they are afterwards. e.g.
87 // visibility: ["//visibility:private", "//visibility:public"]
88 // would be invalid if specified in a module definition but is valid if it results
89 // from something like this:
90 //
91 // defaults {
92 // name: "defaults",
93 // // Be inaccessible outside a package by default.
94 // visibility: ["//visibility:private"]
95 // }
96 //
97 // defaultable_module {
98 // name: "defaultable_module",
99 // defaults: ["defaults"],
100 // // Override the default.
101 // visibility: ["//visibility:public"]
102 // }
103 //
Paul Duffin593b3c92019-12-05 14:31:48 +0000104 RegisterVisibilityRuleChecker,
Paul Duffinaa4162e2020-05-05 11:35:43 +0100105
Bob Badour37af0462021-01-07 03:34:31 +0000106 // Record the default_applicable_licenses for each package.
107 //
108 // This must run before the defaults so that defaults modules can pick up the package default.
109 RegisterLicensesPackageMapper,
110
Paul Duffinaa4162e2020-05-05 11:35:43 +0100111 // Apply properties from defaults modules to the referencing modules.
Paul Duffinafa9fa12020-04-29 16:47:28 +0100112 //
113 // Any mutators that are added before this will not see any modules created by
114 // a DefaultableHook.
Colin Cross89536d42017-07-07 14:35:50 -0700115 RegisterDefaultsPreArchMutators,
Paul Duffinaa4162e2020-05-05 11:35:43 +0100116
Paul Duffin44f1d842020-06-26 20:17:02 +0100117 // Add dependencies on any components so that any component references can be
118 // resolved within the deps mutator.
119 //
120 // Must be run after defaults so it can be used to create dependencies on the
121 // component modules that are creating in a DefaultableHook.
122 //
123 // Must be run before RegisterPrebuiltsPreArchMutators, i.e. before prebuilts are
124 // renamed. That is so that if a module creates components using a prebuilt module
125 // type that any dependencies (which must use prebuilt_ prefixes) are resolved to
126 // the prebuilt module and not the source module.
127 RegisterComponentsMutator,
128
Paul Duffinc988c8e2020-04-29 18:27:14 +0100129 // Create an association between prebuilt modules and their corresponding source
130 // modules (if any).
Paul Duffinafa9fa12020-04-29 16:47:28 +0100131 //
132 // Must be run after defaults mutators to ensure that any modules created by
133 // a DefaultableHook can be either a prebuilt or a source module with a matching
134 // prebuilt.
Paul Duffinc988c8e2020-04-29 18:27:14 +0100135 RegisterPrebuiltsPreArchMutators,
136
Bob Badour37af0462021-01-07 03:34:31 +0000137 // Gather the licenses properties for all modules for use during expansion and enforcement.
138 //
139 // This must come after the defaults mutators to ensure that any licenses supplied
140 // in a defaults module has been successfully applied before the rules are gathered.
141 RegisterLicensesPropertyGatherer,
142
Paul Duffinaa4162e2020-05-05 11:35:43 +0100143 // Gather the visibility rules for all modules for us during visibility enforcement.
144 //
145 // This must come after the defaults mutators to ensure that any visibility supplied
146 // in a defaults module has been successfully applied before the rules are gathered.
Paul Duffin593b3c92019-12-05 14:31:48 +0000147 RegisterVisibilityRuleGatherer,
Colin Crosscec81712017-07-13 14:43:27 -0700148}
149
Colin Crossae4c6182017-09-15 17:33:55 -0700150func registerArchMutator(ctx RegisterMutatorsContext) {
Colin Cross8bbc3d52024-09-11 15:33:54 -0700151 ctx.Transition("os", &osTransitionMutator{})
Jihoon Kang5402bbd2024-07-31 18:37:49 +0000152 ctx.Transition("image", &imageTransitionMutator{})
Colin Cross8bbc3d52024-09-11 15:33:54 -0700153 ctx.Transition("arch", &archTransitionMutator{})
Colin Crossae4c6182017-09-15 17:33:55 -0700154}
155
Colin Crosscec81712017-07-13 14:43:27 -0700156var preDeps = []RegisterMutatorFunc{
Colin Crossae4c6182017-09-15 17:33:55 -0700157 registerArchMutator,
Colin Crosscec81712017-07-13 14:43:27 -0700158}
159
160var postDeps = []RegisterMutatorFunc{
Colin Cross1b488422019-03-04 22:33:56 -0800161 registerPathDepsMutator,
Colin Cross5ea9bcc2017-07-27 15:41:32 -0700162 RegisterPrebuiltsPostDepsMutators,
Paul Duffin593b3c92019-12-05 14:31:48 +0000163 RegisterVisibilityRuleEnforcer,
Bob Badour37af0462021-01-07 03:34:31 +0000164 RegisterLicensesDependencyChecker,
Paul Duffin45338f02021-03-30 23:07:52 +0100165 registerNeverallowMutator,
Jaewoong Jungb639a6a2019-05-10 15:16:29 -0700166 RegisterOverridePostDepsMutators,
Colin Crosscec81712017-07-13 14:43:27 -0700167}
Colin Cross1e676be2016-10-12 14:38:15 -0700168
Martin Stjernholm710ec3a2020-01-16 15:12:04 +0000169var finalDeps = []RegisterMutatorFunc{}
170
Colin Cross1e676be2016-10-12 14:38:15 -0700171func PreArchMutators(f RegisterMutatorFunc) {
172 preArch = append(preArch, f)
173}
174
175func PreDepsMutators(f RegisterMutatorFunc) {
176 preDeps = append(preDeps, f)
177}
178
179func PostDepsMutators(f RegisterMutatorFunc) {
180 postDeps = append(postDeps, f)
181}
182
Martin Stjernholm710ec3a2020-01-16 15:12:04 +0000183func FinalDepsMutators(f RegisterMutatorFunc) {
184 finalDeps = append(finalDeps, f)
185}
186
Chris Parsons637458d2023-09-19 20:09:00 +0000187type BaseMutatorContext interface {
188 BaseModuleContext
189
190 // MutatorName returns the name that this mutator was registered with.
191 MutatorName() string
192
193 // Rename all variants of a module. The new name is not visible to calls to ModuleName,
194 // AddDependency or OtherModuleName until after this mutator pass is complete.
195 Rename(name string)
196}
197
198type TopDownMutator func(TopDownMutatorContext)
199
200type TopDownMutatorContext interface {
201 BaseMutatorContext
Chris Parsons637458d2023-09-19 20:09:00 +0000202
203 // CreateModule creates a new module by calling the factory method for the specified moduleType, and applies
204 // the specified property structs to it as if the properties were set in a blueprint file.
205 CreateModule(ModuleFactory, ...interface{}) Module
206}
207
Colin Cross25de6c32019-06-06 14:29:25 -0700208type topDownMutatorContext struct {
Colin Crossdc35e212019-06-06 16:13:11 -0700209 bp blueprint.TopDownMutatorContext
Colin Cross0ea8ba82019-06-06 14:33:29 -0700210 baseModuleContext
Colin Cross6362e272015-10-29 15:25:03 -0700211}
212
Colin Cross25de6c32019-06-06 14:29:25 -0700213type BottomUpMutator func(BottomUpMutatorContext)
Colin Cross6362e272015-10-29 15:25:03 -0700214
Colin Cross635c3b02016-05-18 15:37:25 -0700215type BottomUpMutatorContext interface {
Colin Cross9f35c3d2020-09-16 19:04:41 -0700216 BaseMutatorContext
Colin Crossb63d7b32023-12-07 16:54:51 -0800217
218 // AddDependency adds a dependency to the given module. It returns a slice of modules for each
219 // dependency (some entries may be nil).
220 //
221 // If the mutator is parallel (see MutatorHandle.Parallel), this method will pause until the
222 // new dependencies have had the current mutator called on them. If the mutator is not
223 // parallel this method does not affect the ordering of the current mutator pass, but will
224 // be ordered correctly for all future mutator passes.
225 AddDependency(module blueprint.Module, tag blueprint.DependencyTag, name ...string) []blueprint.Module
Colin Crossaabf6792017-11-29 00:27:14 -0800226
Colin Cross9f35c3d2020-09-16 19:04:41 -0700227 // AddReverseDependency adds a dependency from the destination to the given module.
228 // Does not affect the ordering of the current mutator pass, but will be ordered
229 // correctly for all future mutator passes. All reverse dependencies for a destination module are
230 // collected until the end of the mutator pass, sorted by name, and then appended to the destination
231 // module's dependency list.
Colin Crossaabf6792017-11-29 00:27:14 -0800232 AddReverseDependency(module blueprint.Module, tag blueprint.DependencyTag, name string)
Colin Cross9f35c3d2020-09-16 19:04:41 -0700233
Colin Cross9f35c3d2020-09-16 19:04:41 -0700234 // AddVariationDependencies adds deps as dependencies of the current module, but uses the variations
Colin Cross4f1dcb02020-09-16 18:45:04 -0700235 // argument to select which variant of the dependency to use. It returns a slice of modules for
236 // each dependency (some entries may be nil). A variant of the dependency must exist that matches
Usta Shresthac725f472022-01-11 02:44:21 -0500237 // all the non-local variations of the current module, plus the variations argument.
Colin Cross4f1dcb02020-09-16 18:45:04 -0700238 //
239 // If the mutator is parallel (see MutatorHandle.Parallel), this method will pause until the
240 // new dependencies have had the current mutator called on them. If the mutator is not
241 // parallel this method does not affect the ordering of the current mutator pass, but will
242 // be ordered correctly for all future mutator passes.
Usta Shresthac725f472022-01-11 02:44:21 -0500243 AddVariationDependencies(variations []blueprint.Variation, tag blueprint.DependencyTag, names ...string) []blueprint.Module
Colin Cross9f35c3d2020-09-16 19:04:41 -0700244
245 // AddFarVariationDependencies adds deps as dependencies of the current module, but uses the
Colin Cross4f1dcb02020-09-16 18:45:04 -0700246 // variations argument to select which variant of the dependency to use. It returns a slice of
247 // modules for each dependency (some entries may be nil). A variant of the dependency must
248 // exist that matches the variations argument, but may also have other variations.
Colin Cross9f35c3d2020-09-16 19:04:41 -0700249 // For any unspecified variation the first variant will be used.
250 //
251 // Unlike AddVariationDependencies, the variations of the current module are ignored - the
252 // dependency only needs to match the supplied variations.
Colin Cross4f1dcb02020-09-16 18:45:04 -0700253 //
254 // If the mutator is parallel (see MutatorHandle.Parallel), this method will pause until the
255 // new dependencies have had the current mutator called on them. If the mutator is not
256 // parallel this method does not affect the ordering of the current mutator pass, but will
257 // be ordered correctly for all future mutator passes.
258 AddFarVariationDependencies([]blueprint.Variation, blueprint.DependencyTag, ...string) []blueprint.Module
Colin Cross9f35c3d2020-09-16 19:04:41 -0700259
Colin Cross86771322024-05-01 14:19:51 -0700260 // ReplaceDependencies finds all the variants of the module with the specified name, then
261 // replaces all dependencies onto those variants with the current variant of this module.
262 // Replacements don't take effect until after the mutator pass is finished.
Colin Crossaabf6792017-11-29 00:27:14 -0800263 ReplaceDependencies(string)
Colin Cross9f35c3d2020-09-16 19:04:41 -0700264
Colin Cross86771322024-05-01 14:19:51 -0700265 // ReplaceDependenciesIf finds all the variants of the module with the specified name, then
266 // replaces all dependencies onto those variants with the current variant of this module
267 // as long as the supplied predicate returns true.
Colin Cross9f35c3d2020-09-16 19:04:41 -0700268 // Replacements don't take effect until after the mutator pass is finished.
Paul Duffin80342d72020-06-26 22:08:43 +0100269 ReplaceDependenciesIf(string, blueprint.ReplaceDependencyPredicate)
Colin Cross6362e272015-10-29 15:25:03 -0700270}
271
Colin Cross984223f2024-02-01 17:10:23 -0800272// An outgoingTransitionContextImpl and incomingTransitionContextImpl is created for every dependency of every module
273// for each transition mutator. bottomUpMutatorContext and topDownMutatorContext are created once for every module
274// for every BottomUp or TopDown mutator. Use a global pool for each to avoid reallocating every time.
275var (
276 outgoingTransitionContextPool = sync.Pool{
277 New: func() any { return &outgoingTransitionContextImpl{} },
278 }
279 incomingTransitionContextPool = sync.Pool{
280 New: func() any { return &incomingTransitionContextImpl{} },
281 }
282 bottomUpMutatorContextPool = sync.Pool{
283 New: func() any { return &bottomUpMutatorContext{} },
284 }
285
286 topDownMutatorContextPool = sync.Pool{
287 New: func() any { return &topDownMutatorContext{} },
288 }
289)
290
Colin Cross25de6c32019-06-06 14:29:25 -0700291type bottomUpMutatorContext struct {
Colin Crossdc35e212019-06-06 16:13:11 -0700292 bp blueprint.BottomUpMutatorContext
Colin Cross0ea8ba82019-06-06 14:33:29 -0700293 baseModuleContext
Chris Parsons5a34ffb2021-07-21 14:34:58 -0400294 finalPhase bool
Colin Cross6362e272015-10-29 15:25:03 -0700295}
296
Colin Cross984223f2024-02-01 17:10:23 -0800297// callers must immediately follow the call to this function with defer bottomUpMutatorContextPool.Put(mctx).
Colin Cross617b88a2020-08-24 18:04:09 -0700298func bottomUpMutatorContextFactory(ctx blueprint.BottomUpMutatorContext, a Module,
Colin Crossb63d7b32023-12-07 16:54:51 -0800299 finalPhase bool) BottomUpMutatorContext {
Colin Cross617b88a2020-08-24 18:04:09 -0700300
Chris Parsons5a34ffb2021-07-21 14:34:58 -0400301 moduleContext := a.base().baseModuleContextFactory(ctx)
Colin Cross984223f2024-02-01 17:10:23 -0800302 mctx := bottomUpMutatorContextPool.Get().(*bottomUpMutatorContext)
303 *mctx = bottomUpMutatorContext{
Chris Parsons5a34ffb2021-07-21 14:34:58 -0400304 bp: ctx,
Cole Faust0abd4b42023-01-10 10:49:18 -0800305 baseModuleContext: moduleContext,
Chris Parsons5a34ffb2021-07-21 14:34:58 -0400306 finalPhase: finalPhase,
Colin Cross617b88a2020-08-24 18:04:09 -0700307 }
Colin Cross984223f2024-02-01 17:10:23 -0800308 return mctx
Colin Cross617b88a2020-08-24 18:04:09 -0700309}
310
Colin Cross25de6c32019-06-06 14:29:25 -0700311func (x *registerMutatorsContext) BottomUp(name string, m BottomUpMutator) MutatorHandle {
Martin Stjernholm710ec3a2020-01-16 15:12:04 +0000312 finalPhase := x.finalPhase
Colin Cross798bfce2016-10-12 14:28:16 -0700313 f := func(ctx blueprint.BottomUpMutatorContext) {
Colin Cross635c3b02016-05-18 15:37:25 -0700314 if a, ok := ctx.Module().(Module); ok {
Colin Cross984223f2024-02-01 17:10:23 -0800315 mctx := bottomUpMutatorContextFactory(ctx, a, finalPhase)
316 defer bottomUpMutatorContextPool.Put(mctx)
317 m(mctx)
Colin Cross6362e272015-10-29 15:25:03 -0700318 }
Colin Cross798bfce2016-10-12 14:28:16 -0700319 }
Liz Kammer356f7d42021-01-26 09:18:53 -0500320 mutator := &mutator{name: x.mutatorName(name), bottomUpMutator: f}
Colin Cross795c3772017-03-16 16:50:10 -0700321 x.mutators = append(x.mutators, mutator)
Colin Cross798bfce2016-10-12 14:28:16 -0700322 return mutator
Colin Cross6362e272015-10-29 15:25:03 -0700323}
324
Colin Cross617b88a2020-08-24 18:04:09 -0700325func (x *registerMutatorsContext) BottomUpBlueprint(name string, m blueprint.BottomUpMutator) MutatorHandle {
326 mutator := &mutator{name: name, bottomUpMutator: m}
327 x.mutators = append(x.mutators, mutator)
328 return mutator
329}
330
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200331type IncomingTransitionContext interface {
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800332 ArchModuleContext
Colin Crossaf333f52024-04-15 15:20:23 -0700333 ModuleProviderContext
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800334
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200335 // Module returns the target of the dependency edge for which the transition
336 // is being computed
337 Module() Module
338
339 // Config returns the configuration for the build.
340 Config() Config
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800341
342 DeviceConfig() DeviceConfig
Colin Crosse1a85552024-06-14 12:17:37 -0700343
344 // IsAddingDependency returns true if the transition is being called while adding a dependency
345 // after the transition mutator has already run, or false if it is being called when the transition
346 // mutator is running. This should be used sparingly, all uses will have to be removed in order
347 // to support creating variants on demand.
348 IsAddingDependency() bool
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200349}
350
351type OutgoingTransitionContext interface {
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800352 ArchModuleContext
Colin Crossaf333f52024-04-15 15:20:23 -0700353 ModuleProviderContext
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800354
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200355 // Module returns the target of the dependency edge for which the transition
356 // is being computed
357 Module() Module
358
359 // DepTag() Returns the dependency tag through which this dependency is
360 // reached
361 DepTag() blueprint.DependencyTag
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800362
363 // Config returns the configuration for the build.
364 Config() Config
365
366 DeviceConfig() DeviceConfig
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200367}
Lukacs T. Berki0e691c12022-06-24 10:15:55 +0200368
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800369// TransitionMutator implements a top-down mechanism where a module tells its
Lukacs T. Berki0e691c12022-06-24 10:15:55 +0200370// direct dependencies what variation they should be built in but the dependency
371// has the final say.
372//
373// When implementing a transition mutator, one needs to implement four methods:
374// - Split() that tells what variations a module has by itself
375// - OutgoingTransition() where a module tells what it wants from its
376// dependency
377// - IncomingTransition() where a module has the final say about its own
378// variation
379// - Mutate() that changes the state of a module depending on its variation
380//
381// That the effective variation of module B when depended on by module A is the
382// composition the outgoing transition of module A and the incoming transition
383// of module B.
384//
385// the outgoing transition should not take the properties of the dependency into
386// account, only those of the module that depends on it. For this reason, the
387// dependency is not even passed into it as an argument. Likewise, the incoming
388// transition should not take the properties of the depending module into
389// account and is thus not informed about it. This makes for a nice
390// decomposition of the decision logic.
391//
392// A given transition mutator only affects its own variation; other variations
393// stay unchanged along the dependency edges.
394//
395// Soong makes sure that all modules are created in the desired variations and
396// that dependency edges are set up correctly. This ensures that "missing
397// variation" errors do not happen and allows for more flexible changes in the
398// value of the variation among dependency edges (as oppposed to bottom-up
399// mutators where if module A in variation X depends on module B and module B
400// has that variation X, A must depend on variation X of B)
401//
402// The limited power of the context objects passed to individual mutators
403// methods also makes it more difficult to shoot oneself in the foot. Complete
404// safety is not guaranteed because no one prevents individual transition
405// mutators from mutating modules in illegal ways and for e.g. Split() or
406// Mutate() to run their own visitations of the transitive dependency of the
407// module and both of these are bad ideas, but it's better than no guardrails at
408// all.
409//
410// This model is pretty close to Bazel's configuration transitions. The mapping
411// between concepts in Soong and Bazel is as follows:
412// - Module == configured target
413// - Variant == configuration
414// - Variation name == configuration flag
415// - Variation == configuration flag value
416// - Outgoing transition == attribute transition
417// - Incoming transition == rule transition
418//
419// The Split() method does not have a Bazel equivalent and Bazel split
420// transitions do not have a Soong equivalent.
421//
422// Mutate() does not make sense in Bazel due to the different models of the
423// two systems: when creating new variations, Soong clones the old module and
424// thus some way is needed to change it state whereas Bazel creates each
425// configuration of a given configured target anew.
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200426type TransitionMutator interface {
427 // Split returns the set of variations that should be created for a module no
428 // matter who depends on it. Used when Make depends on a particular variation
429 // or when the module knows its variations just based on information given to
430 // it in the Blueprint file. This method should not mutate the module it is
431 // called on.
432 Split(ctx BaseModuleContext) []string
433
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800434 // OutgoingTransition is called on a module to determine which variation it wants
435 // from its direct dependencies. The dependency itself can override this decision.
436 // This method should not mutate the module itself.
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200437 OutgoingTransition(ctx OutgoingTransitionContext, sourceVariation string) string
438
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800439 // IncomingTransition is called on a module to determine which variation it should
440 // be in based on the variation modules that depend on it want. This gives the module
441 // a final say about its own variations. This method should not mutate the module
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200442 // itself.
443 IncomingTransition(ctx IncomingTransitionContext, incomingVariation string) string
444
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800445 // Mutate is called after a module was split into multiple variations on each variation.
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200446 // It should not split the module any further but adding new dependencies is
447 // fine. Unlike all the other methods on TransitionMutator, this method is
448 // allowed to mutate the module.
449 Mutate(ctx BottomUpMutatorContext, variation string)
450}
451
452type androidTransitionMutator struct {
Colin Crossb63d7b32023-12-07 16:54:51 -0800453 finalPhase bool
454 mutator TransitionMutator
Colin Crossd67425d2024-04-15 15:17:05 -0700455 name string
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200456}
457
458func (a *androidTransitionMutator) Split(ctx blueprint.BaseModuleContext) []string {
Colin Crossd27205e2024-09-12 22:41:37 -0700459 if a.finalPhase {
460 panic("TransitionMutator not allowed in FinalDepsMutators")
461 }
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200462 if m, ok := ctx.Module().(Module); ok {
463 moduleContext := m.base().baseModuleContextFactory(ctx)
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200464 return a.mutator.Split(&moduleContext)
465 } else {
466 return []string{""}
467 }
468}
469
470type outgoingTransitionContextImpl struct {
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800471 archModuleContext
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200472 bp blueprint.OutgoingTransitionContext
473}
474
475func (c *outgoingTransitionContextImpl) Module() Module {
476 return c.bp.Module().(Module)
477}
478
479func (c *outgoingTransitionContextImpl) DepTag() blueprint.DependencyTag {
480 return c.bp.DepTag()
481}
482
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800483func (c *outgoingTransitionContextImpl) Config() Config {
484 return c.bp.Config().(Config)
485}
486
487func (c *outgoingTransitionContextImpl) DeviceConfig() DeviceConfig {
488 return DeviceConfig{c.bp.Config().(Config).deviceConfig}
489}
490
Colin Crossaf333f52024-04-15 15:20:23 -0700491func (c *outgoingTransitionContextImpl) provider(provider blueprint.AnyProviderKey) (any, bool) {
492 return c.bp.Provider(provider)
493}
494
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800495func (a *androidTransitionMutator) OutgoingTransition(bpctx blueprint.OutgoingTransitionContext, sourceVariation string) string {
496 if m, ok := bpctx.Module().(Module); ok {
Colin Cross984223f2024-02-01 17:10:23 -0800497 ctx := outgoingTransitionContextPool.Get().(*outgoingTransitionContextImpl)
498 defer outgoingTransitionContextPool.Put(ctx)
499 *ctx = outgoingTransitionContextImpl{
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800500 archModuleContext: m.base().archModuleContextFactory(bpctx),
501 bp: bpctx,
502 }
503 return a.mutator.OutgoingTransition(ctx, sourceVariation)
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200504 } else {
505 return ""
506 }
507}
508
509type incomingTransitionContextImpl struct {
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800510 archModuleContext
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200511 bp blueprint.IncomingTransitionContext
512}
513
514func (c *incomingTransitionContextImpl) Module() Module {
515 return c.bp.Module().(Module)
516}
517
518func (c *incomingTransitionContextImpl) Config() Config {
519 return c.bp.Config().(Config)
520}
521
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800522func (c *incomingTransitionContextImpl) DeviceConfig() DeviceConfig {
523 return DeviceConfig{c.bp.Config().(Config).deviceConfig}
524}
525
Colin Crosse1a85552024-06-14 12:17:37 -0700526func (c *incomingTransitionContextImpl) IsAddingDependency() bool {
527 return c.bp.IsAddingDependency()
528}
529
Colin Crossaf333f52024-04-15 15:20:23 -0700530func (c *incomingTransitionContextImpl) provider(provider blueprint.AnyProviderKey) (any, bool) {
531 return c.bp.Provider(provider)
532}
533
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800534func (a *androidTransitionMutator) IncomingTransition(bpctx blueprint.IncomingTransitionContext, incomingVariation string) string {
535 if m, ok := bpctx.Module().(Module); ok {
Colin Cross984223f2024-02-01 17:10:23 -0800536 ctx := incomingTransitionContextPool.Get().(*incomingTransitionContextImpl)
537 defer incomingTransitionContextPool.Put(ctx)
538 *ctx = incomingTransitionContextImpl{
Colin Cross4aa3e0a2024-01-18 17:22:58 -0800539 archModuleContext: m.base().archModuleContextFactory(bpctx),
540 bp: bpctx,
541 }
542 return a.mutator.IncomingTransition(ctx, incomingVariation)
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200543 } else {
544 return ""
545 }
546}
547
548func (a *androidTransitionMutator) Mutate(ctx blueprint.BottomUpMutatorContext, variation string) {
549 if am, ok := ctx.Module().(Module); ok {
Colin Cross888046f2024-05-01 14:20:31 -0700550 if variation != "" {
551 // TODO: this should really be checking whether the TransitionMutator affected this module, not
552 // the empty variant, but TransitionMutator has no concept of skipping a module.
553 base := am.base()
554 base.commonProperties.DebugMutators = append(base.commonProperties.DebugMutators, a.name)
555 base.commonProperties.DebugVariations = append(base.commonProperties.DebugVariations, variation)
556 }
557
Colin Cross984223f2024-02-01 17:10:23 -0800558 mctx := bottomUpMutatorContextFactory(ctx, am, a.finalPhase)
559 defer bottomUpMutatorContextPool.Put(mctx)
560 a.mutator.Mutate(mctx, variation)
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200561 }
562}
563
564func (x *registerMutatorsContext) Transition(name string, m TransitionMutator) {
565 atm := &androidTransitionMutator{
Colin Crossb63d7b32023-12-07 16:54:51 -0800566 finalPhase: x.finalPhase,
567 mutator: m,
Colin Crossd67425d2024-04-15 15:17:05 -0700568 name: name,
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200569 }
570 mutator := &mutator{
571 name: name,
572 transitionMutator: atm}
573 x.mutators = append(x.mutators, mutator)
574}
575
Liz Kammer356f7d42021-01-26 09:18:53 -0500576func (x *registerMutatorsContext) mutatorName(name string) string {
Liz Kammer356f7d42021-01-26 09:18:53 -0500577 return name
578}
579
Colin Cross25de6c32019-06-06 14:29:25 -0700580func (x *registerMutatorsContext) TopDown(name string, m TopDownMutator) MutatorHandle {
Colin Cross798bfce2016-10-12 14:28:16 -0700581 f := func(ctx blueprint.TopDownMutatorContext) {
Colin Cross635c3b02016-05-18 15:37:25 -0700582 if a, ok := ctx.Module().(Module); ok {
Chris Parsons5a34ffb2021-07-21 14:34:58 -0400583 moduleContext := a.base().baseModuleContextFactory(ctx)
Colin Cross984223f2024-02-01 17:10:23 -0800584 actx := topDownMutatorContextPool.Get().(*topDownMutatorContext)
585 defer topDownMutatorContextPool.Put(actx)
586 *actx = topDownMutatorContext{
Colin Crossdc35e212019-06-06 16:13:11 -0700587 bp: ctx,
Chris Parsons5a34ffb2021-07-21 14:34:58 -0400588 baseModuleContext: moduleContext,
Colin Cross6362e272015-10-29 15:25:03 -0700589 }
Colin Cross798bfce2016-10-12 14:28:16 -0700590 m(actx)
Colin Cross6362e272015-10-29 15:25:03 -0700591 }
Colin Cross798bfce2016-10-12 14:28:16 -0700592 }
Liz Kammer356f7d42021-01-26 09:18:53 -0500593 mutator := &mutator{name: x.mutatorName(name), topDownMutator: f}
Colin Cross795c3772017-03-16 16:50:10 -0700594 x.mutators = append(x.mutators, mutator)
Colin Cross798bfce2016-10-12 14:28:16 -0700595 return mutator
596}
597
Paul Duffin1d2d42f2021-03-06 20:08:12 +0000598func (mutator *mutator) componentName() string {
599 return mutator.name
600}
601
602func (mutator *mutator) register(ctx *Context) {
603 blueprintCtx := ctx.Context
604 var handle blueprint.MutatorHandle
605 if mutator.bottomUpMutator != nil {
606 handle = blueprintCtx.RegisterBottomUpMutator(mutator.name, mutator.bottomUpMutator)
607 } else if mutator.topDownMutator != nil {
608 handle = blueprintCtx.RegisterTopDownMutator(mutator.name, mutator.topDownMutator)
Lukacs T. Berki6c716762022-06-13 20:50:39 +0200609 } else if mutator.transitionMutator != nil {
610 blueprintCtx.RegisterTransitionMutator(mutator.name, mutator.transitionMutator)
Paul Duffin1d2d42f2021-03-06 20:08:12 +0000611 }
612 if mutator.parallel {
613 handle.Parallel()
614 }
615}
616
Colin Cross798bfce2016-10-12 14:28:16 -0700617type MutatorHandle interface {
618 Parallel() MutatorHandle
619}
620
621func (mutator *mutator) Parallel() MutatorHandle {
622 mutator.parallel = true
623 return mutator
Colin Cross6362e272015-10-29 15:25:03 -0700624}
Colin Cross1e676be2016-10-12 14:38:15 -0700625
Paul Duffin44f1d842020-06-26 20:17:02 +0100626func RegisterComponentsMutator(ctx RegisterMutatorsContext) {
627 ctx.BottomUp("component-deps", componentDepsMutator).Parallel()
628}
629
630// A special mutator that runs just prior to the deps mutator to allow the dependencies
631// on component modules to be added so that they can depend directly on a prebuilt
632// module.
633func componentDepsMutator(ctx BottomUpMutatorContext) {
Cole Fausta963b942024-04-11 17:43:00 -0700634 ctx.Module().ComponentDepsMutator(ctx)
Paul Duffin44f1d842020-06-26 20:17:02 +0100635}
636
Colin Cross1e676be2016-10-12 14:38:15 -0700637func depsMutator(ctx BottomUpMutatorContext) {
Cole Fausta963b942024-04-11 17:43:00 -0700638 if m := ctx.Module(); m.Enabled(ctx) {
Ronald Braunstein73b08ff2023-12-19 10:24:47 -0800639 m.base().baseDepsMutator(ctx)
Colin Cross1e676be2016-10-12 14:38:15 -0700640 m.DepsMutator(ctx)
641 }
642}
Colin Crossd11fcda2017-10-23 17:59:01 -0700643
Liz Kammer356f7d42021-01-26 09:18:53 -0500644func registerDepsMutator(ctx RegisterMutatorsContext) {
645 ctx.BottomUp("deps", depsMutator).Parallel()
646}
647
Colin Crossdc35e212019-06-06 16:13:11 -0700648// android.topDownMutatorContext either has to embed blueprint.TopDownMutatorContext, in which case every method that
649// has an overridden version in android.BaseModuleContext has to be manually forwarded to BaseModuleContext to avoid
650// ambiguous method errors, or it has to store a blueprint.TopDownMutatorContext non-embedded, in which case every
651// non-overridden method has to be forwarded. There are fewer non-overridden methods, so use the latter. The following
652// methods forward to the identical blueprint versions for topDownMutatorContext and bottomUpMutatorContext.
653
Colin Crosscb55e082019-07-01 15:32:31 -0700654func (t *topDownMutatorContext) MutatorName() string {
655 return t.bp.MutatorName()
656}
657
Colin Crossdc35e212019-06-06 16:13:11 -0700658func (t *topDownMutatorContext) Rename(name string) {
659 t.bp.Rename(name)
Colin Cross9a362232019-07-01 15:32:45 -0700660 t.Module().base().commonProperties.DebugName = name
Colin Crossdc35e212019-06-06 16:13:11 -0700661}
662
Liz Kammerf31c9002022-04-26 09:08:55 -0400663func (t *topDownMutatorContext) createModule(factory blueprint.ModuleFactory, name string, props ...interface{}) blueprint.Module {
664 return t.bp.CreateModule(factory, name, props...)
665}
666
Colin Crosse003c4a2019-09-25 12:58:36 -0700667func (t *topDownMutatorContext) CreateModule(factory ModuleFactory, props ...interface{}) Module {
Liz Kammerf31c9002022-04-26 09:08:55 -0400668 return createModule(t, factory, "_topDownMutatorModule", props...)
Colin Crossdc35e212019-06-06 16:13:11 -0700669}
670
Liz Kammera060c452021-03-24 10:14:47 -0400671func (t *topDownMutatorContext) createModuleWithoutInheritance(factory ModuleFactory, props ...interface{}) Module {
Liz Kammerf31c9002022-04-26 09:08:55 -0400672 module := t.bp.CreateModule(ModuleFactoryAdaptor(factory), "", props...).(Module)
Liz Kammera060c452021-03-24 10:14:47 -0400673 return module
674}
675
Colin Crosscb55e082019-07-01 15:32:31 -0700676func (b *bottomUpMutatorContext) MutatorName() string {
677 return b.bp.MutatorName()
678}
679
Colin Crossdc35e212019-06-06 16:13:11 -0700680func (b *bottomUpMutatorContext) Rename(name string) {
681 b.bp.Rename(name)
Colin Cross9a362232019-07-01 15:32:45 -0700682 b.Module().base().commonProperties.DebugName = name
Colin Crossdc35e212019-06-06 16:13:11 -0700683}
684
Colin Cross4f1dcb02020-09-16 18:45:04 -0700685func (b *bottomUpMutatorContext) AddDependency(module blueprint.Module, tag blueprint.DependencyTag, name ...string) []blueprint.Module {
Liz Kammerc13f7852023-05-17 13:01:48 -0400686 if b.baseModuleContext.checkedMissingDeps() {
687 panic("Adding deps not allowed after checking for missing deps")
688 }
Colin Cross4f1dcb02020-09-16 18:45:04 -0700689 return b.bp.AddDependency(module, tag, name...)
Colin Crossdc35e212019-06-06 16:13:11 -0700690}
691
692func (b *bottomUpMutatorContext) AddReverseDependency(module blueprint.Module, tag blueprint.DependencyTag, name string) {
Liz Kammerc13f7852023-05-17 13:01:48 -0400693 if b.baseModuleContext.checkedMissingDeps() {
694 panic("Adding deps not allowed after checking for missing deps")
695 }
Colin Crossdc35e212019-06-06 16:13:11 -0700696 b.bp.AddReverseDependency(module, tag, name)
697}
Colin Crossdc35e212019-06-06 16:13:11 -0700698func (b *bottomUpMutatorContext) AddVariationDependencies(variations []blueprint.Variation, tag blueprint.DependencyTag,
Colin Cross4f1dcb02020-09-16 18:45:04 -0700699 names ...string) []blueprint.Module {
Liz Kammerc13f7852023-05-17 13:01:48 -0400700 if b.baseModuleContext.checkedMissingDeps() {
701 panic("Adding deps not allowed after checking for missing deps")
702 }
Colin Cross4f1dcb02020-09-16 18:45:04 -0700703 return b.bp.AddVariationDependencies(variations, tag, names...)
Colin Crossdc35e212019-06-06 16:13:11 -0700704}
705
706func (b *bottomUpMutatorContext) AddFarVariationDependencies(variations []blueprint.Variation,
Colin Cross4f1dcb02020-09-16 18:45:04 -0700707 tag blueprint.DependencyTag, names ...string) []blueprint.Module {
Liz Kammerc13f7852023-05-17 13:01:48 -0400708 if b.baseModuleContext.checkedMissingDeps() {
709 panic("Adding deps not allowed after checking for missing deps")
710 }
Colin Crossdc35e212019-06-06 16:13:11 -0700711
Colin Cross4f1dcb02020-09-16 18:45:04 -0700712 return b.bp.AddFarVariationDependencies(variations, tag, names...)
Colin Crossdc35e212019-06-06 16:13:11 -0700713}
714
Colin Crossdc35e212019-06-06 16:13:11 -0700715func (b *bottomUpMutatorContext) ReplaceDependencies(name string) {
Liz Kammerc13f7852023-05-17 13:01:48 -0400716 if b.baseModuleContext.checkedMissingDeps() {
717 panic("Adding deps not allowed after checking for missing deps")
718 }
Colin Crossdc35e212019-06-06 16:13:11 -0700719 b.bp.ReplaceDependencies(name)
720}
Jaewoong Jung9f88ce22019-11-15 10:57:34 -0800721
Paul Duffin80342d72020-06-26 22:08:43 +0100722func (b *bottomUpMutatorContext) ReplaceDependenciesIf(name string, predicate blueprint.ReplaceDependencyPredicate) {
Liz Kammerc13f7852023-05-17 13:01:48 -0400723 if b.baseModuleContext.checkedMissingDeps() {
724 panic("Adding deps not allowed after checking for missing deps")
725 }
Paul Duffin80342d72020-06-26 22:08:43 +0100726 b.bp.ReplaceDependenciesIf(name, predicate)
727}