| Index: docs/gn_check.md
|
| diff --git a/docs/gn_check.md b/docs/gn_check.md
|
| index c10e226a0b5181d1cd452b91645c7633ac3c22b7..e99f6a4879a0e1eaa8bf060db0eb3e88952858ba 100644
|
| --- a/docs/gn_check.md
|
| +++ b/docs/gn_check.md
|
| @@ -1,20 +1,30 @@
|
| -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:
|
| -```
|
| -gn check out/mybuild
|
| -```
|
| +# GN Check
|
|
|
| -To run the check as part of the "gen" command to update the build (this is what the bots do):
|
| -```
|
| -gn gen out/mybuild --check
|
| -```
|
| +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:
|
| +
|
| + gn check out/mybuild
|
| +
|
| +To run the check as part of the "gen" command to update the build (this is what
|
| +the bots do):
|
|
|
| -# Concepts
|
| + gn gen out/mybuild --check
|
|
|
| -## Visibility
|
| +[TOC]
|
|
|
| -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`.
|
| +## Concepts
|
|
|
| -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):
|
| +### Visibility
|
| +
|
| +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`.
|
| +
|
| +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):
|
|
|
| ```
|
| visibility = [
|
| @@ -26,11 +36,15 @@ visibility = [
|
|
|
| See `gn help visibility` for more details and examples.
|
|
|
| -## Public header files
|
| +### Public header files
|
|
|
| -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.
|
| +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.
|
|
|
| -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.
|
| +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.
|
|
|
| ```
|
| source_set("foo") {
|
| @@ -47,11 +61,15 @@ source_set("foo") {
|
| }
|
| ```
|
|
|
| -## Public dependencies
|
| +### Public dependencies
|
| +
|
| +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.
|
|
|
| -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.
|
| +If a target exposes a dependency as part of its public API, then it can list
|
| +that dependency as a `public_deps`:
|
|
|
| -If a target exposes a dependency as part of its public API, then it can list that dependency as a `public_deps`:
|
| ```
|
| source_set("foo") {
|
| sources = [ ... ]
|
| @@ -63,23 +81,32 @@ source_set("foo") {
|
| ]
|
| }
|
| ```
|
| -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.
|
|
|
| -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.
|
| +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.
|
|
|
| -# Putting it all together
|
| +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.
|
| +
|
| +## Putting it all together
|
|
|
| In order to include a header from target Y in a file that is part of target X:
|
|
|
| - * X must be in Y's `visibility` list (or B must have no `visibility` defined).
|
| - * The header must be in Y's `public` headers (or Y must have no `public` variable defined).
|
| - * X must depend directly on Y, or there must be a path from X to Y following only public dependencies.
|
| +* X must be in Y's `visibility` list (or B must have no `visibility` defined).
|
| +* The header must be in Y's `public` headers (or Y must have no `public`
|
| + variable defined).
|
| +* X must depend directly on Y, or there must be a path from X to Y following
|
| + only public dependencies.
|
|
|
| ### What gets checked
|
|
|
| -Chrome currently doesn't come close to passing a `gn check` pass. You can check specific targets or subtrees for issues:
|
| -```
|
| - gn check out/mybuild //base
|
| +Chrome currently doesn't come close to passing a `gn check` pass. You can check
|
| +specific targets or subtrees for issues:
|
| +
|
| + gn check out/mybuild //base
|
|
|
| - gn check out/mybuild "//mojo/*"
|
| -```
|
| + gn check out/mybuild "//mojo/*"
|
|
|