[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 ]