blob: e70003144f5ff8685b3e8b1557a6fe4a37f9c22c [file] [log] [blame]
Jiyong Parkd1063c12019-07-17 20:08:41 +09001// 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
17import (
Paul Duffin255f18e2019-12-13 11:22:16 +000018 "sort"
Jiyong Parkd1063c12019-07-17 20:08:41 +090019 "strings"
20
Paul Duffin13879572019-11-28 14:31:38 +000021 "github.com/google/blueprint"
Jiyong Parkd1063c12019-07-17 20:08:41 +090022 "github.com/google/blueprint/proptools"
23)
24
Paul Duffin923e8a52020-03-30 15:33:32 +010025// Extracted from SdkAware to make it easier to define custom subsets of the
26// SdkAware interface and improve code navigation within the IDE.
27//
28// In addition to its use in SdkAware this interface must also be implemented by
29// APEX to specify the SDKs required by that module and its contents. e.g. APEX
30// is expected to implement RequiredSdks() by reading its own properties like
31// `uses_sdks`.
32type RequiredSdks interface {
33 // The set of SDKs required by an APEX and its contents.
34 RequiredSdks() SdkRefs
35}
36
Paul Duffin50f0da42020-07-22 13:52:01 +010037// Provided to improve code navigation with the IDE.
38type sdkAwareWithoutModule interface {
Paul Duffin923e8a52020-03-30 15:33:32 +010039 RequiredSdks
40
Paul Duffinb97b1572021-04-29 21:50:40 +010041 // SdkMemberComponentName will return the name to use for a component of this module based on the
42 // base name of this module.
43 //
44 // The baseName is the name returned by ModuleBase.BaseModuleName(), i.e. the name specified in
45 // the name property in the .bp file so will not include the prebuilt_ prefix.
46 //
47 // The componentNameCreator is a func for creating the name of a component from the base name of
48 // the module, e.g. it could just append ".component" to the name passed in.
49 //
50 // This is intended to be called by prebuilt modules that create component models. It is because
51 // prebuilt module base names come in a variety of different forms:
52 // * unversioned - this is the same as the source module.
53 // * internal to an sdk - this is the unversioned name prefixed by the base name of the sdk
54 // module.
55 // * versioned - this is the same as the internal with the addition of an "@<version>" suffix.
56 //
57 // While this can be called from a source module in that case it will behave the same way as the
58 // unversioned name and return the result of calling the componentNameCreator func on the supplied
59 // base name.
60 //
61 // e.g. Assuming the componentNameCreator func simply appends ".component" to the name passed in
62 // then this will work as follows:
63 // * An unversioned name of "foo" will return "foo.component".
64 // * An internal to the sdk name of "sdk_foo" will return "sdk_foo.component".
65 // * A versioned name of "sdk_foo@current" will return "sdk_foo.component@current".
66 //
67 // Note that in the latter case the ".component" suffix is added before the version. Adding it
68 // after would change the version.
69 SdkMemberComponentName(baseName string, componentNameCreator func(string) string) string
70
Jiyong Parkd1063c12019-07-17 20:08:41 +090071 sdkBase() *SdkBase
72 MakeMemberOf(sdk SdkRef)
73 IsInAnySdk() bool
Paul Duffinb9e7a3c2021-05-06 15:53:19 +010074
75 // IsVersioned determines whether the module is versioned, i.e. has a name of the form
76 // <name>@<version>
77 IsVersioned() bool
78
Jiyong Parkd1063c12019-07-17 20:08:41 +090079 ContainingSdk() SdkRef
80 MemberName() string
81 BuildWithSdks(sdks SdkRefs)
Jiyong Parkd1063c12019-07-17 20:08:41 +090082}
83
Paul Duffin50f0da42020-07-22 13:52:01 +010084// SdkAware is the interface that must be supported by any module to become a member of SDK or to be
85// built with SDK
86type SdkAware interface {
87 Module
88 sdkAwareWithoutModule
89}
90
Jiyong Parkd1063c12019-07-17 20:08:41 +090091// SdkRef refers to a version of an SDK
92type SdkRef struct {
93 Name string
94 Version string
95}
96
Jiyong Park9b409bc2019-10-11 14:59:13 +090097// Unversioned determines if the SdkRef is referencing to the unversioned SDK module
98func (s SdkRef) Unversioned() bool {
99 return s.Version == ""
Jiyong Parkd1063c12019-07-17 20:08:41 +0900100}
101
Jiyong Parka7bc8ad2019-10-15 15:20:07 +0900102// String returns string representation of this SdkRef for debugging purpose
103func (s SdkRef) String() string {
104 if s.Name == "" {
105 return "(No Sdk)"
106 }
107 if s.Unversioned() {
108 return s.Name
109 }
110 return s.Name + string(SdkVersionSeparator) + s.Version
111}
112
Jiyong Park9b409bc2019-10-11 14:59:13 +0900113// SdkVersionSeparator is a character used to separate an sdk name and its version
114const SdkVersionSeparator = '@'
Jiyong Parkd1063c12019-07-17 20:08:41 +0900115
Jiyong Park9b409bc2019-10-11 14:59:13 +0900116// ParseSdkRef parses a `name@version` style string into a corresponding SdkRef struct
Jiyong Parkd1063c12019-07-17 20:08:41 +0900117func ParseSdkRef(ctx BaseModuleContext, str string, property string) SdkRef {
Jiyong Park9b409bc2019-10-11 14:59:13 +0900118 tokens := strings.Split(str, string(SdkVersionSeparator))
Jiyong Parkd1063c12019-07-17 20:08:41 +0900119 if len(tokens) < 1 || len(tokens) > 2 {
Paul Duffin525a5902021-05-06 16:33:52 +0100120 ctx.PropertyErrorf(property, "%q does not follow name@version syntax", str)
Jiyong Parkd1063c12019-07-17 20:08:41 +0900121 return SdkRef{Name: "invalid sdk name", Version: "invalid sdk version"}
122 }
123
124 name := tokens[0]
125
Jiyong Park9b409bc2019-10-11 14:59:13 +0900126 var version string
Jiyong Parkd1063c12019-07-17 20:08:41 +0900127 if len(tokens) == 2 {
128 version = tokens[1]
129 }
130
131 return SdkRef{Name: name, Version: version}
132}
133
134type SdkRefs []SdkRef
135
Jiyong Park9b409bc2019-10-11 14:59:13 +0900136// Contains tells if the given SdkRef is in this list of SdkRef's
Jiyong Parkd1063c12019-07-17 20:08:41 +0900137func (refs SdkRefs) Contains(s SdkRef) bool {
138 for _, r := range refs {
139 if r == s {
140 return true
141 }
142 }
143 return false
144}
145
146type sdkProperties struct {
147 // The SDK that this module is a member of. nil if it is not a member of any SDK
148 ContainingSdk *SdkRef `blueprint:"mutated"`
149
150 // The list of SDK names and versions that are used to build this module
151 RequiredSdks SdkRefs `blueprint:"mutated"`
152
153 // Name of the module that this sdk member is representing
154 Sdk_member_name *string
155}
156
157// SdkBase is a struct that is expected to be included in module types to implement the SdkAware
158// interface. InitSdkAwareModule should be called to initialize this struct.
159type SdkBase struct {
160 properties sdkProperties
Paul Duffin0e0cf1d2019-11-12 19:39:25 +0000161 module SdkAware
Jiyong Parkd1063c12019-07-17 20:08:41 +0900162}
163
164func (s *SdkBase) sdkBase() *SdkBase {
165 return s
166}
167
Paul Duffinb97b1572021-04-29 21:50:40 +0100168func (s *SdkBase) SdkMemberComponentName(baseName string, componentNameCreator func(string) string) string {
169 if s.MemberName() == "" {
170 return componentNameCreator(baseName)
171 } else {
172 index := strings.LastIndex(baseName, "@")
173 unversionedName := baseName[:index]
174 unversionedComponentName := componentNameCreator(unversionedName)
175 versionSuffix := baseName[index:]
176 return unversionedComponentName + versionSuffix
177 }
178}
179
Jiyong Park9b409bc2019-10-11 14:59:13 +0900180// MakeMemberOf sets this module to be a member of a specific SDK
Jiyong Parkd1063c12019-07-17 20:08:41 +0900181func (s *SdkBase) MakeMemberOf(sdk SdkRef) {
182 s.properties.ContainingSdk = &sdk
183}
184
185// IsInAnySdk returns true if this module is a member of any SDK
186func (s *SdkBase) IsInAnySdk() bool {
187 return s.properties.ContainingSdk != nil
188}
189
Paul Duffinb9e7a3c2021-05-06 15:53:19 +0100190// IsVersioned returns true if this module is versioned.
191func (s *SdkBase) IsVersioned() bool {
192 return strings.Contains(s.module.Name(), "@")
193}
194
Jiyong Parkd1063c12019-07-17 20:08:41 +0900195// ContainingSdk returns the SDK that this module is a member of
196func (s *SdkBase) ContainingSdk() SdkRef {
197 if s.properties.ContainingSdk != nil {
198 return *s.properties.ContainingSdk
199 }
Jiyong Park9b409bc2019-10-11 14:59:13 +0900200 return SdkRef{Name: "", Version: ""}
Jiyong Parkd1063c12019-07-17 20:08:41 +0900201}
202
Jiyong Park9b409bc2019-10-11 14:59:13 +0900203// MemberName returns the name of the module that this SDK member is overriding
Jiyong Parkd1063c12019-07-17 20:08:41 +0900204func (s *SdkBase) MemberName() string {
205 return proptools.String(s.properties.Sdk_member_name)
206}
207
208// BuildWithSdks is used to mark that this module has to be built with the given SDK(s).
209func (s *SdkBase) BuildWithSdks(sdks SdkRefs) {
210 s.properties.RequiredSdks = sdks
211}
212
213// RequiredSdks returns the SDK(s) that this module has to be built with
214func (s *SdkBase) RequiredSdks() SdkRefs {
215 return s.properties.RequiredSdks
216}
217
218// InitSdkAwareModule initializes the SdkBase struct. This must be called by all modules including
219// SdkBase.
220func InitSdkAwareModule(m SdkAware) {
221 base := m.sdkBase()
Paul Duffin0e0cf1d2019-11-12 19:39:25 +0000222 base.module = m
Jiyong Parkd1063c12019-07-17 20:08:41 +0900223 m.AddProperties(&base.properties)
224}
Paul Duffin0e0cf1d2019-11-12 19:39:25 +0000225
Paul Duffin0c2e0832021-04-28 00:39:52 +0100226// IsModuleInVersionedSdk returns true if the module is an versioned sdk.
227func IsModuleInVersionedSdk(module Module) bool {
228 if s, ok := module.(SdkAware); ok {
229 if !s.ContainingSdk().Unversioned() {
230 return true
231 }
232 }
233 return false
234}
235
Paul Duffin0e0cf1d2019-11-12 19:39:25 +0000236// Provide support for generating the build rules which will build the snapshot.
237type SnapshotBuilder interface {
238 // Copy src to the dest (which is a snapshot relative path) and add the dest
239 // to the zip
240 CopyToSnapshot(src Path, dest string)
241
Paul Duffin91547182019-11-12 19:39:36 +0000242 // Unzip the supplied zip into the snapshot relative directory destDir.
243 UnzipToSnapshot(zipPath Path, destDir string)
244
Paul Duffinb645ec82019-11-27 17:43:54 +0000245 // Add a new prebuilt module to the snapshot. The returned module
246 // must be populated with the module type specific properties. The following
247 // properties will be automatically populated.
248 //
249 // * name
250 // * sdk_member_name
251 // * prefer
252 //
253 // This will result in two Soong modules being generated in the Android. One
254 // that is versioned, coupled to the snapshot version and marked as
255 // prefer=true. And one that is not versioned, not marked as prefer=true and
256 // will only be used if the equivalently named non-prebuilt module is not
257 // present.
Paul Duffin9d8d6092019-12-05 18:19:29 +0000258 AddPrebuiltModule(member SdkMember, moduleType string) BpModule
Paul Duffin7b81f5e2020-01-13 21:03:22 +0000259
260 // The property tag to use when adding a property to a BpModule that contains
261 // references to other sdk members. Using this will ensure that the reference
262 // is correctly output for both versioned and unversioned prebuilts in the
263 // snapshot.
264 //
Paul Duffin13f02712020-03-06 12:30:43 +0000265 // "required: true" means that the property must only contain references
266 // to other members of the sdk. Passing a reference to a module that is not a
267 // member of the sdk will result in a build error.
268 //
269 // "required: false" means that the property can contain references to modules
270 // that are either members or not members of the sdk. If a reference is to a
271 // module that is a non member then the reference is left unchanged, i.e. it
272 // is not transformed as references to members are.
273 //
274 // The handling of the member names is dependent on whether it is an internal or
275 // exported member. An exported member is one whose name is specified in one of
276 // the member type specific properties. An internal member is one that is added
277 // due to being a part of an exported (or other internal) member and is not itself
278 // an exported member.
279 //
280 // Member names are handled as follows:
281 // * When creating the unversioned form of the module the name is left unchecked
282 // unless the member is internal in which case it is transformed into an sdk
283 // specific name, i.e. by prefixing with the sdk name.
284 //
285 // * When creating the versioned form of the module the name is transformed into
286 // a versioned sdk specific name, i.e. by prefixing with the sdk name and
287 // suffixing with the version.
288 //
Paul Duffin7b81f5e2020-01-13 21:03:22 +0000289 // e.g.
Paul Duffin13f02712020-03-06 12:30:43 +0000290 // bpPropertySet.AddPropertyWithTag("libs", []string{"member1", "member2"}, builder.SdkMemberReferencePropertyTag(true))
291 SdkMemberReferencePropertyTag(required bool) BpPropertyTag
Paul Duffin0e0cf1d2019-11-12 19:39:25 +0000292}
293
Paul Duffin5b511a22020-01-15 14:23:52 +0000294type BpPropertyTag interface{}
295
Paul Duffinb645ec82019-11-27 17:43:54 +0000296// A set of properties for use in a .bp file.
297type BpPropertySet interface {
298 // Add a property, the value can be one of the following types:
299 // * string
300 // * array of the above
301 // * bool
Martin Stjernholm191c25f2020-09-10 00:40:37 +0100302 // For these types it is an error if multiple properties with the same name
303 // are added.
304 //
305 // * pointer to a struct
Paul Duffinb645ec82019-11-27 17:43:54 +0000306 // * BpPropertySet
307 //
Martin Stjernholm191c25f2020-09-10 00:40:37 +0100308 // A pointer to a Blueprint-style property struct is first converted into a
309 // BpPropertySet by traversing the fields and adding their values as
310 // properties in a BpPropertySet. A field with a struct value is itself
311 // converted into a BpPropertySet before adding.
312 //
313 // Adding a BpPropertySet is done as follows:
314 // * If no property with the name exists then the BpPropertySet is added
315 // directly to this property. Care must be taken to ensure that it does not
316 // introduce a cycle.
317 // * If a property exists with the name and the current value is a
318 // BpPropertySet then every property of the new BpPropertySet is added to
319 // the existing BpPropertySet.
320 // * Otherwise, if a property exists with the name then it is an error.
Paul Duffinb645ec82019-11-27 17:43:54 +0000321 AddProperty(name string, value interface{})
322
Paul Duffin5b511a22020-01-15 14:23:52 +0000323 // Add a property with an associated tag
324 AddPropertyWithTag(name string, value interface{}, tag BpPropertyTag)
325
Paul Duffinb645ec82019-11-27 17:43:54 +0000326 // Add a property set with the specified name and return so that additional
327 // properties can be added.
328 AddPropertySet(name string) BpPropertySet
Paul Duffin0df49682021-05-07 01:10:01 +0100329
330 // Add comment for property (or property set).
331 AddCommentForProperty(name, text string)
Paul Duffinb645ec82019-11-27 17:43:54 +0000332}
333
334// A .bp module definition.
335type BpModule interface {
336 BpPropertySet
Paul Duffin0df49682021-05-07 01:10:01 +0100337
338 // ModuleType returns the module type of the module
339 ModuleType() string
340
341 // Name returns the name of the module or "" if no name has been specified.
342 Name() string
Paul Duffin0e0cf1d2019-11-12 19:39:25 +0000343}
Paul Duffin13879572019-11-28 14:31:38 +0000344
Paul Duffin51227d82021-05-18 12:54:27 +0100345// BpPrintable is a marker interface that must be implemented by any struct that is added as a
346// property value.
347type BpPrintable interface {
348 bpPrintable()
349}
350
351// BpPrintableBase must be embedded within any struct that is added as a
352// property value.
353type BpPrintableBase struct {
354}
355
356func (b BpPrintableBase) bpPrintable() {
357}
358
359var _ BpPrintable = BpPrintableBase{}
360
Paul Duffin13879572019-11-28 14:31:38 +0000361// An individual member of the SDK, includes all of the variants that the SDK
362// requires.
363type SdkMember interface {
364 // The name of the member.
365 Name() string
366
367 // All the variants required by the SDK.
368 Variants() []SdkAware
369}
370
Paul Duffina7208112021-04-23 21:20:20 +0100371// SdkMemberTypeDependencyTag is the interface that a tag must implement in order to allow the
Paul Duffin2d3da312021-05-06 12:02:27 +0100372// dependent module to be automatically added to the sdk.
Paul Duffinf8539922019-11-19 19:44:10 +0000373type SdkMemberTypeDependencyTag interface {
374 blueprint.DependencyTag
375
Paul Duffina7208112021-04-23 21:20:20 +0100376 // SdkMemberType returns the SdkMemberType that will be used to automatically add the child module
377 // to the sdk.
Paul Duffin5cca7c42021-05-26 10:16:01 +0100378 //
379 // Returning nil will prevent the module being added to the sdk.
Paul Duffineee466e2021-04-27 23:17:56 +0100380 SdkMemberType(child Module) SdkMemberType
Paul Duffina7208112021-04-23 21:20:20 +0100381
382 // ExportMember determines whether a module added to the sdk through this tag will be exported
383 // from the sdk or not.
384 //
385 // An exported member is added to the sdk using its own name, e.g. if "foo" was exported from sdk
386 // "bar" then its prebuilt would be simply called "foo". A member can be added to the sdk via
387 // multiple tags and if any of those tags returns true from this method then the membe will be
388 // exported. Every module added directly to the sdk via one of the member type specific
389 // properties, e.g. java_libs, will automatically be exported.
390 //
391 // If a member is not exported then it is treated as an internal implementation detail of the
392 // sdk and so will be added with an sdk specific name. e.g. if "foo" was an internal member of sdk
393 // "bar" then its prebuilt would be called "bar_foo". Additionally its visibility will be set to
394 // "//visibility:private" so it will not be accessible from outside its Android.bp file.
395 ExportMember() bool
Paul Duffinf8539922019-11-19 19:44:10 +0000396}
397
Paul Duffincee7e662020-07-09 17:32:57 +0100398var _ SdkMemberTypeDependencyTag = (*sdkMemberDependencyTag)(nil)
399var _ ReplaceSourceWithPrebuilt = (*sdkMemberDependencyTag)(nil)
400
Paul Duffinf8539922019-11-19 19:44:10 +0000401type sdkMemberDependencyTag struct {
402 blueprint.BaseDependencyTag
403 memberType SdkMemberType
Paul Duffina7208112021-04-23 21:20:20 +0100404 export bool
Paul Duffinf8539922019-11-19 19:44:10 +0000405}
406
Paul Duffineee466e2021-04-27 23:17:56 +0100407func (t *sdkMemberDependencyTag) SdkMemberType(_ Module) SdkMemberType {
Paul Duffinf8539922019-11-19 19:44:10 +0000408 return t.memberType
409}
410
Paul Duffina7208112021-04-23 21:20:20 +0100411func (t *sdkMemberDependencyTag) ExportMember() bool {
412 return t.export
413}
414
Paul Duffincee7e662020-07-09 17:32:57 +0100415// Prevent dependencies from the sdk/module_exports onto their members from being
416// replaced with a preferred prebuilt.
417func (t *sdkMemberDependencyTag) ReplaceSourceWithPrebuilt() bool {
418 return false
419}
420
Paul Duffina7208112021-04-23 21:20:20 +0100421// DependencyTagForSdkMemberType creates an SdkMemberTypeDependencyTag that will cause any
422// dependencies added by the tag to be added to the sdk as the specified SdkMemberType and exported
423// (or not) as specified by the export parameter.
424func DependencyTagForSdkMemberType(memberType SdkMemberType, export bool) SdkMemberTypeDependencyTag {
425 return &sdkMemberDependencyTag{memberType: memberType, export: export}
Paul Duffinf8539922019-11-19 19:44:10 +0000426}
427
Paul Duffin13879572019-11-28 14:31:38 +0000428// Interface that must be implemented for every type that can be a member of an
429// sdk.
430//
431// The basic implementation should look something like this, where ModuleType is
432// the name of the module type being supported.
433//
Paul Duffin255f18e2019-12-13 11:22:16 +0000434// type moduleTypeSdkMemberType struct {
435// android.SdkMemberTypeBase
Paul Duffin13879572019-11-28 14:31:38 +0000436// }
437//
Paul Duffin255f18e2019-12-13 11:22:16 +0000438// func init() {
439// android.RegisterSdkMemberType(&moduleTypeSdkMemberType{
440// SdkMemberTypeBase: android.SdkMemberTypeBase{
441// PropertyName: "module_types",
442// },
443// }
Paul Duffin13879572019-11-28 14:31:38 +0000444// }
445//
446// ...methods...
447//
448type SdkMemberType interface {
Paul Duffin255f18e2019-12-13 11:22:16 +0000449 // The name of the member type property on an sdk module.
450 SdkPropertyName() string
451
Paul Duffin13082052021-05-11 00:31:38 +0100452 // RequiresBpProperty returns true if this member type requires its property to be usable within
453 // an Android.bp file.
454 RequiresBpProperty() bool
455
Paul Duffine6029182019-12-16 17:43:48 +0000456 // True if the member type supports the sdk/sdk_snapshot, false otherwise.
457 UsableWithSdkAndSdkSnapshot() bool
458
Martin Stjernholmcaa47d72020-07-11 04:52:24 +0100459 // Return true if prebuilt host artifacts may be specific to the host OS. Only
460 // applicable to modules where HostSupported() is true. If this is true,
461 // snapshots will list each host OS variant explicitly and disable all other
462 // host OS'es.
463 IsHostOsDependent() bool
464
Martin Stjernholmcd07bce2020-03-10 22:37:59 +0000465 // Add dependencies from the SDK module to all the module variants the member
466 // type contributes to the SDK. `names` is the list of module names given in
467 // the member type property (as returned by SdkPropertyName()) in the SDK
468 // module. The exact set of variants required is determined by the SDK and its
469 // properties. The dependencies must be added with the supplied tag.
Paul Duffin13879572019-11-28 14:31:38 +0000470 //
471 // The BottomUpMutatorContext provided is for the SDK module.
472 AddDependencies(mctx BottomUpMutatorContext, dependencyTag blueprint.DependencyTag, names []string)
473
474 // Return true if the supplied module is an instance of this member type.
475 //
476 // This is used to check the type of each variant before added to the
477 // SdkMember. Returning false will cause an error to be logged expaining that
478 // the module is not allowed in whichever sdk property it was added.
479 IsInstance(module Module) bool
480
Paul Duffin0d4ed0a2021-05-10 23:58:40 +0100481 // UsesSourceModuleTypeInSnapshot returns true when the AddPrebuiltModule() method returns a
482 // source module type.
483 UsesSourceModuleTypeInSnapshot() bool
484
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000485 // Add a prebuilt module that the sdk will populate.
486 //
Paul Duffin425b0ea2020-05-06 12:41:39 +0100487 // The sdk module code generates the snapshot as follows:
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000488 //
489 // * A properties struct of type SdkMemberProperties is created for each variant and
490 // populated with information from the variant by calling PopulateFromVariant(SdkAware)
491 // on the struct.
492 //
493 // * An additional properties struct is created into which the common properties will be
494 // added.
495 //
496 // * The variant property structs are analysed to find exported (capitalized) fields which
497 // have common values. Those fields are cleared and the common value added to the common
Paul Duffin864e1b42020-05-06 10:23:19 +0100498 // properties.
499 //
500 // A field annotated with a tag of `sdk:"keep"` will be treated as if it
Paul Duffinb07fa512020-03-10 22:17:04 +0000501 // was not capitalized, i.e. not optimized for common values.
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000502 //
Paul Duffin864e1b42020-05-06 10:23:19 +0100503 // A field annotated with a tag of `android:"arch_variant"` will be allowed to have
504 // values that differ by arch, fields not tagged as such must have common values across
505 // all variants.
506 //
Paul Duffinc459f892020-04-30 18:08:29 +0100507 // * Additional field tags can be specified on a field that will ignore certain values
508 // for the purpose of common value optimization. A value that is ignored must have the
509 // default value for the property type. This is to ensure that significant value are not
510 // ignored by accident. The purpose of this is to allow the snapshot generation to reflect
511 // the behavior of the runtime. e.g. if a property is ignored on the host then a property
512 // that is common for android can be treated as if it was common for android and host as
513 // the setting for host is ignored anyway.
514 // * `sdk:"ignored-on-host" - this indicates the property is ignored on the host variant.
515 //
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000516 // * The sdk module type populates the BpModule structure, creating the arch specific
517 // structure and calls AddToPropertySet(...) on the properties struct to add the member
518 // specific properties in the correct place in the structure.
519 //
Paul Duffin3a4eb502020-03-19 16:11:18 +0000520 AddPrebuiltModule(ctx SdkMemberContext, member SdkMember) BpModule
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000521
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000522 // Create a structure into which variant specific properties can be added.
523 CreateVariantPropertiesStruct() SdkMemberProperties
Paul Duffin13879572019-11-28 14:31:38 +0000524}
Paul Duffin255f18e2019-12-13 11:22:16 +0000525
Paul Duffine6029182019-12-16 17:43:48 +0000526// Base type for SdkMemberType implementations.
Paul Duffin255f18e2019-12-13 11:22:16 +0000527type SdkMemberTypeBase struct {
Paul Duffin13082052021-05-11 00:31:38 +0100528 PropertyName string
529
530 // When set to true BpPropertyNotRequired indicates that the member type does not require the
531 // property to be specifiable in an Android.bp file.
532 BpPropertyNotRequired bool
533
Paul Duffin2d3da312021-05-06 12:02:27 +0100534 SupportsSdk bool
535 HostOsDependent bool
Paul Duffin0d4ed0a2021-05-10 23:58:40 +0100536
537 // When set to true UseSourceModuleTypeInSnapshot indicates that the member type creates a source
538 // module type in its SdkMemberType.AddPrebuiltModule() method. That prevents the sdk snapshot
539 // code from automatically adding a prefer: true flag.
540 UseSourceModuleTypeInSnapshot bool
Paul Duffin255f18e2019-12-13 11:22:16 +0000541}
542
543func (b *SdkMemberTypeBase) SdkPropertyName() string {
544 return b.PropertyName
545}
546
Paul Duffin13082052021-05-11 00:31:38 +0100547func (b *SdkMemberTypeBase) RequiresBpProperty() bool {
548 return !b.BpPropertyNotRequired
549}
550
Paul Duffine6029182019-12-16 17:43:48 +0000551func (b *SdkMemberTypeBase) UsableWithSdkAndSdkSnapshot() bool {
552 return b.SupportsSdk
553}
554
Martin Stjernholmcaa47d72020-07-11 04:52:24 +0100555func (b *SdkMemberTypeBase) IsHostOsDependent() bool {
556 return b.HostOsDependent
557}
558
Paul Duffin0d4ed0a2021-05-10 23:58:40 +0100559func (b *SdkMemberTypeBase) UsesSourceModuleTypeInSnapshot() bool {
560 return b.UseSourceModuleTypeInSnapshot
561}
562
Paul Duffin255f18e2019-12-13 11:22:16 +0000563// Encapsulates the information about registered SdkMemberTypes.
564type SdkMemberTypesRegistry struct {
565 // The list of types sorted by property name.
566 list []SdkMemberType
567
568 // The key that uniquely identifies this registry instance.
569 key OnceKey
570}
571
Paul Duffine6029182019-12-16 17:43:48 +0000572func (r *SdkMemberTypesRegistry) copyAndAppend(memberType SdkMemberType) *SdkMemberTypesRegistry {
573 oldList := r.list
Paul Duffin255f18e2019-12-13 11:22:16 +0000574
575 // Copy the slice just in case this is being read while being modified, e.g. when testing.
576 list := make([]SdkMemberType, 0, len(oldList)+1)
577 list = append(list, oldList...)
578 list = append(list, memberType)
579
580 // Sort the member types by their property name to ensure that registry order has no effect
581 // on behavior.
582 sort.Slice(list, func(i1, i2 int) bool {
583 t1 := list[i1]
584 t2 := list[i2]
585
586 return t1.SdkPropertyName() < t2.SdkPropertyName()
587 })
588
589 // Generate a key that identifies the slice of SdkMemberTypes by joining the property names
590 // from all the SdkMemberType .
591 var properties []string
592 for _, t := range list {
593 properties = append(properties, t.SdkPropertyName())
594 }
595 key := NewOnceKey(strings.Join(properties, "|"))
596
597 // Create a new registry so the pointer uniquely identifies the set of registered types.
Paul Duffine6029182019-12-16 17:43:48 +0000598 return &SdkMemberTypesRegistry{
Paul Duffin255f18e2019-12-13 11:22:16 +0000599 list: list,
600 key: key,
601 }
602}
Paul Duffine6029182019-12-16 17:43:48 +0000603
604func (r *SdkMemberTypesRegistry) RegisteredTypes() []SdkMemberType {
605 return r.list
606}
607
608func (r *SdkMemberTypesRegistry) UniqueOnceKey() OnceKey {
609 // Use the pointer to the registry as the unique key.
610 return NewCustomOnceKey(r)
611}
612
613// The set of registered SdkMemberTypes, one for sdk module and one for module_exports.
614var ModuleExportsMemberTypes = &SdkMemberTypesRegistry{}
615var SdkMemberTypes = &SdkMemberTypesRegistry{}
616
617// Register an SdkMemberType object to allow them to be used in the sdk and sdk_snapshot module
618// types.
619func RegisterSdkMemberType(memberType SdkMemberType) {
620 // All member types are usable with module_exports.
621 ModuleExportsMemberTypes = ModuleExportsMemberTypes.copyAndAppend(memberType)
622
623 // Only those that explicitly indicate it are usable with sdk.
624 if memberType.UsableWithSdkAndSdkSnapshot() {
625 SdkMemberTypes = SdkMemberTypes.copyAndAppend(memberType)
626 }
627}
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000628
629// Base structure for all implementations of SdkMemberProperties.
630//
Martin Stjernholm89238f42020-07-10 00:14:03 +0100631// Contains common properties that apply across many different member types.
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000632type SdkMemberPropertiesBase struct {
Paul Duffina04c1072020-03-02 10:16:35 +0000633 // The number of unique os types supported by the member variants.
Paul Duffina551a1c2020-03-17 21:04:24 +0000634 //
635 // If a member has a variant with more than one os type then it will need to differentiate
636 // the locations of any of their prebuilt files in the snapshot by os type to prevent them
637 // from colliding. See OsPrefix().
638 //
639 // This property is the same for all variants of a member and so would be optimized away
640 // if it was not explicitly kept.
Paul Duffinb07fa512020-03-10 22:17:04 +0000641 Os_count int `sdk:"keep"`
Paul Duffina04c1072020-03-02 10:16:35 +0000642
643 // The os type for which these properties refer.
Paul Duffina551a1c2020-03-17 21:04:24 +0000644 //
645 // Provided to allow a member to differentiate between os types in the locations of their
646 // prebuilt files when it supports more than one os type.
647 //
648 // This property is the same for all os type specific variants of a member and so would be
649 // optimized away if it was not explicitly kept.
Paul Duffinb07fa512020-03-10 22:17:04 +0000650 Os OsType `sdk:"keep"`
Paul Duffina551a1c2020-03-17 21:04:24 +0000651
652 // The setting to use for the compile_multilib property.
Martin Stjernholm89238f42020-07-10 00:14:03 +0100653 Compile_multilib string `android:"arch_variant"`
Paul Duffina04c1072020-03-02 10:16:35 +0000654}
655
656// The os prefix to use for any file paths in the sdk.
657//
658// Is an empty string if the member only provides variants for a single os type, otherwise
659// is the OsType.Name.
660func (b *SdkMemberPropertiesBase) OsPrefix() string {
661 if b.Os_count == 1 {
662 return ""
663 } else {
664 return b.Os.Name
665 }
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000666}
667
668func (b *SdkMemberPropertiesBase) Base() *SdkMemberPropertiesBase {
669 return b
670}
671
672// Interface to be implemented on top of a structure that contains variant specific
673// information.
674//
675// Struct fields that are capitalized are examined for common values to extract. Fields
676// that are not capitalized are assumed to be arch specific.
677type SdkMemberProperties interface {
678 // Access the base structure.
679 Base() *SdkMemberPropertiesBase
680
Paul Duffin3a4eb502020-03-19 16:11:18 +0000681 // Populate this structure with information from the variant.
682 PopulateFromVariant(ctx SdkMemberContext, variant Module)
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000683
Paul Duffin3a4eb502020-03-19 16:11:18 +0000684 // Add the information from this structure to the property set.
685 AddToPropertySet(ctx SdkMemberContext, propertySet BpPropertySet)
686}
687
688// Provides access to information common to a specific member.
689type SdkMemberContext interface {
690
691 // The module context of the sdk common os variant which is creating the snapshot.
692 SdkModuleContext() ModuleContext
693
694 // The builder of the snapshot.
695 SnapshotBuilder() SnapshotBuilder
Paul Duffina551a1c2020-03-17 21:04:24 +0000696
697 // The type of the member.
698 MemberType() SdkMemberType
699
700 // The name of the member.
701 //
702 // Provided for use by sdk members to create a member specific location within the snapshot
703 // into which to copy the prebuilt files.
704 Name() string
Paul Duffin88f2fbe2020-02-27 16:00:53 +0000705}
Paul Duffinb97b1572021-04-29 21:50:40 +0100706
707// ExportedComponentsInfo contains information about the components that this module exports to an
708// sdk snapshot.
709//
710// A component of a module is a child module that the module creates and which forms an integral
711// part of the functionality that the creating module provides. A component module is essentially
712// owned by its creator and is tightly coupled to the creator and other components.
713//
714// e.g. the child modules created by prebuilt_apis are not components because they are not tightly
715// coupled to the prebuilt_apis module. Once they are created the prebuilt_apis ignores them. The
716// child impl and stub library created by java_sdk_library (and corresponding import) are components
717// because the creating module depends upon them in order to provide some of its own functionality.
718//
719// A component is exported if it is part of an sdk snapshot. e.g. The xml and impl child modules are
720// components but they are not exported as they are not part of an sdk snapshot.
721//
722// This information is used by the sdk snapshot generation code to ensure that it does not create
723// an sdk snapshot that contains a declaration of the component module and the module that creates
724// it as that would result in duplicate modules when attempting to use the snapshot. e.g. a snapshot
725// that included the java_sdk_library_import "foo" and also a java_import "foo.stubs" would fail
726// as there would be two modules called "foo.stubs".
727type ExportedComponentsInfo struct {
728 // The names of the exported components.
729 Components []string
730}
731
732var ExportedComponentsInfoProvider = blueprint.NewProvider(ExportedComponentsInfo{})