tools/gn/docs/check.md

   1 # GN Check
   2
   3 GN has several different ways to check dependencies. Many of them are checked by
   4 the `gn check` command. Running checks involve opening and scanning all source
   5 files so this isn't run every time a build is updated. To run check on an
   6 existing build:
   7
   8     gn check out/mybuild
   9
  10 To run the check as part of the "gen" command to update the build (this is what
  11 the bots do):
  12
  13     gn gen out/mybuild --check
  14
  15 [TOC]
  16
  17 ## Concepts
  18
  19 ### Visibility
  20
  21 Targets can control which other targets may depend on them by specifying
  22 `visibility`. Visibility is always checked when running any GN command (not just
  23 `gn check`.
  24
  25 By default, targets are "public" meaning any target can depend on them. If you
  26 supply a list, visibility will be listed to those targets (possibly including
  27 wildcards):
  28
  29 ```
  30 visibility = [
  31   ":*",  # All targets in this file.
  32   "//content/*",  # All targets in content and any subdirectory thereof.
  33   "//tools:doom_melon",  # This specific target.
  34 ]
  35 ```
  36
  37 See `gn help visibility` for more details and examples.
  38
  39 ### Public header files
  40
  41 Targets can control which headers may be included by dependent targets so as to
  42 define a public API. If your target specifies only `sources`, then all headers
  43 listed there are public and can be included by all dependents.
  44
  45 If your target defines a `public` variable, only the files listed in that list
  46 will be public. Files in `sources` but not `public` (they can be in both or only
  47 one) may not be included by dependent targets.
  48
  49 ```
  50 source_set("foo") {
  51   public = [
  52     "foo.h",
  53     "foo_config.h",
  54   ]
  55   sources = [
  56     "foo.cc",
  57     "foo.h",
  58     "bar.cc",
  59     "bar.h",
  60   ]
  61 }
  62 ```
  63
  64 ### Public dependencies
  65
  66 In order to include files from your target, that target must be listed in your
  67 target's dependencies. By default, transitively depending on a target doesn't
  68 give your files this privilege.
  69
  70 If a target exposes a dependency as part of its public API, then it can list
  71 that dependency as a `public_deps`:
  72
  73 ```
  74 source_set("foo") {
  75   sources = [ ... ]
  76   public_deps = [
  77     "//base",
  78   ]
  79   deps = [
  80     "//tools/doom_melon",
  81   ]
  82 }
  83 ```
  84
  85 Targets that depend on `foo` can include files from `base` but not from
  86 `doom_melon`. To include public headers from `doom\_melon, a target would need
  87 to depend directly on it.
  88
  89 Public dependencies work transitively, so listing a target as a public
  90 dependency also exposes that target's public dependencies. Along with the
  91 ability to include headers, public dependencies forward the `public_configs`
  92 which allow settings like defines and include directories to apply to
  93 dependents.
  94
  95 ## Putting it all together
  96
  97 In order to include a header from target Y in a file that is part of target X:
  98
  99 *   X must be in Y's `visibility` list (or B must have no `visibility` defined).
 100 *   The header must be in Y's `public` headers (or Y must have no `public`
 101     variable defined).
 102 *   X must depend directly on Y, or there must be a path from X to Y following
 103     only public dependencies.
 104
 105 ### What gets checked
 106
 107 Chrome currently doesn't come close to passing a `gn check` pass. You can check
 108 specific targets or subtrees for issues:
 109
 110     gn check out/mybuild //base
 111
 112     gn check out/mybuild "//mojo/*"