sdk.go 39 KB

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