sdk.go 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870
  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. package android
  15. import (
  16. "fmt"
  17. "sort"
  18. "strings"
  19. "github.com/google/blueprint"
  20. "github.com/google/blueprint/proptools"
  21. )
  22. // minApiLevelForSdkSnapshot provides access to the min_sdk_version for MinApiLevelForSdkSnapshot
  23. type minApiLevelForSdkSnapshot interface {
  24. MinSdkVersion(ctx EarlyModuleContext) ApiLevel
  25. }
  26. // MinApiLevelForSdkSnapshot returns the ApiLevel of the min_sdk_version of the supplied module.
  27. //
  28. // If the module does not provide a min_sdk_version then it defaults to 1.
  29. func MinApiLevelForSdkSnapshot(ctx EarlyModuleContext, module Module) ApiLevel {
  30. minApiLevel := NoneApiLevel
  31. if m, ok := module.(minApiLevelForSdkSnapshot); ok {
  32. minApiLevel = m.MinSdkVersion(ctx)
  33. }
  34. if minApiLevel == NoneApiLevel {
  35. // The default min API level is 1.
  36. minApiLevel = uncheckedFinalApiLevel(1)
  37. }
  38. return minApiLevel
  39. }
  40. // SnapshotBuilder provides support for generating the build rules which will build the snapshot.
  41. type SnapshotBuilder interface {
  42. // CopyToSnapshot generates a rule that will copy the src to the dest (which is a snapshot
  43. // relative path) and add the dest to the zip.
  44. CopyToSnapshot(src Path, dest string)
  45. // EmptyFile returns the path to an empty file.
  46. //
  47. // This can be used by sdk member types that need to create an empty file in the snapshot, simply
  48. // pass the value returned from this to the CopyToSnapshot() method.
  49. EmptyFile() Path
  50. // UnzipToSnapshot generates a rule that will unzip the supplied zip into the snapshot relative
  51. // directory destDir.
  52. UnzipToSnapshot(zipPath Path, destDir string)
  53. // AddPrebuiltModule adds a new prebuilt module to the snapshot.
  54. //
  55. // It is intended to be called from SdkMemberType.AddPrebuiltModule which can add module type
  56. // specific properties that are not variant specific. The following properties will be
  57. // automatically populated before returning.
  58. //
  59. // * name
  60. // * sdk_member_name
  61. // * prefer
  62. //
  63. // Properties that are variant specific will be handled by SdkMemberProperties structure.
  64. //
  65. // Each module created by this method can be output to the generated Android.bp file in two
  66. // different forms, depending on the setting of the SOONG_SDK_SNAPSHOT_VERSION build property.
  67. // The two forms are:
  68. // 1. A versioned Soong module that is referenced from a corresponding similarly versioned
  69. // snapshot module.
  70. // 2. An unversioned Soong module that.
  71. //
  72. // See sdk/update.go for more information.
  73. AddPrebuiltModule(member SdkMember, moduleType string) BpModule
  74. // SdkMemberReferencePropertyTag returns a property tag to use when adding a property to a
  75. // BpModule that contains references to other sdk members.
  76. //
  77. // Using this will ensure that the reference is correctly output for both versioned and
  78. // unversioned prebuilts in the snapshot.
  79. //
  80. // "required: true" means that the property must only contain references to other members of the
  81. // sdk. Passing a reference to a module that is not a member of the sdk will result in a build
  82. // error.
  83. //
  84. // "required: false" means that the property can contain references to modules that are either
  85. // members or not members of the sdk. If a reference is to a module that is a non member then the
  86. // reference is left unchanged, i.e. it is not transformed as references to members are.
  87. //
  88. // The handling of the member names is dependent on whether it is an internal or exported member.
  89. // An exported member is one whose name is specified in one of the member type specific
  90. // properties. An internal member is one that is added due to being a part of an exported (or
  91. // other internal) member and is not itself an exported member.
  92. //
  93. // Member names are handled as follows:
  94. // * When creating the unversioned form of the module the name is left unchecked unless the member
  95. // is internal in which case it is transformed into an sdk specific name, i.e. by prefixing with
  96. // the sdk name.
  97. //
  98. // * When creating the versioned form of the module the name is transformed into a versioned sdk
  99. // specific name, i.e. by prefixing with the sdk name and suffixing with the version.
  100. //
  101. // e.g.
  102. // bpPropertySet.AddPropertyWithTag("libs", []string{"member1", "member2"}, builder.SdkMemberReferencePropertyTag(true))
  103. SdkMemberReferencePropertyTag(required bool) BpPropertyTag
  104. }
  105. // BpPropertyTag is a marker interface that can be associated with properties in a BpPropertySet to
  106. // provide additional information which can be used to customize their behavior.
  107. type BpPropertyTag interface{}
  108. // BpPropertySet is a set of properties for use in a .bp file.
  109. type BpPropertySet interface {
  110. // AddProperty adds a property.
  111. //
  112. // The value can be one of the following types:
  113. // * string
  114. // * array of the above
  115. // * bool
  116. // For these types it is an error if multiple properties with the same name
  117. // are added.
  118. //
  119. // * pointer to a struct
  120. // * BpPropertySet
  121. //
  122. // A pointer to a Blueprint-style property struct is first converted into a
  123. // BpPropertySet by traversing the fields and adding their values as
  124. // properties in a BpPropertySet. A field with a struct value is itself
  125. // converted into a BpPropertySet before adding.
  126. //
  127. // Adding a BpPropertySet is done as follows:
  128. // * If no property with the name exists then the BpPropertySet is added
  129. // directly to this property. Care must be taken to ensure that it does not
  130. // introduce a cycle.
  131. // * If a property exists with the name and the current value is a
  132. // BpPropertySet then every property of the new BpPropertySet is added to
  133. // the existing BpPropertySet.
  134. // * Otherwise, if a property exists with the name then it is an error.
  135. AddProperty(name string, value interface{})
  136. // AddPropertyWithTag adds a property with an associated property tag.
  137. AddPropertyWithTag(name string, value interface{}, tag BpPropertyTag)
  138. // AddPropertySet adds a property set with the specified name and returns it so that additional
  139. // properties can be added to it.
  140. AddPropertySet(name string) BpPropertySet
  141. // AddCommentForProperty adds a comment for the named property (or property set).
  142. AddCommentForProperty(name, text string)
  143. }
  144. // BpModule represents a module definition in a .bp file.
  145. type BpModule interface {
  146. BpPropertySet
  147. // ModuleType returns the module type of the module
  148. ModuleType() string
  149. // Name returns the name of the module or "" if no name has been specified.
  150. Name() string
  151. }
  152. // BpPrintable is a marker interface that must be implemented by any struct that is added as a
  153. // property value.
  154. type BpPrintable interface {
  155. bpPrintable()
  156. }
  157. // BpPrintableBase must be embedded within any struct that is added as a
  158. // property value.
  159. type BpPrintableBase struct {
  160. }
  161. func (b BpPrintableBase) bpPrintable() {
  162. }
  163. var _ BpPrintable = BpPrintableBase{}
  164. // sdkRegisterable defines the interface that must be implemented by objects that can be registered
  165. // in an sdkRegistry.
  166. type sdkRegisterable interface {
  167. // SdkPropertyName returns the name of the corresponding property on an sdk module.
  168. SdkPropertyName() string
  169. }
  170. // sdkRegistry provides support for registering and retrieving objects that define properties for
  171. // use by sdk and module_exports module types.
  172. type sdkRegistry struct {
  173. // The list of registered objects sorted by property name.
  174. list []sdkRegisterable
  175. }
  176. // copyAndAppend creates a new sdkRegistry that includes all the traits registered in
  177. // this registry plus the supplied trait.
  178. func (r *sdkRegistry) copyAndAppend(registerable sdkRegisterable) *sdkRegistry {
  179. oldList := r.list
  180. // Make sure that list does not already contain the property. Uses a simple linear search instead
  181. // of a binary search even though the list is sorted. That is because the number of items in the
  182. // list is small and so not worth the overhead of a binary search.
  183. found := false
  184. newPropertyName := registerable.SdkPropertyName()
  185. for _, r := range oldList {
  186. if r.SdkPropertyName() == newPropertyName {
  187. found = true
  188. break
  189. }
  190. }
  191. if found {
  192. names := []string{}
  193. for _, r := range oldList {
  194. names = append(names, r.SdkPropertyName())
  195. }
  196. panic(fmt.Errorf("duplicate properties found, %q already exists in %q", newPropertyName, names))
  197. }
  198. // Copy the slice just in case this is being read while being modified, e.g. when testing.
  199. list := make([]sdkRegisterable, 0, len(oldList)+1)
  200. list = append(list, oldList...)
  201. list = append(list, registerable)
  202. // Sort the registered objects by their property name to ensure that registry order has no effect
  203. // on behavior.
  204. sort.Slice(list, func(i1, i2 int) bool {
  205. t1 := list[i1]
  206. t2 := list[i2]
  207. return t1.SdkPropertyName() < t2.SdkPropertyName()
  208. })
  209. // Create a new registry so the pointer uniquely identifies the set of registered types.
  210. return &sdkRegistry{
  211. list: list,
  212. }
  213. }
  214. // registeredObjects returns the list of registered instances.
  215. func (r *sdkRegistry) registeredObjects() []sdkRegisterable {
  216. return r.list
  217. }
  218. // uniqueOnceKey returns a key that uniquely identifies this instance and can be used with
  219. // OncePer.Once
  220. func (r *sdkRegistry) uniqueOnceKey() OnceKey {
  221. // Use the pointer to the registry as the unique key. The pointer is used because it is guaranteed
  222. // to uniquely identify the contained list. The list itself cannot be used as slices are not
  223. // comparable. Using the pointer does mean that two separate registries with identical lists would
  224. // have different keys and so cause whatever information is cached to be created multiple times.
  225. // However, that is not an issue in practice as it should not occur outside tests. Constructing a
  226. // string representation of the list to use instead would avoid that but is an unnecessary
  227. // complication that provides no significant benefit.
  228. return NewCustomOnceKey(r)
  229. }
  230. // SdkMemberTrait represents a trait that members of an sdk module can contribute to the sdk
  231. // snapshot.
  232. //
  233. // A trait is simply a characteristic of sdk member that is not required by default which may be
  234. // required for some members but not others. Traits can cause additional information to be output
  235. // to the sdk snapshot or replace the default information exported for a member with something else.
  236. // e.g.
  237. // - By default cc libraries only export the default image variants to the SDK. However, for some
  238. // members it may be necessary to export specific image variants, e.g. vendor, or recovery.
  239. // - By default cc libraries export all the configured architecture variants except for the native
  240. // bridge architecture variants. However, for some members it may be necessary to export the
  241. // native bridge architecture variants as well.
  242. // - By default cc libraries export the platform variant (i.e. sdk:). However, for some members it
  243. // may be necessary to export the sdk variant (i.e. sdk:sdk).
  244. //
  245. // A sdk can request a module to provide no traits, one trait or a collection of traits. The exact
  246. // behavior of a trait is determined by how SdkMemberType implementations handle the traits. A trait
  247. // could be specific to one SdkMemberType or many. Some trait combinations could be incompatible.
  248. //
  249. // The sdk module type will create a special traits structure that contains a property for each
  250. // trait registered with RegisterSdkMemberTrait(). The property names are those returned from
  251. // SdkPropertyName(). Each property contains a list of modules that are required to have that trait.
  252. // e.g. something like this:
  253. //
  254. // sdk {
  255. // name: "sdk",
  256. // ...
  257. // traits: {
  258. // recovery_image: ["module1", "module4", "module5"],
  259. // native_bridge: ["module1", "module2"],
  260. // native_sdk: ["module1", "module3"],
  261. // ...
  262. // },
  263. // ...
  264. // }
  265. type SdkMemberTrait interface {
  266. // SdkPropertyName returns the name of the traits property on an sdk module.
  267. SdkPropertyName() string
  268. }
  269. var _ sdkRegisterable = (SdkMemberTrait)(nil)
  270. // SdkMemberTraitBase is the base struct that must be embedded within any type that implements
  271. // SdkMemberTrait.
  272. type SdkMemberTraitBase struct {
  273. // PropertyName is the name of the property
  274. PropertyName string
  275. }
  276. func (b *SdkMemberTraitBase) SdkPropertyName() string {
  277. return b.PropertyName
  278. }
  279. // SdkMemberTraitSet is a set of SdkMemberTrait instances.
  280. type SdkMemberTraitSet interface {
  281. // Empty returns true if this set is empty.
  282. Empty() bool
  283. // Contains returns true if this set contains the specified trait.
  284. Contains(trait SdkMemberTrait) bool
  285. // Subtract returns a new set containing all elements of this set except for those in the
  286. // other set.
  287. Subtract(other SdkMemberTraitSet) SdkMemberTraitSet
  288. // String returns a string representation of the set and its contents.
  289. String() string
  290. }
  291. func NewSdkMemberTraitSet(traits []SdkMemberTrait) SdkMemberTraitSet {
  292. if len(traits) == 0 {
  293. return EmptySdkMemberTraitSet()
  294. }
  295. m := sdkMemberTraitSet{}
  296. for _, trait := range traits {
  297. m[trait] = true
  298. }
  299. return m
  300. }
  301. func EmptySdkMemberTraitSet() SdkMemberTraitSet {
  302. return (sdkMemberTraitSet)(nil)
  303. }
  304. type sdkMemberTraitSet map[SdkMemberTrait]bool
  305. var _ SdkMemberTraitSet = (sdkMemberTraitSet{})
  306. func (s sdkMemberTraitSet) Empty() bool {
  307. return len(s) == 0
  308. }
  309. func (s sdkMemberTraitSet) Contains(trait SdkMemberTrait) bool {
  310. return s[trait]
  311. }
  312. func (s sdkMemberTraitSet) Subtract(other SdkMemberTraitSet) SdkMemberTraitSet {
  313. if other.Empty() {
  314. return s
  315. }
  316. var remainder []SdkMemberTrait
  317. for trait, _ := range s {
  318. if !other.Contains(trait) {
  319. remainder = append(remainder, trait)
  320. }
  321. }
  322. return NewSdkMemberTraitSet(remainder)
  323. }
  324. func (s sdkMemberTraitSet) String() string {
  325. list := []string{}
  326. for trait, _ := range s {
  327. list = append(list, trait.SdkPropertyName())
  328. }
  329. sort.Strings(list)
  330. return fmt.Sprintf("[%s]", strings.Join(list, ","))
  331. }
  332. var registeredSdkMemberTraits = &sdkRegistry{}
  333. // RegisteredSdkMemberTraits returns a OnceKey and a sorted list of registered traits.
  334. //
  335. // The key uniquely identifies the array of traits and can be used with OncePer.Once() to cache
  336. // information derived from the array of traits.
  337. func RegisteredSdkMemberTraits() (OnceKey, []SdkMemberTrait) {
  338. registerables := registeredSdkMemberTraits.registeredObjects()
  339. traits := make([]SdkMemberTrait, len(registerables))
  340. for i, registerable := range registerables {
  341. traits[i] = registerable.(SdkMemberTrait)
  342. }
  343. return registeredSdkMemberTraits.uniqueOnceKey(), traits
  344. }
  345. // RegisterSdkMemberTrait registers an SdkMemberTrait object to allow them to be used in the
  346. // module_exports, module_exports_snapshot, sdk and sdk_snapshot module types.
  347. func RegisterSdkMemberTrait(trait SdkMemberTrait) {
  348. registeredSdkMemberTraits = registeredSdkMemberTraits.copyAndAppend(trait)
  349. }
  350. // SdkMember is an individual member of the SDK.
  351. //
  352. // It includes all of the variants that the SDK depends upon.
  353. type SdkMember interface {
  354. // Name returns the name of the member.
  355. Name() string
  356. // Variants returns all the variants of this module depended upon by the SDK.
  357. Variants() []Module
  358. }
  359. // SdkMemberDependencyTag is the interface that a tag must implement in order to allow the
  360. // dependent module to be automatically added to the sdk.
  361. type SdkMemberDependencyTag interface {
  362. blueprint.DependencyTag
  363. // SdkMemberType returns the SdkMemberType that will be used to automatically add the child module
  364. // to the sdk.
  365. //
  366. // Returning nil will prevent the module being added to the sdk.
  367. SdkMemberType(child Module) SdkMemberType
  368. // ExportMember determines whether a module added to the sdk through this tag will be exported
  369. // from the sdk or not.
  370. //
  371. // An exported member is added to the sdk using its own name, e.g. if "foo" was exported from sdk
  372. // "bar" then its prebuilt would be simply called "foo". A member can be added to the sdk via
  373. // multiple tags and if any of those tags returns true from this method then the membe will be
  374. // exported. Every module added directly to the sdk via one of the member type specific
  375. // properties, e.g. java_libs, will automatically be exported.
  376. //
  377. // If a member is not exported then it is treated as an internal implementation detail of the
  378. // sdk and so will be added with an sdk specific name. e.g. if "foo" was an internal member of sdk
  379. // "bar" then its prebuilt would be called "bar_foo". Additionally its visibility will be set to
  380. // "//visibility:private" so it will not be accessible from outside its Android.bp file.
  381. ExportMember() bool
  382. }
  383. var _ SdkMemberDependencyTag = (*sdkMemberDependencyTag)(nil)
  384. var _ ReplaceSourceWithPrebuilt = (*sdkMemberDependencyTag)(nil)
  385. type sdkMemberDependencyTag struct {
  386. blueprint.BaseDependencyTag
  387. memberType SdkMemberType
  388. export bool
  389. }
  390. func (t *sdkMemberDependencyTag) SdkMemberType(_ Module) SdkMemberType {
  391. return t.memberType
  392. }
  393. func (t *sdkMemberDependencyTag) ExportMember() bool {
  394. return t.export
  395. }
  396. // ReplaceSourceWithPrebuilt prevents dependencies from the sdk/module_exports onto their members
  397. // from being replaced with a preferred prebuilt.
  398. func (t *sdkMemberDependencyTag) ReplaceSourceWithPrebuilt() bool {
  399. return false
  400. }
  401. // DependencyTagForSdkMemberType creates an SdkMemberDependencyTag that will cause any
  402. // dependencies added by the tag to be added to the sdk as the specified SdkMemberType and exported
  403. // (or not) as specified by the export parameter.
  404. func DependencyTagForSdkMemberType(memberType SdkMemberType, export bool) SdkMemberDependencyTag {
  405. return &sdkMemberDependencyTag{memberType: memberType, export: export}
  406. }
  407. // SdkMemberType is the interface that must be implemented for every type that can be a member of an
  408. // sdk.
  409. //
  410. // The basic implementation should look something like this, where ModuleType is
  411. // the name of the module type being supported.
  412. //
  413. // type moduleTypeSdkMemberType struct {
  414. // android.SdkMemberTypeBase
  415. // }
  416. //
  417. // func init() {
  418. // android.RegisterSdkMemberType(&moduleTypeSdkMemberType{
  419. // SdkMemberTypeBase: android.SdkMemberTypeBase{
  420. // PropertyName: "module_types",
  421. // },
  422. // }
  423. // }
  424. //
  425. // ...methods...
  426. type SdkMemberType interface {
  427. // SdkPropertyName returns the name of the member type property on an sdk module.
  428. SdkPropertyName() string
  429. // RequiresBpProperty returns true if this member type requires its property to be usable within
  430. // an Android.bp file.
  431. RequiresBpProperty() bool
  432. // SupportedBuildReleases returns the string representation of a set of target build releases that
  433. // support this member type.
  434. SupportedBuildReleases() string
  435. // UsableWithSdkAndSdkSnapshot returns true if the member type supports the sdk/sdk_snapshot,
  436. // false otherwise.
  437. UsableWithSdkAndSdkSnapshot() bool
  438. // IsHostOsDependent returns true if prebuilt host artifacts may be specific to the host OS. Only
  439. // applicable to modules where HostSupported() is true. If this is true, snapshots will list each
  440. // host OS variant explicitly and disable all other host OS'es.
  441. IsHostOsDependent() bool
  442. // SupportedLinkages returns the names of the linkage variants supported by this module.
  443. SupportedLinkages() []string
  444. // ArePrebuiltsRequired returns true if prebuilts are required in the sdk snapshot, false
  445. // otherwise.
  446. ArePrebuiltsRequired() bool
  447. // AddDependencies adds dependencies from the SDK module to all the module variants the member
  448. // type contributes to the SDK. `names` is the list of module names given in the member type
  449. // property (as returned by SdkPropertyName()) in the SDK module. The exact set of variants
  450. // required is determined by the SDK and its properties. The dependencies must be added with the
  451. // supplied tag.
  452. //
  453. // The BottomUpMutatorContext provided is for the SDK module.
  454. AddDependencies(ctx SdkDependencyContext, dependencyTag blueprint.DependencyTag, names []string)
  455. // IsInstance returns true if the supplied module is an instance of this member type.
  456. //
  457. // This is used to check the type of each variant before added to the SdkMember. Returning false
  458. // will cause an error to be logged explaining that the module is not allowed in whichever sdk
  459. // property it was added.
  460. IsInstance(module Module) bool
  461. // UsesSourceModuleTypeInSnapshot returns true when the AddPrebuiltModule() method returns a
  462. // source module type.
  463. UsesSourceModuleTypeInSnapshot() bool
  464. // AddPrebuiltModule is called to add a prebuilt module that the sdk will populate.
  465. //
  466. // The sdk module code generates the snapshot as follows:
  467. //
  468. // * A properties struct of type SdkMemberProperties is created for each variant and
  469. // populated with information from the variant by calling PopulateFromVariant(Module)
  470. // on the struct.
  471. //
  472. // * An additional properties struct is created into which the common properties will be
  473. // added.
  474. //
  475. // * The variant property structs are analysed to find exported (capitalized) fields which
  476. // have common values. Those fields are cleared and the common value added to the common
  477. // properties.
  478. //
  479. // A field annotated with a tag of `sdk:"ignore"` will be treated as if it
  480. // was not capitalized, i.e. ignored and not optimized for common values.
  481. //
  482. // A field annotated with a tag of `sdk:"keep"` will not be cleared even if the value is common
  483. // across multiple structs. Common values will still be copied into the common property struct.
  484. // So, if the same value is placed in all structs populated from variants that value would be
  485. // copied into all common property structs and so be available in every instance.
  486. //
  487. // A field annotated with a tag of `android:"arch_variant"` will be allowed to have
  488. // values that differ by arch, fields not tagged as such must have common values across
  489. // all variants.
  490. //
  491. // * Additional field tags can be specified on a field that will ignore certain values
  492. // for the purpose of common value optimization. A value that is ignored must have the
  493. // default value for the property type. This is to ensure that significant value are not
  494. // ignored by accident. The purpose of this is to allow the snapshot generation to reflect
  495. // the behavior of the runtime. e.g. if a property is ignored on the host then a property
  496. // that is common for android can be treated as if it was common for android and host as
  497. // the setting for host is ignored anyway.
  498. // * `sdk:"ignored-on-host" - this indicates the property is ignored on the host variant.
  499. //
  500. // * The sdk module type populates the BpModule structure, creating the arch specific
  501. // structure and calls AddToPropertySet(...) on the properties struct to add the member
  502. // specific properties in the correct place in the structure.
  503. //
  504. AddPrebuiltModule(ctx SdkMemberContext, member SdkMember) BpModule
  505. // CreateVariantPropertiesStruct creates a structure into which variant specific properties can be
  506. // added.
  507. CreateVariantPropertiesStruct() SdkMemberProperties
  508. // SupportedTraits returns the set of traits supported by this member type.
  509. SupportedTraits() SdkMemberTraitSet
  510. // Overrides returns whether type overrides other SdkMemberType
  511. Overrides(SdkMemberType) bool
  512. }
  513. var _ sdkRegisterable = (SdkMemberType)(nil)
  514. // SdkDependencyContext provides access to information needed by the SdkMemberType.AddDependencies()
  515. // implementations.
  516. type SdkDependencyContext interface {
  517. BottomUpMutatorContext
  518. // RequiredTraits returns the set of SdkMemberTrait instances that the sdk requires the named
  519. // member to provide.
  520. RequiredTraits(name string) SdkMemberTraitSet
  521. // RequiresTrait returns true if the sdk requires the member with the supplied name to provide the
  522. // supplied trait.
  523. RequiresTrait(name string, trait SdkMemberTrait) bool
  524. }
  525. // SdkMemberTypeBase is the base type for SdkMemberType implementations and must be embedded in any
  526. // struct that implements SdkMemberType.
  527. type SdkMemberTypeBase struct {
  528. PropertyName string
  529. // Property names that this SdkMemberTypeBase can override, this is useful when a module type is a
  530. // superset of another module type.
  531. OverridesPropertyNames map[string]bool
  532. // The names of linkage variants supported by this module.
  533. SupportedLinkageNames []string
  534. // When set to true BpPropertyNotRequired indicates that the member type does not require the
  535. // property to be specifiable in an Android.bp file.
  536. BpPropertyNotRequired bool
  537. // The name of the first targeted build release.
  538. //
  539. // If not specified then it is assumed to be available on all targeted build releases.
  540. SupportedBuildReleaseSpecification string
  541. // Set to true if this must be usable with the sdk/sdk_snapshot module types. Otherwise, it will
  542. // only be usable with module_exports/module_exports_snapshots module types.
  543. SupportsSdk bool
  544. // Set to true if prebuilt host artifacts of this member may be specific to the host OS. Only
  545. // applicable to modules where HostSupported() is true.
  546. HostOsDependent bool
  547. // When set to true UseSourceModuleTypeInSnapshot indicates that the member type creates a source
  548. // module type in its SdkMemberType.AddPrebuiltModule() method. That prevents the sdk snapshot
  549. // code from automatically adding a prefer: true flag.
  550. UseSourceModuleTypeInSnapshot bool
  551. // Set to proptools.BoolPtr(false) if this member does not generate prebuilts but is only provided
  552. // to allow the sdk to gather members from this member's dependencies. If not specified then
  553. // defaults to true.
  554. PrebuiltsRequired *bool
  555. // The list of supported traits.
  556. Traits []SdkMemberTrait
  557. }
  558. func (b *SdkMemberTypeBase) SdkPropertyName() string {
  559. return b.PropertyName
  560. }
  561. func (b *SdkMemberTypeBase) RequiresBpProperty() bool {
  562. return !b.BpPropertyNotRequired
  563. }
  564. func (b *SdkMemberTypeBase) SupportedBuildReleases() string {
  565. return b.SupportedBuildReleaseSpecification
  566. }
  567. func (b *SdkMemberTypeBase) UsableWithSdkAndSdkSnapshot() bool {
  568. return b.SupportsSdk
  569. }
  570. func (b *SdkMemberTypeBase) IsHostOsDependent() bool {
  571. return b.HostOsDependent
  572. }
  573. func (b *SdkMemberTypeBase) ArePrebuiltsRequired() bool {
  574. return proptools.BoolDefault(b.PrebuiltsRequired, true)
  575. }
  576. func (b *SdkMemberTypeBase) UsesSourceModuleTypeInSnapshot() bool {
  577. return b.UseSourceModuleTypeInSnapshot
  578. }
  579. func (b *SdkMemberTypeBase) SupportedTraits() SdkMemberTraitSet {
  580. return NewSdkMemberTraitSet(b.Traits)
  581. }
  582. func (b *SdkMemberTypeBase) Overrides(other SdkMemberType) bool {
  583. return b.OverridesPropertyNames[other.SdkPropertyName()]
  584. }
  585. func (b *SdkMemberTypeBase) SupportedLinkages() []string {
  586. return b.SupportedLinkageNames
  587. }
  588. // registeredModuleExportsMemberTypes is the set of registered SdkMemberTypes for module_exports
  589. // modules.
  590. var registeredModuleExportsMemberTypes = &sdkRegistry{}
  591. // registeredSdkMemberTypes is the set of registered registeredSdkMemberTypes for sdk modules.
  592. var registeredSdkMemberTypes = &sdkRegistry{}
  593. // RegisteredSdkMemberTypes returns a OnceKey and a sorted list of registered types.
  594. //
  595. // If moduleExports is true then the slice of types includes all registered types that can be used
  596. // with the module_exports and module_exports_snapshot module types. Otherwise, the slice of types
  597. // only includes those registered types that can be used with the sdk and sdk_snapshot module
  598. // types.
  599. //
  600. // The key uniquely identifies the array of types and can be used with OncePer.Once() to cache
  601. // information derived from the array of types.
  602. func RegisteredSdkMemberTypes(moduleExports bool) (OnceKey, []SdkMemberType) {
  603. var registry *sdkRegistry
  604. if moduleExports {
  605. registry = registeredModuleExportsMemberTypes
  606. } else {
  607. registry = registeredSdkMemberTypes
  608. }
  609. registerables := registry.registeredObjects()
  610. types := make([]SdkMemberType, len(registerables))
  611. for i, registerable := range registerables {
  612. types[i] = registerable.(SdkMemberType)
  613. }
  614. return registry.uniqueOnceKey(), types
  615. }
  616. // RegisterSdkMemberType registers an SdkMemberType object to allow them to be used in the
  617. // module_exports, module_exports_snapshot and (depending on the value returned from
  618. // SdkMemberType.UsableWithSdkAndSdkSnapshot) the sdk and sdk_snapshot module types.
  619. func RegisterSdkMemberType(memberType SdkMemberType) {
  620. // All member types are usable with module_exports.
  621. registeredModuleExportsMemberTypes = registeredModuleExportsMemberTypes.copyAndAppend(memberType)
  622. // Only those that explicitly indicate it are usable with sdk.
  623. if memberType.UsableWithSdkAndSdkSnapshot() {
  624. registeredSdkMemberTypes = registeredSdkMemberTypes.copyAndAppend(memberType)
  625. }
  626. }
  627. // SdkMemberPropertiesBase is the base structure for all implementations of SdkMemberProperties and
  628. // must be embedded in any struct that implements SdkMemberProperties.
  629. //
  630. // Contains common properties that apply across many different member types.
  631. type SdkMemberPropertiesBase struct {
  632. // The number of unique os types supported by the member variants.
  633. //
  634. // If a member has a variant with more than one os type then it will need to differentiate
  635. // the locations of any of their prebuilt files in the snapshot by os type to prevent them
  636. // from colliding. See OsPrefix().
  637. //
  638. // Ignore this property during optimization. This is needed because this property is the same for
  639. // all variants of a member and so would be optimized away if it was not ignored.
  640. Os_count int `sdk:"ignore"`
  641. // The os type for which these properties refer.
  642. //
  643. // Provided to allow a member to differentiate between os types in the locations of their
  644. // prebuilt files when it supports more than one os type.
  645. //
  646. // Ignore this property during optimization. This is needed because this property is the same for
  647. // all variants of a member and so would be optimized away if it was not ignored.
  648. Os OsType `sdk:"ignore"`
  649. // The setting to use for the compile_multilib property.
  650. Compile_multilib string `android:"arch_variant"`
  651. }
  652. // OsPrefix returns the os prefix to use for any file paths in the sdk.
  653. //
  654. // Is an empty string if the member only provides variants for a single os type, otherwise
  655. // is the OsType.Name.
  656. func (b *SdkMemberPropertiesBase) OsPrefix() string {
  657. if b.Os_count == 1 {
  658. return ""
  659. } else {
  660. return b.Os.Name
  661. }
  662. }
  663. func (b *SdkMemberPropertiesBase) Base() *SdkMemberPropertiesBase {
  664. return b
  665. }
  666. // SdkMemberProperties is the interface to be implemented on top of a structure that contains
  667. // variant specific information.
  668. //
  669. // Struct fields that are capitalized are examined for common values to extract. Fields that are not
  670. // capitalized are assumed to be arch specific.
  671. type SdkMemberProperties interface {
  672. // Base returns the base structure.
  673. Base() *SdkMemberPropertiesBase
  674. // PopulateFromVariant populates this structure with information from a module variant.
  675. //
  676. // It will typically be called once for each variant of a member module that the SDK depends upon.
  677. PopulateFromVariant(ctx SdkMemberContext, variant Module)
  678. // AddToPropertySet adds the information from this structure to the property set.
  679. //
  680. // This will be called for each instance of this structure on which the PopulateFromVariant method
  681. // was called and also on a number of different instances of this structure into which properties
  682. // common to one or more variants have been copied. Therefore, implementations of this must handle
  683. // the case when this structure is only partially populated.
  684. AddToPropertySet(ctx SdkMemberContext, propertySet BpPropertySet)
  685. }
  686. // SdkMemberContext provides access to information common to a specific member.
  687. type SdkMemberContext interface {
  688. // SdkModuleContext returns the module context of the sdk common os variant which is creating the
  689. // snapshot.
  690. //
  691. // This is common to all members of the sdk and is not specific to the member being processed.
  692. // If information about the member being processed needs to be obtained from this ModuleContext it
  693. // must be obtained using one of the OtherModule... methods not the Module... methods.
  694. SdkModuleContext() ModuleContext
  695. // SnapshotBuilder the builder of the snapshot.
  696. SnapshotBuilder() SnapshotBuilder
  697. // MemberType returns the type of the member currently being processed.
  698. MemberType() SdkMemberType
  699. // Name returns the name of the member currently being processed.
  700. //
  701. // Provided for use by sdk members to create a member specific location within the snapshot
  702. // into which to copy the prebuilt files.
  703. Name() string
  704. // RequiresTrait returns true if this member is expected to provide the specified trait.
  705. RequiresTrait(trait SdkMemberTrait) bool
  706. // IsTargetBuildBeforeTiramisu return true if the target build release for which this snapshot is
  707. // being generated is before Tiramisu, i.e. S.
  708. IsTargetBuildBeforeTiramisu() bool
  709. // ModuleErrorf reports an error at the line number of the module type in the module definition.
  710. ModuleErrorf(fmt string, args ...interface{})
  711. }
  712. // ExportedComponentsInfo contains information about the components that this module exports to an
  713. // sdk snapshot.
  714. //
  715. // A component of a module is a child module that the module creates and which forms an integral
  716. // part of the functionality that the creating module provides. A component module is essentially
  717. // owned by its creator and is tightly coupled to the creator and other components.
  718. //
  719. // e.g. the child modules created by prebuilt_apis are not components because they are not tightly
  720. // coupled to the prebuilt_apis module. Once they are created the prebuilt_apis ignores them. The
  721. // child impl and stub library created by java_sdk_library (and corresponding import) are components
  722. // because the creating module depends upon them in order to provide some of its own functionality.
  723. //
  724. // A component is exported if it is part of an sdk snapshot. e.g. The xml and impl child modules are
  725. // components but they are not exported as they are not part of an sdk snapshot.
  726. //
  727. // This information is used by the sdk snapshot generation code to ensure that it does not create
  728. // an sdk snapshot that contains a declaration of the component module and the module that creates
  729. // it as that would result in duplicate modules when attempting to use the snapshot. e.g. a snapshot
  730. // that included the java_sdk_library_import "foo" and also a java_import "foo.stubs" would fail
  731. // as there would be two modules called "foo.stubs".
  732. type ExportedComponentsInfo struct {
  733. // The names of the exported components.
  734. Components []string
  735. }
  736. var ExportedComponentsInfoProvider = blueprint.NewProvider(ExportedComponentsInfo{})
  737. // AdditionalSdkInfo contains additional properties to add to the generated SDK info file.
  738. type AdditionalSdkInfo struct {
  739. Properties map[string]interface{}
  740. }
  741. var AdditionalSdkInfoProvider = blueprint.NewProvider(AdditionalSdkInfo{})