[docs] Improve documentation around scopes
Specifically, mention that explicit scopes do not have parent
references.
Change-Id: Ie9b93c4c6299c6b29e45b1ca195094189737a9a7
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/12980
Reviewed-by: Brett Wilson <brettw@chromium.org>
Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/docs/reference.md b/docs/reference.md
index 922f1d9..566b3ed 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -124,6 +124,7 @@
* [framework_dirs: [directory list] Additional framework search directories.](#var_framework_dirs)
* [frameworks: [name list] Name of frameworks that must be linked.](#var_frameworks)
* [friend: [label pattern list] Allow targets to include private headers.](#var_friend)
+ * [gen_deps: [label list] Declares targets that should generate when this one does.](#var_gen_deps)
* [include_dirs: [directory list] Additional include directories.](#var_include_dirs)
* [inputs: [file list] Additional compile-time dependencies.](#var_inputs)
* [ldflags: [string list] Flags passed to the linker.](#var_ldflags)
@@ -777,6 +778,7 @@
"vs2015" - Visual Studio 2015 project/solution files.
"vs2017" - Visual Studio 2017 project/solution files.
"vs2019" - Visual Studio 2019 project/solution files.
+ "vs2022" - Visual Studio 2022 project/solution files.
"xcode" - Xcode workspace/solution files.
"qtcreator" - QtCreator project files.
"json" - JSON file containing target information
@@ -1013,17 +1015,18 @@
A list of target labels from which to initiate the walk.
--data
- A list of keys from which to extract data. In each target walked, its metadata
- scope is checked for the presence of these keys. If present, the contents of
- those variable in the scope are appended to the results list.
+ A comma-separated list of keys from which to extract data. In each target
+ walked, its metadata scope is checked for the presence of these keys. If
+ present, the contents of those variable in the scope are appended to the
+ results list.
--walk (optional)
- A list of keys from which to control the walk. In each target walked, its
- metadata scope is checked for the presence of any of these keys. If present,
- the contents of those variables is checked to ensure that it is a label of
- a valid dependency of the target and then added to the set of targets to walk.
- If the empty string ("") is present in any of these keys, all deps and data_deps
- are added to the walk set.
+ A comma-separated list of keys from which to control the walk. In each
+ target walked, its metadata scope is checked for the presence of any of
+ these keys. If present, the contents of those variables is checked to ensure
+ that it is a label of a valid dependency of the target and then added to the
+ set of targets to walk. If the empty string ("") is present in any of these
+ keys, all deps and data_deps are added to the walk set.
--rebase (optional)
A destination directory onto which to rebase any paths found. If set, all
@@ -1038,7 +1041,7 @@
Lists collected metaresults for the `files` key in the //base/foo:foo
target and all of its dependency tree.
- gn meta out/Debug "//base/foo" --data=files --data=other
+ gn meta out/Debug "//base/foo" --data=files,other
Lists collected metaresults for the `files` and `other` keys in the
//base/foo:foo target and all of its dependency tree.
@@ -1731,7 +1734,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -1925,7 +1928,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -1957,7 +1960,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -1992,7 +1995,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -2026,7 +2029,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -2071,7 +2074,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -2095,7 +2098,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
@@ -2204,7 +2207,7 @@
Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,
asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,
libs, precompiled_header, precompiled_source, rustflags,
- rustenv, swiftflags
+ rustenv, swiftflags, testonly
Nested configs: configs
General: visibility
```
@@ -4377,6 +4380,13 @@
- "arm"
- "arm64"
- "mipsel"
+ - "mips64el"
+ - "s390x"
+ - "ppc64"
+ - "riscv32"
+ - "riscv64"
+ - "e2k"
+ - "loong64"
```
### <a name="var_target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files.
@@ -5583,6 +5593,18 @@
]
}
```
+### <a name="var_gen_deps"></a>**gen_deps**: Declares targets that should generate when this one does.
+
+```
+ A list of target labels.
+
+ Not all GN targets that get evaluated are actually turned into ninja targets
+ (see "gn help execution"). If this target is generated, then any targets in
+ the "gen_deps" list will also be generated, regardless of the usual critera.
+
+ Since "gen_deps" are not build time dependencies, there can be cycles between
+ "deps" and "gen_deps" or within "gen_deps" itself.
+```
### <a name="var_include_dirs"></a>**include_dirs**: Additional include directories.
```
@@ -6903,6 +6925,13 @@
required (directly or transitively) to build a target in the default
toolchain.
+ Some targets might be associated but without a formal build dependency (for
+ example, related tools or optional variants). A target that is marked as
+ "generated" can propagate its generated state to an associated target using
+ "gen_deps". This will make the referenced dependency have Ninja rules
+ generated in the same cases the source target has but without a build-time
+ dependency and even in non-default toolchains.
+
See also "gn help ninja_rules".
```
@@ -7109,19 +7138,20 @@
```
All execution happens in the context of a scope which holds the current state
(like variables). With the exception of loops and conditions, '{' introduces
- a new scope that has a parent reference to the old scope.
+ a new scope.
- Variable reads recursively search all nested scopes until the variable is
- found or there are no more scopes. Variable writes always go into the current
- scope. This means that after the closing '}' (again excepting loops and
- conditions), all local variables will be restored to the previous values.
- This also means that "foo = foo" can do useful work by copying a variable
- into the current scope that was defined in a containing scope.
+ Most scopes have a parent reference to the old scope. Variable reads
+ recursively search all parent scopes until the variable is found or there are
+ no more scopes. Variable writes always go into the current scope. This means
+ that after the closing '}' (again excepting loops and conditions), all local
+ variables will be restored to the previous values. This also means that "foo
+ = foo" can do useful work by copying a variable into the current scope that
+ was defined in a containing scope.
- Scopes can also be assigned to variables. Such scopes can be created by
- functions like exec_script, when invoking a template (the template code
- refers to the variables set by the invoking code by the implicitly-created
- "invoker" scope), or explicitly like:
+ Scopes can be assigned to variables. Examples of such scopes are the
+ implicitly-created "invoker" when invoking a template (which refers to the
+ variables set by the invoking code), scopes created by functions like
+ exec_script, and scopes explicitly created like
empty_scope = {}
myvalues = {
@@ -7129,10 +7159,14 @@
bar = "something"
}
- Inside such a scope definition can be any GN code including conditionals and
- function calls. After the close of the scope, it will contain all variables
- explicitly set by the code contained inside it. After this, the values can be
- read, modified, or added to:
+ In the case of explicitly created scopes and scopes created by functions like
+ exec_script, there is no reference to the parent scope. Such scopes are fully
+ self-contained and do not "inherit" values from their defining scope.
+
+ Inside an explicit scope definition can be any GN code including conditionals
+ and function calls. After the close of the scope, it will contain all
+ variables explicitly set by the code contained inside it. After this, the
+ values can be read, modified, or added to:
myvalues.foo += 2
empty_scope.new_thing = [ 1, 2, 3 ]
diff --git a/src/gn/parser.cc b/src/gn/parser.cc
index a4ad244..96739a5 100644
--- a/src/gn/parser.cc
+++ b/src/gn/parser.cc
@@ -181,19 +181,20 @@
All execution happens in the context of a scope which holds the current state
(like variables). With the exception of loops and conditions, '{' introduces
- a new scope that has a parent reference to the old scope.
+ a new scope.
- Variable reads recursively search all nested scopes until the variable is
- found or there are no more scopes. Variable writes always go into the current
- scope. This means that after the closing '}' (again excepting loops and
- conditions), all local variables will be restored to the previous values.
- This also means that "foo = foo" can do useful work by copying a variable
- into the current scope that was defined in a containing scope.
+ Most scopes have a parent reference to the old scope. Variable reads
+ recursively search all parent scopes until the variable is found or there are
+ no more scopes. Variable writes always go into the current scope. This means
+ that after the closing '}' (again excepting loops and conditions), all local
+ variables will be restored to the previous values. This also means that "foo
+ = foo" can do useful work by copying a variable into the current scope that
+ was defined in a containing scope.
- Scopes can also be assigned to variables. Such scopes can be created by
- functions like exec_script, when invoking a template (the template code
- refers to the variables set by the invoking code by the implicitly-created
- "invoker" scope), or explicitly like:
+ Scopes can be assigned to variables. Examples of such scopes are the
+ implicitly-created "invoker" when invoking a template (which refers to the
+ variables set by the invoking code), scopes created by functions like
+ exec_script, and scopes explicitly created like
empty_scope = {}
myvalues = {
@@ -201,10 +202,14 @@
bar = "something"
}
- Inside such a scope definition can be any GN code including conditionals and
- function calls. After the close of the scope, it will contain all variables
- explicitly set by the code contained inside it. After this, the values can be
- read, modified, or added to:
+ In the case of explicitly created scopes and scopes created by functions like
+ exec_script, there is no reference to the parent scope. Such scopes are fully
+ self-contained and do not "inherit" values from their defining scope.
+
+ Inside an explicit scope definition can be any GN code including conditionals
+ and function calls. After the close of the scope, it will contain all
+ variables explicitly set by the code contained inside it. After this, the
+ values can be read, modified, or added to:
myvalues.foo += 2
empty_scope.new_thing = [ 1, 2, 3 ]
