Add better target flag documentation.
Some target types were missing documentation on the flags they
supported, and some used their own list rather than the shared macros
that help defining them. This patch unifies the flag documentation.
There is no behavior change.
Change-Id: I54c82dbabf9cc33713d3b6b856bb20169d091ef6
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/13760
Reviewed-by: Takuto Ikuta <tikuta@google.com>
Reviewed-by: David Turner <digit@google.com>
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 51dcecc..2aba497 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -1360,11 +1360,20 @@
#### **Variables**
```
- args, asmflags, bridge_header, cflags, cflags_c, cflags_cc, cflags_objc,
- cflags_objcc, configs, data, data_deps, defines, depfile, deps,
- framework_dirs, include_dirs, inputs, metadata, module_deps, module_name,
- outputs*, pool, response_file_contents, rustenv, rustflags, script*, sources,
- swiftflags
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Dependent configs: all_dependent_configs, public_configs
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+ Action variables: args, bridge_header, configs, data, depfile,
+ framework_dirs, inputs, module_deps, module_name,
+ outputs*, pool, response_file_contents, script*,
+ sources
* = required
```
@@ -1452,11 +1461,21 @@
#### **Variables**
```
- args, asmflags, bridge_header, cflags, cflags_c, cflags_cc, cflags_objc,
- cflags_objcc, configs, data, data_deps, defines, depfile, deps,
- framework_dirs, include_dirs, inputs, metadata, module_deps, module_name,
- outputs*, pool, response_file_contents, rustenv, rustflags, script*, sources,
- swiftflags
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Dependent configs: all_dependent_configs, public_configs
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+ Action variables: args, bridge_header, configs, data, depfile,
+ framework_dirs, inputs, module_deps, module_name,
+ outputs*, pool, response_file_contents, script*,
+ sources
+ * = required
```
#### **Example**
@@ -1507,7 +1526,13 @@
#### **Variables**
```
- sources*, outputs*, deps, data_deps, metadata, public_deps, visibility
+ Dependent configs: all_dependent_configs, public_configs
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+ Bundle-specific: sources*, outputs*
* = required
```
@@ -1557,6 +1582,23 @@
mapping from each source file to an output file name using source expansion
(see "gn help source_expansion"). The placeholders will look like
"{{source_name_part}}", for example.
+
+ If you want to copy the output of a previous build step, the target that
+ generates the file to copy must be reachable from the deps or public_deps of
+ the copy target.
+```
+
+#### **Variables**
+
+```
+ Dependent configs: all_dependent_configs, public_configs
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+ Copy variables: sources*, outputs*
+ * = required
```
#### **Examples**
@@ -1576,6 +1618,24 @@
# names in the gen dir. This will just copy each file.
outputs = [ "$target_gen_dir/{{source_file_part}}" ]
}
+
+ # Copy the output of a generated executable.
+ copy("package_melon") {
+ # This example uses get_label_info() to compute the output directory of the
+ # dependency. This allows the copy rule to work regardless of the toolchain.
+ #
+ # In some cases (particularly actions defined previously in the same file)
+ # you can use get_target_outputs() to get the input file which can eliminate
+ # the assumptions about the output file name of the dependency.
+
+ input_dir = get_label_info("//src/tools/melon", "root_out_dir");
+ sources = [ "$input_dir/melon" ]
+
+ outputs = [ "$target_gen_dir/{{source_file_part}}" ]
+
+ # Depend on the target to build the file before copying.
+ deps = [ "//src/tools/melon" ]
+ }
```
### <a name="func_create_bundle"></a>**create_bundle**: [ios/macOS] Build an iOS or macOS bundle.
@@ -1621,11 +1681,17 @@
#### **Variables**
```
- bundle_root_dir, bundle_contents_dir, bundle_resources_dir,
- bundle_executable_dir, bundle_deps_filter, deps, data_deps, public_deps,
- visibility, product_type, code_signing_args, code_signing_script,
- code_signing_sources, code_signing_outputs, xcode_extra_attributes,
- xcode_test_application_name, partial_info_plist, metadata
+ Dependent configs: all_dependent_configs, public_configs
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+ Bundle vars: bundle_root_dir, bundle_contents_dir, bundle_resources_dir,
+ bundle_executable_dir, bundle_deps_filter, product_type,
+ code_signing_args, code_signing_script, code_signing_sources,
+ code_signing_outputs, xcode_extra_attributes,
+ xcode_test_application_name, partial_info_plist
```
#### **Example**
@@ -1742,14 +1808,15 @@
#### **Variables**
```
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
Rust variables: aliased_deps, crate_root, crate_name
```
@@ -1777,6 +1844,18 @@
dependencies. See the example for details.
```
+#### **Variables**
+
+```
+ Dependent configs: all_dependent_configs, public_configs
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+ Generated file: contents, data_keys, rebase, walk_keys, output_conversion
+```
+
#### **Example (metadata collection)**
```
@@ -1874,18 +1953,6 @@
"../base/foo.cpp", // from //base:a
]
```
-
-#### **Variables**
-
-```
- contents
- data_keys
- rebase
- walk_keys
- output_conversion
- Deps: data_deps, deps, public_deps
- Dependent configs: all_dependent_configs, public_configs
-```
### <a name="func_group"></a>**group**: Declare a named group of targets.
```
@@ -1897,8 +1964,12 @@
#### **Variables**
```
- Deps: data_deps, deps, public_deps
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
```
#### **Example**
@@ -1936,14 +2007,15 @@
#### **Variables**
```
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
Rust variables: aliased_deps, crate_root, crate_name, crate_type
```
@@ -1968,14 +2040,15 @@
#### **Variables**
```
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
Rust variables: aliased_deps, crate_root, crate_name
```
@@ -2003,14 +2076,15 @@
#### **Variables**
```
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
Rust variables: aliased_deps, crate_root, crate_name
```
@@ -2037,14 +2111,15 @@
#### **Variables**
```
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
Rust variables: aliased_deps, crate_root, crate_name, crate_type
```
@@ -2082,14 +2157,15 @@
#### **Variables**
```
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
```
### <a name="func_static_library"></a>**static_library**: Declare a static library target.
@@ -2106,14 +2182,15 @@
```
complete_static_lib
- 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, testonly
- Deps: data_deps, deps, public_deps
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
Dependent configs: all_dependent_configs, public_configs
General: check_includes, configs, data, friend, inputs, metadata,
- output_name, output_extension, public, sources, testonly,
+ output_extension, output_name, public, sources, testonly,
visibility
Rust variables: aliased_deps, crate_root, crate_name
@@ -2142,6 +2219,20 @@
source_set("doom_melon") {
```
+#### **Common target variables**
+
+```
+ Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,
+ write_runtime_deps
+ Dependent configs: all_dependent_configs, public_configs
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_extension, output_name, public, sources, testonly,
+ visibility
+
+ Targets will also have variables specific to that type, see "gn help <type>"
+ for more.
+```
+
#### **Example**
```
@@ -2215,10 +2306,10 @@
#### **Variables valid in a config definition**
```
- 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, testonly
+ Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,
+ cflags_objcc, defines, include_dirs, inputs, ldflags,
+ lib_dirs, libs, precompiled_header, precompiled_source,
+ rustenv, rustflags, swiftflags, testonly
Nested configs: configs
General: visibility
```
@@ -6814,12 +6905,14 @@
help --root-target").
script_executable [optional]
- Path to specific Python executable or other interpreter to use in
- action targets and exec_script calls. By default GN searches the
- PATH for Python to execute these scripts.
+ By default, GN runs the scripts used in action targets and exec_script
+ calls using the Python interpreter found in PATH. This value specifies the
+ Python executable or other interpreter to use instead.
- If set to the empty string, the path specified in action targets
- and exec_script calls will be executed directly.
+ If set to the empty string, the scripts will be executed directly.
+
+ The command-line switch --script-executable will override this value (see
+ "gn help --script-executable")
secondary_source [optional]
Label of an alternate directory tree to find input files. When searching
diff --git a/src/gn/config_values_generator.h b/src/gn/config_values_generator.h
index d006140..ff9cd03 100644
--- a/src/gn/config_values_generator.h
+++ b/src/gn/config_values_generator.h
@@ -37,10 +37,10 @@
};
// For using in documentation for functions which use this.
-#define CONFIG_VALUES_VARS_HELP \
- " Flags: cflags, cflags_c, cflags_cc, cflags_objc, cflags_objcc,\n" \
- " asmflags, defines, include_dirs, inputs, ldflags, lib_dirs,\n" \
- " libs, precompiled_header, precompiled_source, rustflags,\n" \
- " rustenv, swiftflags, testonly\n"
+#define CONFIG_VALUES_VARS_HELP \
+ " Flags: asmflags, cflags, cflags_c, cflags_cc, cflags_objc,\n" \
+ " cflags_objcc, defines, include_dirs, inputs, ldflags,\n" \
+ " lib_dirs, libs, precompiled_header, precompiled_source,\n" \
+ " rustenv, rustflags, swiftflags, testonly\n"
#endif // TOOLS_GN_CONFIG_VALUES_GENERATOR_H_
diff --git a/src/gn/functions_target.cc b/src/gn/functions_target.cc
index 74f53e9..8c8613c 100644
--- a/src/gn/functions_target.cc
+++ b/src/gn/functions_target.cc
@@ -15,15 +15,22 @@
#define DEPENDENT_CONFIG_VARS \
" Dependent configs: all_dependent_configs, public_configs\n"
-#define DEPS_VARS " Deps: data_deps, deps, public_deps\n"
+#define DEPS_VARS \
+ " Deps: assert_no_deps, data_deps, deps, public_deps, runtime_deps,\n" \
+ " write_runtime_deps\n"
#define GENERAL_TARGET_VARS \
" General: check_includes, configs, data, friend, inputs, metadata,\n" \
- " output_name, output_extension, public, sources, testonly,\n" \
+ " output_extension, output_name, public, sources, testonly,\n" \
" visibility\n"
#define RUST_VARS \
" Rust variables: aliased_deps, crate_root, crate_name\n"
#define RUST_SHARED_VARS \
" Rust variables: aliased_deps, crate_root, crate_name, crate_type\n"
+#define ACTION_VARS \
+ " Action variables: args, bridge_header, configs, data, depfile,\n" \
+ " framework_dirs, inputs, module_deps, module_name,\n" \
+ " outputs*, pool, response_file_contents, script*,\n" \
+ " sources\n"
namespace functions {
@@ -166,12 +173,10 @@
R"(
Variables
- args, asmflags, bridge_header, cflags, cflags_c, cflags_cc, cflags_objc,
- cflags_objcc, configs, data, data_deps, defines, depfile, deps,
- framework_dirs, include_dirs, inputs, metadata, module_deps, module_name,
- outputs*, pool, response_file_contents, rustenv, rustflags, script*, sources,
- swiftflags
- * = required
+)" CONFIG_VALUES_VARS_HELP DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS
+ACTION_VARS
+
+R"( * = required
Example
@@ -239,11 +244,10 @@
R"(
Variables
- args, asmflags, bridge_header, cflags, cflags_c, cflags_cc, cflags_objc,
- cflags_objcc, configs, data, data_deps, defines, depfile, deps,
- framework_dirs, include_dirs, inputs, metadata, module_deps, module_name,
- outputs*, pool, response_file_contents, rustenv, rustflags, script*, sources,
- swiftflags
+)" CONFIG_VALUES_VARS_HELP DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS
+ACTION_VARS
+
+R"( * = required
Example
@@ -305,7 +309,9 @@
Variables
- sources*, outputs*, deps, data_deps, metadata, public_deps, visibility
+)" DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS
+
+R"( Bundle-specific: sources*, outputs*
* = required
Examples
@@ -391,11 +397,13 @@
Variables
- bundle_root_dir, bundle_contents_dir, bundle_resources_dir,
- bundle_executable_dir, bundle_deps_filter, deps, data_deps, public_deps,
- visibility, product_type, code_signing_args, code_signing_script,
- code_signing_sources, code_signing_outputs, xcode_extra_attributes,
- xcode_test_application_name, partial_info_plist, metadata
+)" DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS
+
+R"( Bundle vars: bundle_root_dir, bundle_contents_dir, bundle_resources_dir,
+ bundle_executable_dir, bundle_deps_filter, product_type,
+ code_signing_args, code_signing_script, code_signing_sources,
+ code_signing_outputs, xcode_extra_attributes,
+ xcode_test_application_name, partial_info_plist
Example
@@ -527,6 +535,17 @@
(see "gn help source_expansion"). The placeholders will look like
"{{source_name_part}}", for example.
+ If you want to copy the output of a previous build step, the target that
+ generates the file to copy must be reachable from the deps or public_deps of
+ the copy target.
+
+Variables
+
+)" DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS
+
+R"( Copy variables: sources*, outputs*
+ * = required
+
Examples
# Write a rule that copies a checked-in DLL to the output directory.
@@ -543,6 +562,24 @@
# names in the gen dir. This will just copy each file.
outputs = [ "$target_gen_dir/{{source_file_part}}" ]
}
+
+ # Copy the output of a generated executable.
+ copy("package_melon") {
+ # This example uses get_label_info() to compute the output directory of the
+ # dependency. This allows the copy rule to work regardless of the toolchain.
+ #
+ # In some cases (particularly actions defined previously in the same file)
+ # you can use get_target_outputs() to get the input file which can eliminate
+ # the assumptions about the output file name of the dependency.
+
+ input_dir = get_label_info("//src/tools/melon", "root_out_dir");
+ sources = [ "$input_dir/melon" ]
+
+ outputs = [ "$target_gen_dir/{{source_file_part}}" ]
+
+ # Depend on the target to build the file before copying.
+ deps = [ "//src/tools/melon" ]
+ }
)";
Value RunCopy(const FunctionCallNode* function,
@@ -595,7 +632,7 @@
Variables
-)" DEPS_VARS DEPENDENT_CONFIG_VARS
+)" DEPS_VARS DEPENDENT_CONFIG_VARS GENERAL_TARGET_VARS
R"(
Example
@@ -841,6 +878,14 @@
Is equivalent to:
source_set("doom_melon") {
+Common target variables
+
+)" DEPS_VARS DEPENDENT_CONFIG_VARS GENERAL_TARGET_VARS
+
+R"(
+ Targets will also have variables specific to that type, see "gn help <type>"
+ for more.
+
Example
if (foo_build_as_shared) {
@@ -908,6 +953,12 @@
Collected metadata, if specified, will be returned in postorder of
dependencies. See the example for details.
+Variables
+
+)" DEPENDENT_CONFIG_VARS DEPS_VARS GENERAL_TARGET_VARS
+
+R"( Generated file: contents, data_keys, rebase, walk_keys, output_conversion
+
Example (metadata collection)
Given the following targets defined in //base/BUILD.gn, where A depends on B
@@ -1003,16 +1054,7 @@
"../base/bar.cpp", // from //base:b via //base:a
"../base/foo.cpp", // from //base:a
]
-
-
-Variables
-
- contents
- data_keys
- rebase
- walk_keys
- output_conversion
-)" DEPS_VARS DEPENDENT_CONFIG_VARS;
+)";
Value RunGeneratedFile(Scope* scope,
const FunctionCallNode* function,
