droidstubs.go 38 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046
  1. // Copyright 2021 Google Inc. All rights reserved.
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. package java
  15. import (
  16. "fmt"
  17. "path/filepath"
  18. "regexp"
  19. "sort"
  20. "strings"
  21. "github.com/google/blueprint/proptools"
  22. "android/soong/android"
  23. "android/soong/bazel"
  24. "android/soong/java/config"
  25. "android/soong/remoteexec"
  26. )
  27. // The values allowed for Droidstubs' Api_levels_sdk_type
  28. var allowedApiLevelSdkTypes = []string{"public", "system", "module-lib", "system-server"}
  29. func init() {
  30. RegisterStubsBuildComponents(android.InitRegistrationContext)
  31. }
  32. func RegisterStubsBuildComponents(ctx android.RegistrationContext) {
  33. ctx.RegisterModuleType("stubs_defaults", StubsDefaultsFactory)
  34. ctx.RegisterModuleType("droidstubs", DroidstubsFactory)
  35. ctx.RegisterModuleType("droidstubs_host", DroidstubsHostFactory)
  36. ctx.RegisterModuleType("prebuilt_stubs_sources", PrebuiltStubsSourcesFactory)
  37. }
  38. // Droidstubs
  39. type Droidstubs struct {
  40. Javadoc
  41. properties DroidstubsProperties
  42. apiFile android.Path
  43. removedApiFile android.Path
  44. nullabilityWarningsFile android.WritablePath
  45. checkCurrentApiTimestamp android.WritablePath
  46. updateCurrentApiTimestamp android.WritablePath
  47. checkLastReleasedApiTimestamp android.WritablePath
  48. apiLintTimestamp android.WritablePath
  49. apiLintReport android.WritablePath
  50. checkNullabilityWarningsTimestamp android.WritablePath
  51. annotationsZip android.WritablePath
  52. apiVersionsXml android.WritablePath
  53. metadataZip android.WritablePath
  54. metadataDir android.WritablePath
  55. }
  56. type DroidstubsProperties struct {
  57. // The generated public API filename by Metalava, defaults to <module>_api.txt
  58. Api_filename *string
  59. // the generated removed API filename by Metalava, defaults to <module>_removed.txt
  60. Removed_api_filename *string
  61. Check_api struct {
  62. Last_released ApiToCheck
  63. Current ApiToCheck
  64. Api_lint struct {
  65. Enabled *bool
  66. // If set, performs api_lint on any new APIs not found in the given signature file
  67. New_since *string `android:"path"`
  68. // If not blank, path to the baseline txt file for approved API lint violations.
  69. Baseline_file *string `android:"path"`
  70. }
  71. }
  72. // user can specify the version of previous released API file in order to do compatibility check.
  73. Previous_api *string `android:"path"`
  74. // is set to true, Metalava will allow framework SDK to contain annotations.
  75. Annotations_enabled *bool
  76. // a list of top-level directories containing files to merge qualifier annotations (i.e. those intended to be included in the stubs written) from.
  77. Merge_annotations_dirs []string
  78. // a list of top-level directories containing Java stub files to merge show/hide annotations from.
  79. Merge_inclusion_annotations_dirs []string
  80. // a file containing a list of classes to do nullability validation for.
  81. Validate_nullability_from_list *string
  82. // a file containing expected warnings produced by validation of nullability annotations.
  83. Check_nullability_warnings *string
  84. // if set to true, allow Metalava to generate doc_stubs source files. Defaults to false.
  85. Create_doc_stubs *bool
  86. // if set to true, cause Metalava to output Javadoc comments in the stubs source files. Defaults to false.
  87. // Has no effect if create_doc_stubs: true.
  88. Output_javadoc_comments *bool
  89. // if set to false then do not write out stubs. Defaults to true.
  90. //
  91. // TODO(b/146727827): Remove capability when we do not need to generate stubs and API separately.
  92. Generate_stubs *bool
  93. // if set to true, provides a hint to the build system that this rule uses a lot of memory,
  94. // whicih can be used for scheduling purposes
  95. High_mem *bool
  96. // if set to true, Metalava will allow framework SDK to contain API levels annotations.
  97. Api_levels_annotations_enabled *bool
  98. // Apply the api levels database created by this module rather than generating one in this droidstubs.
  99. Api_levels_module *string
  100. // the dirs which Metalava extracts API levels annotations from.
  101. Api_levels_annotations_dirs []string
  102. // the sdk kind which Metalava extracts API levels annotations from. Supports 'public', 'system', 'module-lib' and 'system-server'; defaults to public.
  103. Api_levels_sdk_type *string
  104. // the filename which Metalava extracts API levels annotations from. Defaults to android.jar.
  105. Api_levels_jar_filename *string
  106. // if set to true, collect the values used by the Dev tools and
  107. // write them in files packaged with the SDK. Defaults to false.
  108. Write_sdk_values *bool
  109. // path or filegroup to file defining extension an SDK name <-> numerical ID mapping and
  110. // what APIs exist in which SDKs; passed to metalava via --sdk-extensions-info
  111. Extensions_info_file *string `android:"path"`
  112. // API surface of this module. If set, the module contributes to an API surface.
  113. // For the full list of available API surfaces, refer to soong/android/sdk_version.go
  114. Api_surface *string
  115. }
  116. // Used by xsd_config
  117. type ApiFilePath interface {
  118. ApiFilePath() android.Path
  119. }
  120. type ApiStubsSrcProvider interface {
  121. StubsSrcJar() android.Path
  122. }
  123. // Provider of information about API stubs, used by java_sdk_library.
  124. type ApiStubsProvider interface {
  125. AnnotationsZip() android.Path
  126. ApiFilePath
  127. RemovedApiFilePath() android.Path
  128. ApiStubsSrcProvider
  129. }
  130. // droidstubs passes sources files through Metalava to generate stub .java files that only contain the API to be
  131. // documented, filtering out hidden classes and methods. The resulting .java files are intended to be passed to
  132. // a droiddoc module to generate documentation.
  133. func DroidstubsFactory() android.Module {
  134. module := &Droidstubs{}
  135. module.AddProperties(&module.properties,
  136. &module.Javadoc.properties)
  137. InitDroiddocModule(module, android.HostAndDeviceSupported)
  138. module.SetDefaultableHook(func(ctx android.DefaultableHookContext) {
  139. module.createApiContribution(ctx)
  140. })
  141. return module
  142. }
  143. // droidstubs_host passes sources files through Metalava to generate stub .java files that only contain the API
  144. // to be documented, filtering out hidden classes and methods. The resulting .java files are intended to be
  145. // passed to a droiddoc_host module to generate documentation. Use a droidstubs_host instead of a droidstubs
  146. // module when symbols needed by the source files are provided by java_library_host modules.
  147. func DroidstubsHostFactory() android.Module {
  148. module := &Droidstubs{}
  149. module.AddProperties(&module.properties,
  150. &module.Javadoc.properties)
  151. InitDroiddocModule(module, android.HostSupported)
  152. return module
  153. }
  154. func (d *Droidstubs) OutputFiles(tag string) (android.Paths, error) {
  155. switch tag {
  156. case "":
  157. return android.Paths{d.stubsSrcJar}, nil
  158. case ".docs.zip":
  159. return android.Paths{d.docZip}, nil
  160. case ".api.txt", android.DefaultDistTag:
  161. // This is the default dist path for dist properties that have no tag property.
  162. return android.Paths{d.apiFile}, nil
  163. case ".removed-api.txt":
  164. return android.Paths{d.removedApiFile}, nil
  165. case ".annotations.zip":
  166. return android.Paths{d.annotationsZip}, nil
  167. case ".api_versions.xml":
  168. return android.Paths{d.apiVersionsXml}, nil
  169. default:
  170. return nil, fmt.Errorf("unsupported module reference tag %q", tag)
  171. }
  172. }
  173. func (d *Droidstubs) AnnotationsZip() android.Path {
  174. return d.annotationsZip
  175. }
  176. func (d *Droidstubs) ApiFilePath() android.Path {
  177. return d.apiFile
  178. }
  179. func (d *Droidstubs) RemovedApiFilePath() android.Path {
  180. return d.removedApiFile
  181. }
  182. func (d *Droidstubs) StubsSrcJar() android.Path {
  183. return d.stubsSrcJar
  184. }
  185. var metalavaMergeAnnotationsDirTag = dependencyTag{name: "metalava-merge-annotations-dir"}
  186. var metalavaMergeInclusionAnnotationsDirTag = dependencyTag{name: "metalava-merge-inclusion-annotations-dir"}
  187. var metalavaAPILevelsAnnotationsDirTag = dependencyTag{name: "metalava-api-levels-annotations-dir"}
  188. var metalavaAPILevelsModuleTag = dependencyTag{name: "metalava-api-levels-module-tag"}
  189. func (d *Droidstubs) DepsMutator(ctx android.BottomUpMutatorContext) {
  190. d.Javadoc.addDeps(ctx)
  191. if len(d.properties.Merge_annotations_dirs) != 0 {
  192. for _, mergeAnnotationsDir := range d.properties.Merge_annotations_dirs {
  193. ctx.AddDependency(ctx.Module(), metalavaMergeAnnotationsDirTag, mergeAnnotationsDir)
  194. }
  195. }
  196. if len(d.properties.Merge_inclusion_annotations_dirs) != 0 {
  197. for _, mergeInclusionAnnotationsDir := range d.properties.Merge_inclusion_annotations_dirs {
  198. ctx.AddDependency(ctx.Module(), metalavaMergeInclusionAnnotationsDirTag, mergeInclusionAnnotationsDir)
  199. }
  200. }
  201. if len(d.properties.Api_levels_annotations_dirs) != 0 {
  202. for _, apiLevelsAnnotationsDir := range d.properties.Api_levels_annotations_dirs {
  203. ctx.AddDependency(ctx.Module(), metalavaAPILevelsAnnotationsDirTag, apiLevelsAnnotationsDir)
  204. }
  205. }
  206. if d.properties.Api_levels_module != nil {
  207. ctx.AddDependency(ctx.Module(), metalavaAPILevelsModuleTag, proptools.String(d.properties.Api_levels_module))
  208. }
  209. }
  210. func (d *Droidstubs) stubsFlags(ctx android.ModuleContext, cmd *android.RuleBuilderCommand, stubsDir android.OptionalPath) {
  211. if apiCheckEnabled(ctx, d.properties.Check_api.Current, "current") ||
  212. apiCheckEnabled(ctx, d.properties.Check_api.Last_released, "last_released") ||
  213. String(d.properties.Api_filename) != "" {
  214. filename := proptools.StringDefault(d.properties.Api_filename, ctx.ModuleName()+"_api.txt")
  215. uncheckedApiFile := android.PathForModuleOut(ctx, "metalava", filename)
  216. cmd.FlagWithOutput("--api ", uncheckedApiFile)
  217. d.apiFile = uncheckedApiFile
  218. } else if sourceApiFile := proptools.String(d.properties.Check_api.Current.Api_file); sourceApiFile != "" {
  219. // If check api is disabled then make the source file available for export.
  220. d.apiFile = android.PathForModuleSrc(ctx, sourceApiFile)
  221. }
  222. if apiCheckEnabled(ctx, d.properties.Check_api.Current, "current") ||
  223. apiCheckEnabled(ctx, d.properties.Check_api.Last_released, "last_released") ||
  224. String(d.properties.Removed_api_filename) != "" {
  225. filename := proptools.StringDefault(d.properties.Removed_api_filename, ctx.ModuleName()+"_removed.txt")
  226. uncheckedRemovedFile := android.PathForModuleOut(ctx, "metalava", filename)
  227. cmd.FlagWithOutput("--removed-api ", uncheckedRemovedFile)
  228. d.removedApiFile = uncheckedRemovedFile
  229. } else if sourceRemovedApiFile := proptools.String(d.properties.Check_api.Current.Removed_api_file); sourceRemovedApiFile != "" {
  230. // If check api is disabled then make the source removed api file available for export.
  231. d.removedApiFile = android.PathForModuleSrc(ctx, sourceRemovedApiFile)
  232. }
  233. if Bool(d.properties.Write_sdk_values) {
  234. d.metadataDir = android.PathForModuleOut(ctx, "metalava", "metadata")
  235. cmd.FlagWithArg("--sdk-values ", d.metadataDir.String())
  236. }
  237. if stubsDir.Valid() {
  238. if Bool(d.properties.Create_doc_stubs) {
  239. cmd.FlagWithArg("--doc-stubs ", stubsDir.String())
  240. } else {
  241. cmd.FlagWithArg("--stubs ", stubsDir.String())
  242. if !Bool(d.properties.Output_javadoc_comments) {
  243. cmd.Flag("--exclude-documentation-from-stubs")
  244. }
  245. }
  246. }
  247. }
  248. func (d *Droidstubs) annotationsFlags(ctx android.ModuleContext, cmd *android.RuleBuilderCommand) {
  249. if Bool(d.properties.Annotations_enabled) {
  250. cmd.Flag("--include-annotations")
  251. cmd.FlagWithArg("--exclude-annotation ", "androidx.annotation.RequiresApi")
  252. validatingNullability :=
  253. strings.Contains(String(d.Javadoc.properties.Args), "--validate-nullability-from-merged-stubs") ||
  254. String(d.properties.Validate_nullability_from_list) != ""
  255. migratingNullability := String(d.properties.Previous_api) != ""
  256. if migratingNullability {
  257. previousApi := android.PathForModuleSrc(ctx, String(d.properties.Previous_api))
  258. cmd.FlagWithInput("--migrate-nullness ", previousApi)
  259. }
  260. if s := String(d.properties.Validate_nullability_from_list); s != "" {
  261. cmd.FlagWithInput("--validate-nullability-from-list ", android.PathForModuleSrc(ctx, s))
  262. }
  263. if validatingNullability {
  264. d.nullabilityWarningsFile = android.PathForModuleOut(ctx, "metalava", ctx.ModuleName()+"_nullability_warnings.txt")
  265. cmd.FlagWithOutput("--nullability-warnings-txt ", d.nullabilityWarningsFile)
  266. }
  267. d.annotationsZip = android.PathForModuleOut(ctx, "metalava", ctx.ModuleName()+"_annotations.zip")
  268. cmd.FlagWithOutput("--extract-annotations ", d.annotationsZip)
  269. if len(d.properties.Merge_annotations_dirs) != 0 {
  270. d.mergeAnnoDirFlags(ctx, cmd)
  271. }
  272. // TODO(tnorbye): find owners to fix these warnings when annotation was enabled.
  273. cmd.FlagWithArg("--hide ", "HiddenTypedefConstant").
  274. FlagWithArg("--hide ", "SuperfluousPrefix").
  275. FlagWithArg("--hide ", "AnnotationExtraction").
  276. // b/222738070
  277. FlagWithArg("--hide ", "BannedThrow").
  278. // b/223382732
  279. FlagWithArg("--hide ", "ChangedDefault")
  280. }
  281. }
  282. func (d *Droidstubs) mergeAnnoDirFlags(ctx android.ModuleContext, cmd *android.RuleBuilderCommand) {
  283. ctx.VisitDirectDepsWithTag(metalavaMergeAnnotationsDirTag, func(m android.Module) {
  284. if t, ok := m.(*ExportedDroiddocDir); ok {
  285. cmd.FlagWithArg("--merge-qualifier-annotations ", t.dir.String()).Implicits(t.deps)
  286. } else {
  287. ctx.PropertyErrorf("merge_annotations_dirs",
  288. "module %q is not a metalava merge-annotations dir", ctx.OtherModuleName(m))
  289. }
  290. })
  291. }
  292. func (d *Droidstubs) inclusionAnnotationsFlags(ctx android.ModuleContext, cmd *android.RuleBuilderCommand) {
  293. ctx.VisitDirectDepsWithTag(metalavaMergeInclusionAnnotationsDirTag, func(m android.Module) {
  294. if t, ok := m.(*ExportedDroiddocDir); ok {
  295. cmd.FlagWithArg("--merge-inclusion-annotations ", t.dir.String()).Implicits(t.deps)
  296. } else {
  297. ctx.PropertyErrorf("merge_inclusion_annotations_dirs",
  298. "module %q is not a metalava merge-annotations dir", ctx.OtherModuleName(m))
  299. }
  300. })
  301. }
  302. func (d *Droidstubs) apiLevelsAnnotationsFlags(ctx android.ModuleContext, cmd *android.RuleBuilderCommand) {
  303. var apiVersions android.Path
  304. if proptools.Bool(d.properties.Api_levels_annotations_enabled) {
  305. d.apiLevelsGenerationFlags(ctx, cmd)
  306. apiVersions = d.apiVersionsXml
  307. } else {
  308. ctx.VisitDirectDepsWithTag(metalavaAPILevelsModuleTag, func(m android.Module) {
  309. if s, ok := m.(*Droidstubs); ok {
  310. apiVersions = s.apiVersionsXml
  311. } else {
  312. ctx.PropertyErrorf("api_levels_module",
  313. "module %q is not a droidstubs module", ctx.OtherModuleName(m))
  314. }
  315. })
  316. }
  317. if apiVersions != nil {
  318. cmd.FlagWithArg("--current-version ", ctx.Config().PlatformSdkVersion().String())
  319. cmd.FlagWithArg("--current-codename ", ctx.Config().PlatformSdkCodename())
  320. cmd.FlagWithInput("--apply-api-levels ", apiVersions)
  321. }
  322. }
  323. func (d *Droidstubs) apiLevelsGenerationFlags(ctx android.ModuleContext, cmd *android.RuleBuilderCommand) {
  324. if len(d.properties.Api_levels_annotations_dirs) == 0 {
  325. ctx.PropertyErrorf("api_levels_annotations_dirs",
  326. "has to be non-empty if api levels annotations was enabled!")
  327. }
  328. d.apiVersionsXml = android.PathForModuleOut(ctx, "metalava", "api-versions.xml")
  329. cmd.FlagWithOutput("--generate-api-levels ", d.apiVersionsXml)
  330. filename := proptools.StringDefault(d.properties.Api_levels_jar_filename, "android.jar")
  331. var dirs []string
  332. var extensions_dir string
  333. ctx.VisitDirectDepsWithTag(metalavaAPILevelsAnnotationsDirTag, func(m android.Module) {
  334. if t, ok := m.(*ExportedDroiddocDir); ok {
  335. extRegex := regexp.MustCompile(t.dir.String() + `/extensions/[0-9]+/public/.*\.jar`)
  336. // Grab the first extensions_dir and we find while scanning ExportedDroiddocDir.deps;
  337. // ideally this should be read from prebuiltApis.properties.Extensions_*
  338. for _, dep := range t.deps {
  339. if extRegex.MatchString(dep.String()) && d.properties.Extensions_info_file != nil {
  340. if extensions_dir == "" {
  341. extensions_dir = t.dir.String() + "/extensions"
  342. }
  343. cmd.Implicit(dep)
  344. }
  345. if dep.Base() == filename {
  346. cmd.Implicit(dep)
  347. }
  348. if filename != "android.jar" && dep.Base() == "android.jar" {
  349. // Metalava implicitly searches these patterns:
  350. // prebuilts/tools/common/api-versions/android-%/android.jar
  351. // prebuilts/sdk/%/public/android.jar
  352. // Add android.jar files from the api_levels_annotations_dirs directories to try
  353. // to satisfy these patterns. If Metalava can't find a match for an API level
  354. // between 1 and 28 in at least one pattern it will fail.
  355. cmd.Implicit(dep)
  356. }
  357. }
  358. dirs = append(dirs, t.dir.String())
  359. } else {
  360. ctx.PropertyErrorf("api_levels_annotations_dirs",
  361. "module %q is not a metalava api-levels-annotations dir", ctx.OtherModuleName(m))
  362. }
  363. })
  364. // Add all relevant --android-jar-pattern patterns for Metalava.
  365. // When parsing a stub jar for a specific version, Metalava picks the first pattern that defines
  366. // an actual file present on disk (in the order the patterns were passed). For system APIs for
  367. // privileged apps that are only defined since API level 21 (Lollipop), fallback to public stubs
  368. // for older releases. Similarly, module-lib falls back to system API.
  369. var sdkDirs []string
  370. switch proptools.StringDefault(d.properties.Api_levels_sdk_type, "public") {
  371. case "system-server":
  372. sdkDirs = []string{"system-server", "module-lib", "system", "public"}
  373. case "module-lib":
  374. sdkDirs = []string{"module-lib", "system", "public"}
  375. case "system":
  376. sdkDirs = []string{"system", "public"}
  377. case "public":
  378. sdkDirs = []string{"public"}
  379. default:
  380. ctx.PropertyErrorf("api_levels_sdk_type", "needs to be one of %v", allowedApiLevelSdkTypes)
  381. return
  382. }
  383. for _, sdkDir := range sdkDirs {
  384. for _, dir := range dirs {
  385. cmd.FlagWithArg("--android-jar-pattern ", fmt.Sprintf("%s/%%/%s/%s", dir, sdkDir, filename))
  386. }
  387. }
  388. if d.properties.Extensions_info_file != nil {
  389. if extensions_dir == "" {
  390. ctx.ModuleErrorf("extensions_info_file set, but no SDK extension dirs found")
  391. }
  392. info_file := android.PathForModuleSrc(ctx, *d.properties.Extensions_info_file)
  393. cmd.Implicit(info_file)
  394. cmd.FlagWithArg("--sdk-extensions-root ", extensions_dir)
  395. cmd.FlagWithArg("--sdk-extensions-info ", info_file.String())
  396. }
  397. }
  398. func metalavaUseRbe(ctx android.ModuleContext) bool {
  399. return ctx.Config().UseRBE() && ctx.Config().IsEnvTrue("RBE_METALAVA")
  400. }
  401. func metalavaCmd(ctx android.ModuleContext, rule *android.RuleBuilder, javaVersion javaVersion, srcs android.Paths,
  402. srcJarList android.Path, bootclasspath, classpath classpath, homeDir android.WritablePath) *android.RuleBuilderCommand {
  403. rule.Command().Text("rm -rf").Flag(homeDir.String())
  404. rule.Command().Text("mkdir -p").Flag(homeDir.String())
  405. cmd := rule.Command()
  406. cmd.FlagWithArg("ANDROID_PREFS_ROOT=", homeDir.String())
  407. if metalavaUseRbe(ctx) {
  408. rule.Remoteable(android.RemoteRuleSupports{RBE: true})
  409. execStrategy := ctx.Config().GetenvWithDefault("RBE_METALAVA_EXEC_STRATEGY", remoteexec.LocalExecStrategy)
  410. labels := map[string]string{"type": "tool", "name": "metalava"}
  411. // TODO: metalava pool rejects these jobs
  412. pool := ctx.Config().GetenvWithDefault("RBE_METALAVA_POOL", "java16")
  413. rule.Rewrapper(&remoteexec.REParams{
  414. Labels: labels,
  415. ExecStrategy: execStrategy,
  416. ToolchainInputs: []string{config.JavaCmd(ctx).String()},
  417. Platform: map[string]string{remoteexec.PoolKey: pool},
  418. })
  419. }
  420. cmd.BuiltTool("metalava").ImplicitTool(ctx.Config().HostJavaToolPath(ctx, "metalava.jar")).
  421. Flag(config.JavacVmFlags).
  422. Flag("-J--add-opens=java.base/java.util=ALL-UNNAMED").
  423. FlagWithArg("-encoding ", "UTF-8").
  424. FlagWithArg("-source ", javaVersion.String()).
  425. FlagWithRspFileInputList("@", android.PathForModuleOut(ctx, "metalava.rsp"), srcs).
  426. FlagWithInput("@", srcJarList)
  427. if len(bootclasspath) > 0 {
  428. cmd.FlagWithInputList("-bootclasspath ", bootclasspath.Paths(), ":")
  429. }
  430. if len(classpath) > 0 {
  431. cmd.FlagWithInputList("-classpath ", classpath.Paths(), ":")
  432. }
  433. cmd.Flag("--no-banner").
  434. Flag("--color").
  435. Flag("--quiet").
  436. Flag("--format=v2").
  437. FlagWithArg("--repeat-errors-max ", "10").
  438. FlagWithArg("--hide ", "UnresolvedImport").
  439. FlagWithArg("--hide ", "InvalidNullabilityOverride").
  440. // b/223382732
  441. FlagWithArg("--hide ", "ChangedDefault")
  442. // Force metalava to ignore classes on the classpath when an API file contains missing classes.
  443. // See b/285140653 for more information.
  444. cmd.FlagWithArg("--api-class-resolution ", "api")
  445. // Force metalava to sort overloaded methods by their order in the source code.
  446. // See b/285312164 for more information.
  447. cmd.FlagWithArg("--api-overloaded-method-order ", "source")
  448. return cmd
  449. }
  450. func (d *Droidstubs) GenerateAndroidBuildActions(ctx android.ModuleContext) {
  451. deps := d.Javadoc.collectDeps(ctx)
  452. javaVersion := getJavaVersion(ctx, String(d.Javadoc.properties.Java_version), android.SdkContext(d))
  453. // Create rule for metalava
  454. srcJarDir := android.PathForModuleOut(ctx, "metalava", "srcjars")
  455. rule := android.NewRuleBuilder(pctx, ctx)
  456. rule.Sbox(android.PathForModuleOut(ctx, "metalava"),
  457. android.PathForModuleOut(ctx, "metalava.sbox.textproto")).
  458. SandboxInputs()
  459. if BoolDefault(d.properties.High_mem, false) {
  460. // This metalava run uses lots of memory, restrict the number of metalava jobs that can run in parallel.
  461. rule.HighMem()
  462. }
  463. generateStubs := BoolDefault(d.properties.Generate_stubs, true)
  464. var stubsDir android.OptionalPath
  465. if generateStubs {
  466. d.Javadoc.stubsSrcJar = android.PathForModuleOut(ctx, "metalava", ctx.ModuleName()+"-"+"stubs.srcjar")
  467. stubsDir = android.OptionalPathForPath(android.PathForModuleOut(ctx, "metalava", "stubsDir"))
  468. rule.Command().Text("rm -rf").Text(stubsDir.String())
  469. rule.Command().Text("mkdir -p").Text(stubsDir.String())
  470. }
  471. srcJarList := zipSyncCmd(ctx, rule, srcJarDir, d.Javadoc.srcJars)
  472. homeDir := android.PathForModuleOut(ctx, "metalava", "home")
  473. cmd := metalavaCmd(ctx, rule, javaVersion, d.Javadoc.srcFiles, srcJarList,
  474. deps.bootClasspath, deps.classpath, homeDir)
  475. cmd.Implicits(d.Javadoc.implicits)
  476. d.stubsFlags(ctx, cmd, stubsDir)
  477. d.annotationsFlags(ctx, cmd)
  478. d.inclusionAnnotationsFlags(ctx, cmd)
  479. d.apiLevelsAnnotationsFlags(ctx, cmd)
  480. d.expandArgs(ctx, cmd)
  481. for _, o := range d.Javadoc.properties.Out {
  482. cmd.ImplicitOutput(android.PathForModuleGen(ctx, o))
  483. }
  484. // Add options for the other optional tasks: API-lint and check-released.
  485. // We generate separate timestamp files for them.
  486. doApiLint := false
  487. doCheckReleased := false
  488. // Add API lint options.
  489. if BoolDefault(d.properties.Check_api.Api_lint.Enabled, false) {
  490. doApiLint = true
  491. newSince := android.OptionalPathForModuleSrc(ctx, d.properties.Check_api.Api_lint.New_since)
  492. if newSince.Valid() {
  493. cmd.FlagWithInput("--api-lint ", newSince.Path())
  494. } else {
  495. cmd.Flag("--api-lint")
  496. }
  497. d.apiLintReport = android.PathForModuleOut(ctx, "metalava", "api_lint_report.txt")
  498. cmd.FlagWithOutput("--report-even-if-suppressed ", d.apiLintReport) // TODO: Change to ":api-lint"
  499. // TODO(b/154317059): Clean up this allowlist by baselining and/or checking in last-released.
  500. if d.Name() != "android.car-system-stubs-docs" &&
  501. d.Name() != "android.car-stubs-docs" {
  502. cmd.Flag("--lints-as-errors")
  503. cmd.Flag("--warnings-as-errors") // Most lints are actually warnings.
  504. }
  505. baselineFile := android.OptionalPathForModuleSrc(ctx, d.properties.Check_api.Api_lint.Baseline_file)
  506. updatedBaselineOutput := android.PathForModuleOut(ctx, "metalava", "api_lint_baseline.txt")
  507. d.apiLintTimestamp = android.PathForModuleOut(ctx, "metalava", "api_lint.timestamp")
  508. // Note this string includes a special shell quote $' ... ', which decodes the "\n"s.
  509. //
  510. // TODO: metalava also has a slightly different message hardcoded. Should we unify this
  511. // message and metalava's one?
  512. msg := `$'` + // Enclose with $' ... '
  513. `************************************************************\n` +
  514. `Your API changes are triggering API Lint warnings or errors.\n` +
  515. `To make these errors go away, fix the code according to the\n` +
  516. `error and/or warning messages above.\n` +
  517. `\n` +
  518. `If it is not possible to do so, there are workarounds:\n` +
  519. `\n` +
  520. `1. You can suppress the errors with @SuppressLint("<id>")\n` +
  521. ` where the <id> is given in brackets in the error message above.\n`
  522. if baselineFile.Valid() {
  523. cmd.FlagWithInput("--baseline:api-lint ", baselineFile.Path())
  524. cmd.FlagWithOutput("--update-baseline:api-lint ", updatedBaselineOutput)
  525. msg += fmt.Sprintf(``+
  526. `2. You can update the baseline by executing the following\n`+
  527. ` command:\n`+
  528. ` (cd $ANDROID_BUILD_TOP && cp \\\n`+
  529. ` "%s" \\\n`+
  530. ` "%s")\n`+
  531. ` To submit the revised baseline.txt to the main Android\n`+
  532. ` repository, you will need approval.\n`, updatedBaselineOutput, baselineFile.Path())
  533. } else {
  534. msg += fmt.Sprintf(``+
  535. `2. You can add a baseline file of existing lint failures\n`+
  536. ` to the build rule of %s.\n`, d.Name())
  537. }
  538. // Note the message ends with a ' (single quote), to close the $' ... ' .
  539. msg += `************************************************************\n'`
  540. cmd.FlagWithArg("--error-message:api-lint ", msg)
  541. }
  542. // Add "check released" options. (Detect incompatible API changes from the last public release)
  543. if apiCheckEnabled(ctx, d.properties.Check_api.Last_released, "last_released") {
  544. doCheckReleased = true
  545. if len(d.Javadoc.properties.Out) > 0 {
  546. ctx.PropertyErrorf("out", "out property may not be combined with check_api")
  547. }
  548. apiFile := android.PathForModuleSrc(ctx, String(d.properties.Check_api.Last_released.Api_file))
  549. removedApiFile := android.PathForModuleSrc(ctx, String(d.properties.Check_api.Last_released.Removed_api_file))
  550. baselineFile := android.OptionalPathForModuleSrc(ctx, d.properties.Check_api.Last_released.Baseline_file)
  551. updatedBaselineOutput := android.PathForModuleOut(ctx, "metalava", "last_released_baseline.txt")
  552. d.checkLastReleasedApiTimestamp = android.PathForModuleOut(ctx, "metalava", "check_last_released_api.timestamp")
  553. cmd.FlagWithInput("--check-compatibility:api:released ", apiFile)
  554. cmd.FlagWithInput("--check-compatibility:removed:released ", removedApiFile)
  555. if baselineFile.Valid() {
  556. cmd.FlagWithInput("--baseline:compatibility:released ", baselineFile.Path())
  557. cmd.FlagWithOutput("--update-baseline:compatibility:released ", updatedBaselineOutput)
  558. }
  559. // Note this string includes quote ($' ... '), which decodes the "\n"s.
  560. msg := `$'\n******************************\n` +
  561. `You have tried to change the API from what has been previously released in\n` +
  562. `an SDK. Please fix the errors listed above.\n` +
  563. `******************************\n'`
  564. cmd.FlagWithArg("--error-message:compatibility:released ", msg)
  565. }
  566. if generateStubs {
  567. rule.Command().
  568. BuiltTool("soong_zip").
  569. Flag("-write_if_changed").
  570. Flag("-jar").
  571. FlagWithOutput("-o ", d.Javadoc.stubsSrcJar).
  572. FlagWithArg("-C ", stubsDir.String()).
  573. FlagWithArg("-D ", stubsDir.String())
  574. }
  575. if Bool(d.properties.Write_sdk_values) {
  576. d.metadataZip = android.PathForModuleOut(ctx, "metalava", ctx.ModuleName()+"-metadata.zip")
  577. rule.Command().
  578. BuiltTool("soong_zip").
  579. Flag("-write_if_changed").
  580. Flag("-d").
  581. FlagWithOutput("-o ", d.metadataZip).
  582. FlagWithArg("-C ", d.metadataDir.String()).
  583. FlagWithArg("-D ", d.metadataDir.String())
  584. }
  585. // TODO: We don't really need two separate API files, but this is a reminiscence of how
  586. // we used to run metalava separately for API lint and the "last_released" check. Unify them.
  587. if doApiLint {
  588. rule.Command().Text("touch").Output(d.apiLintTimestamp)
  589. }
  590. if doCheckReleased {
  591. rule.Command().Text("touch").Output(d.checkLastReleasedApiTimestamp)
  592. }
  593. // TODO(b/183630617): rewrapper doesn't support restat rules
  594. if !metalavaUseRbe(ctx) {
  595. rule.Restat()
  596. }
  597. zipSyncCleanupCmd(rule, srcJarDir)
  598. rule.Build("metalava", "metalava merged")
  599. if apiCheckEnabled(ctx, d.properties.Check_api.Current, "current") {
  600. if len(d.Javadoc.properties.Out) > 0 {
  601. ctx.PropertyErrorf("out", "out property may not be combined with check_api")
  602. }
  603. apiFile := android.PathForModuleSrc(ctx, String(d.properties.Check_api.Current.Api_file))
  604. removedApiFile := android.PathForModuleSrc(ctx, String(d.properties.Check_api.Current.Removed_api_file))
  605. baselineFile := android.OptionalPathForModuleSrc(ctx, d.properties.Check_api.Current.Baseline_file)
  606. if baselineFile.Valid() {
  607. ctx.PropertyErrorf("baseline_file", "current API check can't have a baseline file. (module %s)", ctx.ModuleName())
  608. }
  609. d.checkCurrentApiTimestamp = android.PathForModuleOut(ctx, "metalava", "check_current_api.timestamp")
  610. rule := android.NewRuleBuilder(pctx, ctx)
  611. // Diff command line.
  612. // -F matches the closest "opening" line, such as "package android {"
  613. // and " public class Intent {".
  614. diff := `diff -u -F '{ *$'`
  615. rule.Command().Text("( true")
  616. rule.Command().
  617. Text(diff).
  618. Input(apiFile).Input(d.apiFile)
  619. rule.Command().
  620. Text(diff).
  621. Input(removedApiFile).Input(d.removedApiFile)
  622. msg := fmt.Sprintf(`\n******************************\n`+
  623. `You have tried to change the API from what has been previously approved.\n\n`+
  624. `To make these errors go away, you have two choices:\n`+
  625. ` 1. You can add '@hide' javadoc comments (and remove @SystemApi/@TestApi/etc)\n`+
  626. ` to the new methods, etc. shown in the above diff.\n\n`+
  627. ` 2. You can update current.txt and/or removed.txt by executing the following command:\n`+
  628. ` m %s-update-current-api\n\n`+
  629. ` To submit the revised current.txt to the main Android repository,\n`+
  630. ` you will need approval.\n`+
  631. `******************************\n`, ctx.ModuleName())
  632. rule.Command().
  633. Text("touch").Output(d.checkCurrentApiTimestamp).
  634. Text(") || (").
  635. Text("echo").Flag("-e").Flag(`"` + msg + `"`).
  636. Text("; exit 38").
  637. Text(")")
  638. rule.Build("metalavaCurrentApiCheck", "check current API")
  639. d.updateCurrentApiTimestamp = android.PathForModuleOut(ctx, "metalava", "update_current_api.timestamp")
  640. // update API rule
  641. rule = android.NewRuleBuilder(pctx, ctx)
  642. rule.Command().Text("( true")
  643. rule.Command().
  644. Text("cp").Flag("-f").
  645. Input(d.apiFile).Flag(apiFile.String())
  646. rule.Command().
  647. Text("cp").Flag("-f").
  648. Input(d.removedApiFile).Flag(removedApiFile.String())
  649. msg = "failed to update public API"
  650. rule.Command().
  651. Text("touch").Output(d.updateCurrentApiTimestamp).
  652. Text(") || (").
  653. Text("echo").Flag("-e").Flag(`"` + msg + `"`).
  654. Text("; exit 38").
  655. Text(")")
  656. rule.Build("metalavaCurrentApiUpdate", "update current API")
  657. }
  658. if String(d.properties.Check_nullability_warnings) != "" {
  659. if d.nullabilityWarningsFile == nil {
  660. ctx.PropertyErrorf("check_nullability_warnings",
  661. "Cannot specify check_nullability_warnings unless validating nullability")
  662. }
  663. checkNullabilityWarnings := android.PathForModuleSrc(ctx, String(d.properties.Check_nullability_warnings))
  664. d.checkNullabilityWarningsTimestamp = android.PathForModuleOut(ctx, "metalava", "check_nullability_warnings.timestamp")
  665. msg := fmt.Sprintf(`\n******************************\n`+
  666. `The warnings encountered during nullability annotation validation did\n`+
  667. `not match the checked in file of expected warnings. The diffs are shown\n`+
  668. `above. You have two options:\n`+
  669. ` 1. Resolve the differences by editing the nullability annotations.\n`+
  670. ` 2. Update the file of expected warnings by running:\n`+
  671. ` cp %s %s\n`+
  672. ` and submitting the updated file as part of your change.`,
  673. d.nullabilityWarningsFile, checkNullabilityWarnings)
  674. rule := android.NewRuleBuilder(pctx, ctx)
  675. rule.Command().
  676. Text("(").
  677. Text("diff").Input(checkNullabilityWarnings).Input(d.nullabilityWarningsFile).
  678. Text("&&").
  679. Text("touch").Output(d.checkNullabilityWarningsTimestamp).
  680. Text(") || (").
  681. Text("echo").Flag("-e").Flag(`"` + msg + `"`).
  682. Text("; exit 38").
  683. Text(")")
  684. rule.Build("nullabilityWarningsCheck", "nullability warnings check")
  685. }
  686. }
  687. var _ android.ApiProvider = (*Droidstubs)(nil)
  688. type bazelJavaApiContributionAttributes struct {
  689. Api bazel.LabelAttribute
  690. Api_surface *string
  691. }
  692. func (d *Droidstubs) ConvertWithApiBp2build(ctx android.TopDownMutatorContext) {
  693. props := bazel.BazelTargetModuleProperties{
  694. Rule_class: "java_api_contribution",
  695. Bzl_load_location: "//build/bazel/rules/apis:java_api_contribution.bzl",
  696. }
  697. apiFile := d.properties.Check_api.Current.Api_file
  698. // Do not generate a target if check_api is not set
  699. if apiFile == nil {
  700. return
  701. }
  702. attrs := &bazelJavaApiContributionAttributes{
  703. Api: *bazel.MakeLabelAttribute(
  704. android.BazelLabelForModuleSrcSingle(ctx, proptools.String(apiFile)).Label,
  705. ),
  706. Api_surface: proptools.StringPtr(bazelApiSurfaceName(d.Name())),
  707. }
  708. ctx.CreateBazelTargetModule(props, android.CommonAttributes{
  709. Name: android.ApiContributionTargetName(ctx.ModuleName()),
  710. }, attrs)
  711. }
  712. func (d *Droidstubs) createApiContribution(ctx android.DefaultableHookContext) {
  713. api_file := d.properties.Check_api.Current.Api_file
  714. api_surface := d.properties.Api_surface
  715. props := struct {
  716. Name *string
  717. Api_surface *string
  718. Api_file *string
  719. Visibility []string
  720. }{}
  721. props.Name = proptools.StringPtr(d.Name() + ".api.contribution")
  722. props.Api_surface = api_surface
  723. props.Api_file = api_file
  724. props.Visibility = []string{"//visibility:override", "//visibility:public"}
  725. ctx.CreateModule(ApiContributionFactory, &props)
  726. }
  727. // TODO (b/262014796): Export the API contributions of CorePlatformApi
  728. // A map to populate the api surface of a droidstub from a substring appearing in its name
  729. // This map assumes that droidstubs (either checked-in or created by java_sdk_library)
  730. // use a strict naming convention
  731. var (
  732. droidstubsModuleNamingToSdkKind = map[string]android.SdkKind{
  733. //public is commented out since the core libraries use public in their java_sdk_library names
  734. "intracore": android.SdkIntraCore,
  735. "intra.core": android.SdkIntraCore,
  736. "system_server": android.SdkSystemServer,
  737. "system-server": android.SdkSystemServer,
  738. "system": android.SdkSystem,
  739. "module_lib": android.SdkModule,
  740. "module-lib": android.SdkModule,
  741. "platform.api": android.SdkCorePlatform,
  742. "test": android.SdkTest,
  743. "toolchain": android.SdkToolchain,
  744. }
  745. )
  746. // A helper function that returns the api surface of the corresponding java_api_contribution Bazel target
  747. // The api_surface is populated using the naming convention of the droidstubs module.
  748. func bazelApiSurfaceName(name string) string {
  749. // Sort the keys so that longer strings appear first
  750. // Otherwise substrings like system will match both system and system_server
  751. sortedKeys := make([]string, 0)
  752. for key := range droidstubsModuleNamingToSdkKind {
  753. sortedKeys = append(sortedKeys, key)
  754. }
  755. sort.Slice(sortedKeys, func(i, j int) bool {
  756. return len(sortedKeys[i]) > len(sortedKeys[j])
  757. })
  758. for _, sortedKey := range sortedKeys {
  759. if strings.Contains(name, sortedKey) {
  760. sdkKind := droidstubsModuleNamingToSdkKind[sortedKey]
  761. return sdkKind.String() + "api"
  762. }
  763. }
  764. // Default is publicapi
  765. return android.SdkPublic.String() + "api"
  766. }
  767. func StubsDefaultsFactory() android.Module {
  768. module := &DocDefaults{}
  769. module.AddProperties(
  770. &JavadocProperties{},
  771. &DroidstubsProperties{},
  772. )
  773. android.InitDefaultsModule(module)
  774. return module
  775. }
  776. var _ android.PrebuiltInterface = (*PrebuiltStubsSources)(nil)
  777. type PrebuiltStubsSourcesProperties struct {
  778. Srcs []string `android:"path"`
  779. }
  780. type PrebuiltStubsSources struct {
  781. android.ModuleBase
  782. android.DefaultableModuleBase
  783. prebuilt android.Prebuilt
  784. properties PrebuiltStubsSourcesProperties
  785. stubsSrcJar android.Path
  786. }
  787. func (p *PrebuiltStubsSources) OutputFiles(tag string) (android.Paths, error) {
  788. switch tag {
  789. case "":
  790. return android.Paths{p.stubsSrcJar}, nil
  791. default:
  792. return nil, fmt.Errorf("unsupported module reference tag %q", tag)
  793. }
  794. }
  795. func (d *PrebuiltStubsSources) StubsSrcJar() android.Path {
  796. return d.stubsSrcJar
  797. }
  798. func (p *PrebuiltStubsSources) GenerateAndroidBuildActions(ctx android.ModuleContext) {
  799. if len(p.properties.Srcs) != 1 {
  800. ctx.PropertyErrorf("srcs", "must only specify one directory path or srcjar, contains %d paths", len(p.properties.Srcs))
  801. return
  802. }
  803. src := p.properties.Srcs[0]
  804. if filepath.Ext(src) == ".srcjar" {
  805. // This is a srcjar. We can use it directly.
  806. p.stubsSrcJar = android.PathForModuleSrc(ctx, src)
  807. } else {
  808. outPath := android.PathForModuleOut(ctx, ctx.ModuleName()+"-"+"stubs.srcjar")
  809. // This is a directory. Glob the contents just in case the directory does not exist.
  810. srcGlob := src + "/**/*"
  811. srcPaths := android.PathsForModuleSrc(ctx, []string{srcGlob})
  812. // Although PathForModuleSrc can return nil if either the path doesn't exist or
  813. // the path components are invalid it won't in this case because no components
  814. // are specified and the module directory must exist in order to get this far.
  815. srcDir := android.PathForModuleSrc(ctx).(android.SourcePath).Join(ctx, src)
  816. rule := android.NewRuleBuilder(pctx, ctx)
  817. rule.Command().
  818. BuiltTool("soong_zip").
  819. Flag("-write_if_changed").
  820. Flag("-jar").
  821. FlagWithOutput("-o ", outPath).
  822. FlagWithArg("-C ", srcDir.String()).
  823. FlagWithRspFileInputList("-r ", outPath.ReplaceExtension(ctx, "rsp"), srcPaths)
  824. rule.Restat()
  825. rule.Build("zip src", "Create srcjar from prebuilt source")
  826. p.stubsSrcJar = outPath
  827. }
  828. }
  829. func (p *PrebuiltStubsSources) Prebuilt() *android.Prebuilt {
  830. return &p.prebuilt
  831. }
  832. func (p *PrebuiltStubsSources) Name() string {
  833. return p.prebuilt.Name(p.ModuleBase.Name())
  834. }
  835. // prebuilt_stubs_sources imports a set of java source files as if they were
  836. // generated by droidstubs.
  837. //
  838. // By default, a prebuilt_stubs_sources has a single variant that expects a
  839. // set of `.java` files generated by droidstubs.
  840. //
  841. // Specifying `host_supported: true` will produce two variants, one for use as a dependency of device modules and one
  842. // for host modules.
  843. //
  844. // Intended only for use by sdk snapshots.
  845. func PrebuiltStubsSourcesFactory() android.Module {
  846. module := &PrebuiltStubsSources{}
  847. module.AddProperties(&module.properties)
  848. android.InitPrebuiltModule(module, &module.properties.Srcs)
  849. InitDroiddocModule(module, android.HostAndDeviceSupported)
  850. return module
  851. }