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/*" |