Docs: regenerate docs
This only regenerates documentation to reflect changes since the last
docs generation, no change to content otherwise. This should be
non-controversial, since this mostly addition.
Test: out/gn help --markdown all > docs/reference.md
Change-Id: I0c0777947f0b320246badf7e5c302282df765a16
Reviewed-on: https://gn-review.googlesource.com/c/3680
Reviewed-by: Scott Graham <scottmg@chromium.org>
Commit-Queue: Scott Graham <scottmg@chromium.org>
diff --git a/docs/reference.md b/docs/reference.md
index a01c620..cb6960d 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -14,6 +14,7 @@
* [gen: Generate ninja files.](#gen)
* [help: Does what you think.](#help)
* [ls: List matching targets.](#ls)
+ * [meta: List target metadata collection results.](#meta)
* [path: Find paths between two targets.](#path)
* [refs: Find stuff referencing a target or file.](#refs)
* [Target declarations](#targets)
@@ -23,6 +24,7 @@
* [copy: Declare a target that copies files.](#copy)
* [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#create_bundle)
* [executable: Declare an executable target.](#executable)
+ * [generated_file: Declare a generated_file target.](#generated_file)
* [group: Declare a named group of targets.](#group)
* [loadable_module: Declare a loadable module target.](#loadable_module)
* [shared_library: Declare a shared library target.](#shared_library)
@@ -99,8 +101,10 @@
* [code_signing_sources: [file list] Sources for code signing step.](#code_signing_sources)
* [complete_static_lib: [boolean] Links all deps into a static library.](#complete_static_lib)
* [configs: [label list] Configs applying to this target or config.](#configs)
+ * [contents: Contents to write to file.](#contents)
* [data: [file list] Runtime data file dependencies.](#data)
* [data_deps: [label list] Non-linked dependencies.](#data_deps)
+ * [data_keys: [string list] Keys from which to collect metadata.](#data_keys)
* [defines: [string list] C preprocessor defines.](#defines)
* [depfile: [string] File name for input dependencies for actions.](#depfile)
* [deps: [label list] Private linked dependencies.](#deps)
@@ -110,6 +114,8 @@
* [ldflags: [string list] Flags passed to the linker.](#ldflags)
* [lib_dirs: [directory list] Additional library directories.](#lib_dirs)
* [libs: [string list] Additional libraries to link.](#libs)
+ * [metadata: [scope] Metadata of this target.](#metadata)
+ * [output_conversion: Data format for generated_file targets.](#output_conversion)
* [output_dir: [directory] Directory to put output file in.](#output_dir)
* [output_extension: [string] Value to use for the output's file extension.](#output_extension)
* [output_name: [string] Name for the output file other than the default.](#output_name)
@@ -124,11 +130,13 @@
* [public: [file list] Declare public header files for a target.](#public)
* [public_configs: [label list] Configs applied to dependents.](#public_configs)
* [public_deps: [label list] Declare public dependencies.](#public_deps)
+ * [rebase: [boolean] Rebase collected metadata as files.](#rebase)
* [response_file_contents: [string list] Contents of .rsp file for actions.](#response_file_contents)
* [script: [file name] Script file for actions.](#script)
* [sources: [file list] Source files for a target.](#sources)
* [testonly: [boolean] Declares a target must only be used for testing.](#testonly)
* [visibility: [label list] A list of labels that can depend on a target.](#visibility)
+ * [walk_keys: [string list] Key(s) for managing the metadata collection walk.](#walk_keys)
* [write_runtime_deps: Writes the target's runtime_deps to the given path.](#write_runtime_deps)
* [xcode_extra_attributes: [scope] Extra attributes for Xcode projects.](#xcode_extra_attributes)
* [test_application_name: [string] Test application name for unit or ui test target.](#test_application_name)
@@ -331,9 +339,9 @@
#### **What gets checked**
```
- The .gn file may specify a list of targets to be checked. Only these targets
- will be checked if no label_pattern is specified on the command line.
- Otherwise, the command-line list is used instead. See "gn help dotfile".
+ The .gn file may specify a list of targets to be checked in the list
+ check_targets (see "gn help dotfile"). If a label pattern is specified
+ on the command line, check_targets is not used.
Targets can opt-out from checking with "check_includes = false" (see
"gn help check_includes").
@@ -452,6 +460,7 @@
cflags_cc [--blame]
check_includes
configs [--tree] (see below)
+ data_keys
defines [--blame]
depfile
deps [--all] [--tree] (see below)
@@ -460,13 +469,17 @@
ldflags [--blame]
lib_dirs
libs
+ metadata
+ output_conversion
outputs
public_configs
public
+ rebase
script
sources
testonly
visibility
+ walk_keys
runtime_deps
Compute all runtime deps for the given target. This is a computed list
@@ -853,6 +866,61 @@
Lists all variants of the target //base:base (it may be referenced
in multiple toolchains).
```
+### <a name="meta"></a>**gn meta <out_dir> <target>* \--data=<key>[,<key>*]* [\--walk=<key>[,<key>*]*]**
+```
+ [--rebase=<dest dir>]
+
+ Lists collected metaresults of all given targets for the given data key(s),
+ collecting metadata dependencies as specified by the given walk key(s).
+
+ See `gn help generated_file` for more information on the walk.
+```
+
+#### **Arguments**
+
+```
+ <target(s)>
+ 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.
+
+ --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.
+
+ --rebase (optional)
+ A destination directory onto which to rebase any paths found. If set, all
+ collected metadata will be rebased onto this path. This option will throw errors
+ if collected metadata is not a list of strings.
+```
+
+#### **Examples**
+
+```
+ gn meta out/Debug "//base/foo" --data=files
+ 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
+ Lists collected metaresults for the `files` and `other` keys in the
+ //base/foo:foo target and all of its dependency tree.
+
+ gn meta out/Debug "//base/foo" --data=files --walk=stop
+ Lists collected metaresults for the `files` key in the //base/foo:foo
+ target and all of the dependencies listed in the `stop` key (and so on).
+
+ gn meta out/Debug "//base/foo" --data=files --rebase="/"
+ Lists collected metaresults for the `files` key in the //base/foo:foo
+ target and all of its dependency tree, rebasing the strings in the `files`
+ key onto the source directory of the target's declaration relative to "/".
+```
### <a name="path"></a>**gn path <out_dir> <target_one> <target_two>**
```
@@ -1087,7 +1155,7 @@
#### **Variables**
```
- args, data, data_deps, depfile, deps, inputs, outputs*, pool,
+ args, data, data_deps, depfile, deps, inputs, metadata, outputs*, pool,
response_file_contents, script*, sources
* = required
```
@@ -1168,7 +1236,7 @@
#### **Variables**
```
- args, data, data_deps, depfile, deps, inputs, outputs*, pool,
+ args, data, data_deps, depfile, deps, inputs, metadata, outputs*, pool,
response_file_contents, script*, sources*
* = required
```
@@ -1221,7 +1289,7 @@
#### **Variables**
```
- sources*, outputs*, deps, data_deps, public_deps, visibility
+ sources*, outputs*, deps, data_deps, metadata, public_deps, visibility
* = required
```
@@ -1338,7 +1406,8 @@
bundle_executable_dir*, bundle_plugins_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
+ xcode_extra_attributes, xcode_test_application_name, partial_info_plist,
+ metadata
* = required
```
@@ -1453,8 +1522,141 @@
libs, precompiled_header, precompiled_source
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
- General: check_includes, configs, data, friend, inputs, output_name,
- output_extension, public, sources, testonly, visibility
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_name, output_extension, public, sources, testonly,
+ visibility
+```
+### <a name="generated_file"></a>**generated_file**: Declare a generated_file target.
+
+```
+ Writes data value(s) to disk on resolution. This target type mirrors some
+ functionality of the write_file() function, but also provides the ability to
+ collect metadata from its dependencies on resolution rather than writing out
+ parse time.
+
+ The `outputs` variable is required to be a list with a single element,
+ specifying the intended location of the output file.
+
+ The `output_conversion` variable specified the format to write the
+ value. See `gn help output_conversion`.
+
+ One of `contents` or `data_keys` must be specified; use of `data` will write
+ the contents of that value to file, while use of `data_keys` will trigger a
+ metadata collection walk based on the dependencies of the target and the
+ optional values of the `rebase` and `walk_keys` variables. See
+ `gn help metadata`.
+
+ Collected metadata, if specified, will be returned in postorder of
+ dependencies. See the example for details.
+```
+
+#### **Example (metadata collection)**
+
+```
+ Given the following targets defined in //base/BUILD.gn, where A depends on B
+ and B depends on C and D:
+
+ group("a") {
+ metadata = {
+ doom_melon = [ "enable" ]
+ my_files = [ "foo.cpp" ]
+
+ // Note: this is functionally equivalent to not defining `my_barrier`
+ // at all in this target's metadata.
+ my_barrier = [ "" ]
+ }
+
+ deps = [ ":b" ]
+ }
+
+ group("c") {
+ metadata = {
+ my_files = [ "bar.cpp" ]
+ my_barrier = [ ":c" ]
+ }
+
+ deps = [ ":c", ":d" ]
+ }
+
+ group("c") {
+ metadata = {
+ doom_melon = [ "disable" ]
+ my_files = [ "baz.cpp" ]
+ }
+ }
+
+ group("d") {
+ metadata = {
+ my_files = [ "missing.cpp" ]
+ }
+ }
+
+ If the following generated_file target is defined:
+
+ generated_file("my_files_metadata") {
+ outputs = [ "$root_build_dir/my_files.json" ]
+ data_keys = [ "my_files" ]
+
+ deps = [ "//base:a" ]
+ }
+
+ The following will be written to "$root_build_dir/my_files.json" (less the
+ comments):
+ [
+ "baz.cpp", // from //base:c via //base:b
+ "missing.cpp" // from //base:d via //base:b
+ "bar.cpp", // from //base:b via //base:a
+ "foo.cpp", // from //base:a
+ ]
+
+ Alternatively, as an example of using walk_keys, if the following
+ generated_file target is defined:
+
+ generated_file("my_files_metadata") {
+ outputs = [ "$root_build_dir/my_files.json" ]
+ data_keys = [ "my_files" ]
+ walk_keys = [ "my_barrier" ]
+
+ deps = [ "//base:a" ]
+ }
+
+ The following will be written to "$root_build_dir/my_files.json" (again less
+ the comments):
+ [
+ "baz.cpp", // from //base:c via //base:b
+ "bar.cpp", // from //base:b via //base:a
+ "foo.cpp", // from //base:a
+ ]
+
+ If `rebase` is used in the following generated_file target:
+
+ generated_file("my_files_metadata") {
+ outputs = [ "$root_build_dir/my_files.json" ]
+ data_keys = [ "my_files" ]
+ walk_keys = [ "my_barrier" ]
+ rebase = root_build_dir
+
+ deps = [ "//base:a" ]
+ }
+
+ The following will be written to "$root_build_dir/my_files.json" (again less
+ the comments) (assuming root_build_dir = "//out"):
+ [
+ "../base/baz.cpp", // from //base:c via //base:b
+ "../base/bar.cpp", // from //base:b via //base:a
+ "../base/foo.cpp", // from //base:a
+ ]
+```
+
+#### **Variables**
+
+```
+ data_keys
+ rebase
+ walk_keys
+ output_conversion
+ Deps: data_deps, deps, public_deps
+ Dependent configs: all_dependent_configs, public_configs
```
### <a name="group"></a>**group**: Declare a named group of targets.
@@ -1501,8 +1703,9 @@
libs, precompiled_header, precompiled_source
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
- General: check_includes, configs, data, friend, inputs, output_name,
- output_extension, public, sources, testonly, visibility
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_name, output_extension, public, sources, testonly,
+ visibility
```
### <a name="shared_library"></a>**shared_library**: Declare a shared library target.
@@ -1522,8 +1725,9 @@
libs, precompiled_header, precompiled_source
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
- General: check_includes, configs, data, friend, inputs, output_name,
- output_extension, public, sources, testonly, visibility
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_name, output_extension, public, sources, testonly,
+ visibility
```
### <a name="source_set"></a>**source_set**: Declare a source set target.
@@ -1558,8 +1762,9 @@
libs, precompiled_header, precompiled_source
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
- General: check_includes, configs, data, friend, inputs, output_name,
- output_extension, public, sources, testonly, visibility
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_name, output_extension, public, sources, testonly,
+ visibility
```
### <a name="static_library"></a>**static_library**: Declare a static library target.
@@ -1580,8 +1785,9 @@
libs, precompiled_header, precompiled_source
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
- General: check_includes, configs, data, friend, inputs, output_name,
- output_extension, public, sources, testonly, visibility
+ General: check_includes, configs, data, friend, inputs, metadata,
+ output_name, output_extension, public, sources, testonly,
+ visibility
```
### <a name="target"></a>**target**: Declare an target with the given programmatic type.
@@ -4460,6 +4666,12 @@
}
}
```
+### <a name="contents"></a>**contents**: Contents to write to file.
+
+```
+ The contents of the file for a generated_file target.
+ See "gn help generated_file".
+```
### <a name="data"></a>**data**: Runtime data file dependencies.
```
@@ -4515,6 +4727,15 @@
data_deps = [ "//plugins:my_runtime_plugin" ]
}
```
+### <a name="data_keys"></a>**data_keys**: Keys from which to collect metadata.
+
+```
+ These keys are used to identify metadata to collect. If a walked target
+ defines this key in its metadata, its value will be appended to the resulting
+ collection.
+
+ See "gn help generated_file".
+```
### <a name="defines"></a>**defines**: C preprocessor defines.
```
@@ -4930,6 +5151,34 @@
On Linux:
libs = [ "ld" ]
```
+### <a name="metadata"></a>**metadata**: Metadata of this target.
+
+```
+ Metadata is a collection of keys and values relating to a particular target.
+ Generally, these keys will include three categories of strings: ordinary
+ strings, filenames intended to be rebased according to their particular
+ source directory, and target labels intended to be used as barriers to the
+ walk. Verfication of these categories occurs at walk time, not creation
+ time (since it is not clear until the walk which values are intended for
+ which purpose).
+
+ Example
+
+ group("doom_melon") {
+ metadata = {
+ # These keys are not built in to GN but are interpreted when consuming
+ # metadata.
+ my_barrier = []
+ my_files = [ "a.txt", "b.txt" ]
+ }
+ }
+```
+### <a name=""output_conversion"></a>**"output_conversion**: Data format for generated_file targets.
+
+```
+ Controls how the "contents" of a generated_file target is formatted.
+ See "gn help output_conversion".
+```
### <a name="output_dir"></a>**output_dir**: [directory] Directory to put output file in.
```
@@ -5375,6 +5624,22 @@
public_deps = [ ":c" ]
}
```
+### <a name="rebase"></a>**rebase**: Rebase collected metadata as files.
+
+```
+ A boolean that triggers a rebase of collected metadata strings based on their
+ declared file. Defaults to false.
+
+ Metadata generally declares files as strings relative to the local build file.
+ However, this data is often used in other contexts, and so setting this flag
+ will force the metadata collection to be rebased according to the local build
+ file's location and thus allow the filename to be used anywhere.
+
+ Setting this flag will raise an error if any target's specified metadata is
+ not a string value.
+
+ See also "gn help generated_file".
+```
### <a name="response_file_contents"></a>**response_file_contents**: Contents of a response file for actions.
```
@@ -5534,6 +5799,20 @@
any targets in "//bar/" and any subdirectory thereof.
visibility = [ "./*", "//bar/*" ]
```
+### <a name="walk_keys"></a>**walk_keys**: Key(s) for managing the metadata collection walk.
+
+```
+ Defaults to [].
+
+ These keys are used to control the next step in a collection walk, acting as
+ barriers. If a specified key is defined in a target's metadata, the walk will
+ use the targets listed in that value to determine which targets are walked.
+
+ If no walk_keys are specified for a generated_file target (i.e. "[]"), the
+ walk will touch all deps and data_deps of the specified target recursively.
+
+ See "gn help generated_file".
+```
### <a name="write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps to the given path.
```
@@ -5678,8 +5957,8 @@
check_targets [optional]
A list of labels and label patterns that should be checked when running
"gn check" or "gn gen --check". If unspecified, all targets will be
- checked. If it is the empty list, no targets will be checked. To bypass
- this list, request an explicit check of targets, for instance "//*".
+ checked. If it is the empty list, no targets will be checked. To
+ bypass this list, request an explicit check of targets, like "//*".
The format of this list is identical to that of "visibility" so see "gn
help visibility" for examples.
@@ -6060,6 +6339,11 @@
myvalues.foo += 2
empty_scope.new_thing = [ 1, 2, 3 ]
+
+ Scope equality is defined as single-level scopes identical within the current
+ scope. That is, all values in the first scope must be present and identical
+ within the second, and vice versa. Note that this means inherited scopes are
+ always unequal by definition.
```
### <a name="input_conversion"></a>**Input and output conversions are arguments to file and process functions**
#### **that specify how to convert data to or from external formats. The possible**
