visibility.go 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621
  1. // Copyright 2019 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 android
  15. import (
  16. "fmt"
  17. "regexp"
  18. "sort"
  19. "strings"
  20. "sync"
  21. "github.com/google/blueprint"
  22. )
  23. // Enforces visibility rules between modules.
  24. //
  25. // Multi stage process:
  26. // * First stage works bottom up, before defaults expansion, to check the syntax of the visibility
  27. // rules that have been specified.
  28. //
  29. // * Second stage works bottom up to extract the package info for each package and store them in a
  30. // map by package name. See package.go for functionality for this.
  31. //
  32. // * Third stage works bottom up to extract visibility information from the modules, parse it,
  33. // create visibilityRule structures and store them in a map keyed by the module's
  34. // qualifiedModuleName instance, i.e. //<pkg>:<name>. The map is stored in the context rather
  35. // than a global variable for testing. Each test has its own Config so they do not share a map
  36. // and so can be run in parallel. If a module has no visibility specified then it uses the
  37. // default package visibility if specified.
  38. //
  39. // * Fourth stage works top down and iterates over all the deps for each module. If the dep is in
  40. // the same package then it is automatically visible. Otherwise, for each dep it first extracts
  41. // its visibilityRule from the config map. If one could not be found then it assumes that it is
  42. // publicly visible. Otherwise, it calls the visibility rule to check that the module can see
  43. // the dependency. If it cannot then an error is reported.
  44. //
  45. // TODO(b/130631145) - Make visibility work properly with prebuilts.
  46. // Patterns for the values that can be specified in visibility property.
  47. const (
  48. packagePattern = `//([^/:]+(?:/[^/:]+)*)`
  49. namePattern = `:([^/:]+)`
  50. visibilityRulePattern = `^(?:` + packagePattern + `)?(?:` + namePattern + `)?$`
  51. )
  52. var visibilityRuleRegexp = regexp.MustCompile(visibilityRulePattern)
  53. // A visibility rule is associated with a module and determines which other modules it is visible
  54. // to, i.e. which other modules can depend on the rule's module.
  55. type visibilityRule interface {
  56. // Check to see whether this rules matches m.
  57. // Returns true if it does, false otherwise.
  58. matches(m qualifiedModuleName) bool
  59. String() string
  60. }
  61. // Describes the properties provided by a module that contain visibility rules.
  62. type visibilityPropertyImpl struct {
  63. name string
  64. stringsProperty *[]string
  65. }
  66. type visibilityProperty interface {
  67. getName() string
  68. getStrings() []string
  69. }
  70. func newVisibilityProperty(name string, stringsProperty *[]string) visibilityProperty {
  71. return visibilityPropertyImpl{
  72. name: name,
  73. stringsProperty: stringsProperty,
  74. }
  75. }
  76. func (p visibilityPropertyImpl) getName() string {
  77. return p.name
  78. }
  79. func (p visibilityPropertyImpl) getStrings() []string {
  80. return *p.stringsProperty
  81. }
  82. // A compositeRule is a visibility rule composed from a list of atomic visibility rules.
  83. //
  84. // The list corresponds to the list of strings in the visibility property after defaults expansion.
  85. // Even though //visibility:public is not allowed together with other rules in the visibility list
  86. // of a single module, it is allowed here to permit a module to override an inherited visibility
  87. // spec with public visibility.
  88. //
  89. // //visibility:private is not allowed in the same way, since we'd need to check for it during the
  90. // defaults expansion to make that work. No non-private visibility rules are allowed in a
  91. // compositeRule containing a privateRule.
  92. //
  93. // This array will only be [] if all the rules are invalid and will behave as if visibility was
  94. // ["//visibility:private"].
  95. type compositeRule []visibilityRule
  96. // A compositeRule matches if and only if any of its rules matches.
  97. func (c compositeRule) matches(m qualifiedModuleName) bool {
  98. for _, r := range c {
  99. if r.matches(m) {
  100. return true
  101. }
  102. }
  103. return false
  104. }
  105. func (c compositeRule) String() string {
  106. return "[" + strings.Join(c.Strings(), ", ") + "]"
  107. }
  108. func (c compositeRule) Strings() []string {
  109. s := make([]string, 0, len(c))
  110. for _, r := range c {
  111. s = append(s, r.String())
  112. }
  113. return s
  114. }
  115. // A packageRule is a visibility rule that matches modules in a specific package (i.e. directory).
  116. type packageRule struct {
  117. pkg string
  118. }
  119. func (r packageRule) matches(m qualifiedModuleName) bool {
  120. return m.pkg == r.pkg
  121. }
  122. func (r packageRule) String() string {
  123. return fmt.Sprintf("//%s", r.pkg) // :__pkg__ is the default, so skip it.
  124. }
  125. // A subpackagesRule is a visibility rule that matches modules in a specific package (i.e.
  126. // directory) or any of its subpackages (i.e. subdirectories).
  127. type subpackagesRule struct {
  128. pkgPrefix string
  129. }
  130. func (r subpackagesRule) matches(m qualifiedModuleName) bool {
  131. return isAncestor(r.pkgPrefix, m.pkg)
  132. }
  133. func isAncestor(p1 string, p2 string) bool {
  134. // Equivalent to strings.HasPrefix(p2+"/", p1+"/"), but without the string copies
  135. // The check for a trailing slash is so that we don't consider sibling
  136. // directories with common prefixes to be ancestors, e.g. "fooo/bar" should not be
  137. // a descendant of "foo".
  138. return strings.HasPrefix(p2, p1) && (len(p2) == len(p1) || p2[len(p1)] == '/')
  139. }
  140. func (r subpackagesRule) String() string {
  141. return fmt.Sprintf("//%s:__subpackages__", r.pkgPrefix)
  142. }
  143. // visibilityRule for //visibility:public
  144. type publicRule struct{}
  145. func (r publicRule) matches(_ qualifiedModuleName) bool {
  146. return true
  147. }
  148. func (r publicRule) String() string {
  149. return "//visibility:public"
  150. }
  151. // visibilityRule for //visibility:private
  152. type privateRule struct{}
  153. func (r privateRule) matches(_ qualifiedModuleName) bool {
  154. return false
  155. }
  156. func (r privateRule) String() string {
  157. return "//visibility:private"
  158. }
  159. var visibilityRuleMap = NewOnceKey("visibilityRuleMap")
  160. // The map from qualifiedModuleName to visibilityRule.
  161. func moduleToVisibilityRuleMap(config Config) *sync.Map {
  162. return config.Once(visibilityRuleMap, func() interface{} {
  163. return &sync.Map{}
  164. }).(*sync.Map)
  165. }
  166. // Marker interface that identifies dependencies that are excluded from visibility
  167. // enforcement.
  168. type ExcludeFromVisibilityEnforcementTag interface {
  169. blueprint.DependencyTag
  170. // Method that differentiates this interface from others.
  171. ExcludeFromVisibilityEnforcement()
  172. }
  173. // The visibility mutators.
  174. var PrepareForTestWithVisibility = FixtureRegisterWithContext(registerVisibilityMutators)
  175. func registerVisibilityMutators(ctx RegistrationContext) {
  176. ctx.PreArchMutators(RegisterVisibilityRuleChecker)
  177. ctx.PreArchMutators(RegisterVisibilityRuleGatherer)
  178. ctx.PostDepsMutators(RegisterVisibilityRuleEnforcer)
  179. }
  180. // The rule checker needs to be registered before defaults expansion to correctly check that
  181. // //visibility:xxx isn't combined with other packages in the same list in any one module.
  182. func RegisterVisibilityRuleChecker(ctx RegisterMutatorsContext) {
  183. ctx.BottomUp("visibilityRuleChecker", visibilityRuleChecker).Parallel()
  184. }
  185. // Registers the function that gathers the visibility rules for each module.
  186. //
  187. // Visibility is not dependent on arch so this must be registered before the arch phase to avoid
  188. // having to process multiple variants for each module. This goes after defaults expansion to gather
  189. // the complete visibility lists from flat lists and after the package info is gathered to ensure
  190. // that default_visibility is available.
  191. func RegisterVisibilityRuleGatherer(ctx RegisterMutatorsContext) {
  192. ctx.BottomUp("visibilityRuleGatherer", visibilityRuleGatherer).Parallel()
  193. }
  194. // This must be registered after the deps have been resolved.
  195. func RegisterVisibilityRuleEnforcer(ctx RegisterMutatorsContext) {
  196. ctx.TopDown("visibilityRuleEnforcer", visibilityRuleEnforcer).Parallel()
  197. }
  198. // Checks the per-module visibility rule lists before defaults expansion.
  199. func visibilityRuleChecker(ctx BottomUpMutatorContext) {
  200. qualified := createQualifiedModuleName(ctx.ModuleName(), ctx.ModuleDir())
  201. if m, ok := ctx.Module().(Module); ok {
  202. visibilityProperties := m.visibilityProperties()
  203. for _, p := range visibilityProperties {
  204. if visibility := p.getStrings(); visibility != nil {
  205. checkRules(ctx, qualified.pkg, p.getName(), visibility)
  206. }
  207. }
  208. }
  209. }
  210. func checkRules(ctx BaseModuleContext, currentPkg, property string, visibility []string) {
  211. ruleCount := len(visibility)
  212. if ruleCount == 0 {
  213. // This prohibits an empty list as its meaning is unclear, e.g. it could mean no visibility and
  214. // it could mean public visibility. Requiring at least one rule makes the owner's intent
  215. // clearer.
  216. ctx.PropertyErrorf(property, "must contain at least one visibility rule")
  217. return
  218. }
  219. for i, v := range visibility {
  220. ok, pkg, name := splitRule(ctx, v, currentPkg, property)
  221. if !ok {
  222. continue
  223. }
  224. if pkg == "visibility" {
  225. switch name {
  226. case "private", "public":
  227. case "legacy_public":
  228. ctx.PropertyErrorf(property, "//visibility:legacy_public must not be used")
  229. continue
  230. case "override":
  231. // This keyword does not create a rule so pretend it does not exist.
  232. ruleCount -= 1
  233. default:
  234. ctx.PropertyErrorf(property, "unrecognized visibility rule %q", v)
  235. continue
  236. }
  237. if name == "override" {
  238. if i != 0 {
  239. ctx.PropertyErrorf(property, `"%v" may only be used at the start of the visibility rules`, v)
  240. }
  241. } else if ruleCount != 1 {
  242. ctx.PropertyErrorf(property, "cannot mix %q with any other visibility rules", v)
  243. continue
  244. }
  245. }
  246. // If the current directory is not in the vendor tree then there are some additional
  247. // restrictions on the rules.
  248. if !isAncestor("vendor", currentPkg) {
  249. if !isAllowedFromOutsideVendor(pkg, name) {
  250. ctx.PropertyErrorf(property,
  251. "%q is not allowed. Packages outside //vendor cannot make themselves visible to specific"+
  252. " targets within //vendor, they can only use //vendor:__subpackages__.", v)
  253. continue
  254. }
  255. }
  256. }
  257. }
  258. // Gathers the flattened visibility rules after defaults expansion, parses the visibility
  259. // properties, stores them in a map by qualifiedModuleName for retrieval during enforcement.
  260. //
  261. // See ../README.md#Visibility for information on the format of the visibility rules.
  262. func visibilityRuleGatherer(ctx BottomUpMutatorContext) {
  263. m, ok := ctx.Module().(Module)
  264. if !ok {
  265. return
  266. }
  267. qualifiedModuleId := m.qualifiedModuleId(ctx)
  268. currentPkg := qualifiedModuleId.pkg
  269. // Parse the visibility rules that control access to the module and store them by id
  270. // for use when enforcing the rules.
  271. primaryProperty := m.base().primaryVisibilityProperty
  272. if primaryProperty != nil {
  273. if visibility := primaryProperty.getStrings(); visibility != nil {
  274. rule := parseRules(ctx, currentPkg, primaryProperty.getName(), visibility)
  275. if rule != nil {
  276. moduleToVisibilityRuleMap(ctx.Config()).Store(qualifiedModuleId, rule)
  277. }
  278. }
  279. }
  280. }
  281. func parseRules(ctx BaseModuleContext, currentPkg, property string, visibility []string) compositeRule {
  282. rules := make(compositeRule, 0, len(visibility))
  283. hasPrivateRule := false
  284. hasPublicRule := false
  285. hasNonPrivateRule := false
  286. for _, v := range visibility {
  287. ok, pkg, name := splitRule(ctx, v, currentPkg, property)
  288. if !ok {
  289. continue
  290. }
  291. var r visibilityRule
  292. isPrivateRule := false
  293. if pkg == "visibility" {
  294. switch name {
  295. case "private":
  296. r = privateRule{}
  297. isPrivateRule = true
  298. case "public":
  299. r = publicRule{}
  300. hasPublicRule = true
  301. case "override":
  302. // Discard all preceding rules and any state based on them.
  303. rules = nil
  304. hasPrivateRule = false
  305. hasPublicRule = false
  306. hasNonPrivateRule = false
  307. // This does not actually create a rule so continue onto the next rule.
  308. continue
  309. }
  310. } else {
  311. switch name {
  312. case "__pkg__":
  313. r = packageRule{pkg}
  314. case "__subpackages__":
  315. r = subpackagesRule{pkg}
  316. default:
  317. ctx.PropertyErrorf(property, "invalid visibility pattern %q. Must match "+
  318. " //<package>:<scope>, //<package> or :<scope> "+
  319. "where <scope> is one of \"__pkg__\", \"__subpackages__\"",
  320. v)
  321. }
  322. }
  323. if isPrivateRule {
  324. hasPrivateRule = true
  325. } else {
  326. hasNonPrivateRule = true
  327. }
  328. rules = append(rules, r)
  329. }
  330. if hasPrivateRule && hasNonPrivateRule {
  331. ctx.PropertyErrorf("visibility",
  332. "cannot mix \"//visibility:private\" with any other visibility rules")
  333. return compositeRule{privateRule{}}
  334. }
  335. if hasPublicRule {
  336. // Public overrides all other rules so just return it.
  337. return compositeRule{publicRule{}}
  338. }
  339. return rules
  340. }
  341. func isAllowedFromOutsideVendor(pkg string, name string) bool {
  342. if pkg == "vendor" {
  343. if name == "__subpackages__" {
  344. return true
  345. }
  346. return false
  347. }
  348. return !isAncestor("vendor", pkg)
  349. }
  350. func splitRule(ctx BaseModuleContext, ruleExpression string, currentPkg, property string) (bool, string, string) {
  351. // Make sure that the rule is of the correct format.
  352. matches := visibilityRuleRegexp.FindStringSubmatch(ruleExpression)
  353. if ruleExpression == "" || matches == nil {
  354. // Visibility rule is invalid so ignore it. Keep going rather than aborting straight away to
  355. // ensure all the rules on this module are checked.
  356. ctx.PropertyErrorf(property,
  357. "invalid visibility pattern %q must match"+
  358. " //<package>:<scope>, //<package> or :<scope> "+
  359. "where <scope> is one of \"__pkg__\", \"__subpackages__\"",
  360. ruleExpression)
  361. return false, "", ""
  362. }
  363. // Extract the package and name.
  364. pkg := matches[1]
  365. name := matches[2]
  366. // Normalize the short hands
  367. if pkg == "" {
  368. pkg = currentPkg
  369. }
  370. if name == "" {
  371. name = "__pkg__"
  372. }
  373. return true, pkg, name
  374. }
  375. func visibilityRuleEnforcer(ctx TopDownMutatorContext) {
  376. if _, ok := ctx.Module().(Module); !ok {
  377. return
  378. }
  379. qualified := createQualifiedModuleName(ctx.ModuleName(), ctx.ModuleDir())
  380. // Visit all the dependencies making sure that this module has access to them all.
  381. ctx.VisitDirectDeps(func(dep Module) {
  382. // Ignore dependencies that have an ExcludeFromVisibilityEnforcementTag
  383. tag := ctx.OtherModuleDependencyTag(dep)
  384. if _, ok := tag.(ExcludeFromVisibilityEnforcementTag); ok {
  385. return
  386. }
  387. depName := ctx.OtherModuleName(dep)
  388. depDir := ctx.OtherModuleDir(dep)
  389. depQualified := qualifiedModuleName{depDir, depName}
  390. // Targets are always visible to other targets in their own package.
  391. if depQualified.pkg == qualified.pkg {
  392. return
  393. }
  394. rule := effectiveVisibilityRules(ctx.Config(), depQualified)
  395. if !rule.matches(qualified) {
  396. ctx.ModuleErrorf("depends on %s which is not visible to this module\nYou may need to add %q to its visibility", depQualified, "//"+ctx.ModuleDir())
  397. }
  398. })
  399. }
  400. // Default visibility is public.
  401. var defaultVisibility = compositeRule{publicRule{}}
  402. // Return the effective visibility rules.
  403. //
  404. // If no rules have been specified this will return the default visibility rule
  405. // which is currently //visibility:public.
  406. func effectiveVisibilityRules(config Config, qualified qualifiedModuleName) compositeRule {
  407. moduleToVisibilityRule := moduleToVisibilityRuleMap(config)
  408. value, ok := moduleToVisibilityRule.Load(qualified)
  409. var rule compositeRule
  410. if ok {
  411. rule = value.(compositeRule)
  412. } else {
  413. rule = packageDefaultVisibility(config, qualified)
  414. }
  415. // If no rule is specified then return the default visibility rule to avoid
  416. // every caller having to treat nil as public.
  417. if rule == nil {
  418. rule = defaultVisibility
  419. }
  420. return rule
  421. }
  422. func createQualifiedModuleName(moduleName, dir string) qualifiedModuleName {
  423. qualified := qualifiedModuleName{dir, moduleName}
  424. return qualified
  425. }
  426. func packageDefaultVisibility(config Config, moduleId qualifiedModuleName) compositeRule {
  427. moduleToVisibilityRule := moduleToVisibilityRuleMap(config)
  428. packageQualifiedId := moduleId.getContainingPackageId()
  429. for {
  430. value, ok := moduleToVisibilityRule.Load(packageQualifiedId)
  431. if ok {
  432. return value.(compositeRule)
  433. }
  434. if packageQualifiedId.isRootPackage() {
  435. return nil
  436. }
  437. packageQualifiedId = packageQualifiedId.getContainingPackageId()
  438. }
  439. }
  440. type VisibilityRuleSet interface {
  441. // Widen the visibility with some extra rules.
  442. Widen(extra []string) error
  443. Strings() []string
  444. }
  445. type visibilityRuleSet struct {
  446. rules []string
  447. }
  448. var _ VisibilityRuleSet = (*visibilityRuleSet)(nil)
  449. func (v *visibilityRuleSet) Widen(extra []string) error {
  450. // Check the extra rules first just in case they are invalid. Otherwise, if
  451. // the current visibility is public then the extra rules will just be ignored.
  452. if len(extra) == 1 {
  453. singularRule := extra[0]
  454. switch singularRule {
  455. case "//visibility:public":
  456. // Public overrides everything so just discard any existing rules.
  457. v.rules = extra
  458. return nil
  459. case "//visibility:private":
  460. // Extending rule with private is an error.
  461. return fmt.Errorf("%q does not widen the visibility", singularRule)
  462. }
  463. }
  464. if len(v.rules) == 1 {
  465. switch v.rules[0] {
  466. case "//visibility:public":
  467. // No point in adding rules to something which is already public.
  468. return nil
  469. case "//visibility:private":
  470. // Adding any rules to private means it is no longer private so the
  471. // private can be discarded.
  472. v.rules = nil
  473. }
  474. }
  475. v.rules = FirstUniqueStrings(append(v.rules, extra...))
  476. sort.Strings(v.rules)
  477. return nil
  478. }
  479. func (v *visibilityRuleSet) Strings() []string {
  480. return v.rules
  481. }
  482. // Get the effective visibility rules, i.e. the actual rules that affect the visibility of the
  483. // property irrespective of where they are defined.
  484. //
  485. // Includes visibility rules specified by package default_visibility and/or on defaults.
  486. // Short hand forms, e.g. //:__subpackages__ are replaced with their full form, e.g.
  487. // //package/containing/rule:__subpackages__.
  488. func EffectiveVisibilityRules(ctx BaseModuleContext, module Module) VisibilityRuleSet {
  489. moduleName := ctx.OtherModuleName(module)
  490. dir := ctx.OtherModuleDir(module)
  491. qualified := qualifiedModuleName{dir, moduleName}
  492. rule := effectiveVisibilityRules(ctx.Config(), qualified)
  493. // Modules are implicitly visible to other modules in the same package,
  494. // without checking the visibility rules. Here we need to add that visibility
  495. // explicitly.
  496. if !rule.matches(qualified) {
  497. if len(rule) == 1 {
  498. if _, ok := rule[0].(privateRule); ok {
  499. // If the rule is //visibility:private we can't append another
  500. // visibility to it. Semantically we need to convert it to a package
  501. // visibility rule for the location where the result is used, but since
  502. // modules are implicitly visible within the package we get the same
  503. // result without any rule at all, so just make it an empty list to be
  504. // appended below.
  505. rule = nil
  506. }
  507. }
  508. rule = append(rule, packageRule{dir})
  509. }
  510. return &visibilityRuleSet{rule.Strings()}
  511. }
  512. // Clear the default visibility properties so they can be replaced.
  513. func clearVisibilityProperties(module Module) {
  514. module.base().visibilityPropertyInfo = nil
  515. }
  516. // Add a property that contains visibility rules so that they are checked for
  517. // correctness.
  518. func AddVisibilityProperty(module Module, name string, stringsProperty *[]string) {
  519. addVisibilityProperty(module, name, stringsProperty)
  520. }
  521. func addVisibilityProperty(module Module, name string, stringsProperty *[]string) visibilityProperty {
  522. base := module.base()
  523. property := newVisibilityProperty(name, stringsProperty)
  524. base.visibilityPropertyInfo = append(base.visibilityPropertyInfo, property)
  525. return property
  526. }
  527. // Set the primary visibility property.
  528. //
  529. // Also adds the property to the list of properties to be validated.
  530. func setPrimaryVisibilityProperty(module Module, name string, stringsProperty *[]string) {
  531. module.base().primaryVisibilityProperty = addVisibilityProperty(module, name, stringsProperty)
  532. }