docs/gn_check.md

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