Update reference.md
Re-run gn help --reference > docs/reference.md to update the contents,
which have become slightly out of date.
Change-Id: I64f2e8bfa32f431cd397021a608c09057fb2375e
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/6580
Commit-Queue: Petr Hosek <phosek@google.com>
Reviewed-by: Petr Hosek <phosek@google.com>
diff --git a/docs/reference.md b/docs/reference.md
index c4dda86..38ebeb6 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -193,6 +193,8 @@
This filtering behavior is also known as "pruning" the list of compile
targets.
+ If input_path is -, input is read from stdin.
+
output_path is a path indicating where the results of the command are to be
written. The results will be a file containing a JSON object with one or more
of following fields:
@@ -226,6 +228,8 @@
a string describing the error. This includes cases where the input file is
not in the right format, or contains invalid targets.
+ If output_path is -, output is written to stdout.
+
The command returns 1 if it is unable to read the input file or write the
output file, or if there is something wrong with the build such that gen
would also fail, and 0 otherwise. In particular, it returns 0 even if the
@@ -989,7 +993,7 @@
#### **Example**
```
- gn path out/Default //base //tools/gn
+ gn path out/Default //base //gn
```
### <a name="cmd_refs"></a>**gn refs**
@@ -1076,7 +1080,7 @@
#### **Examples (target input)**
```
- gn refs out/Debug //tools/gn:gn
+ gn refs out/Debug //gn:gn
Find all targets depending on the given exact target name.
gn refs out/Debug //base:i18n --as=buildfiles | xargs gvim
@@ -1568,7 +1572,7 @@
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.
+ at parse time.
The `outputs` variable is required to be a list with a single element,
specifying the intended location of the output file.
@@ -1597,8 +1601,8 @@
doom_melon = [ "enable" ]
my_files = [ "foo.cpp" ]
- // Note: this is functionally equivalent to not defining `my_barrier`
- // at all in this target's metadata.
+ # Note: this is functionally equivalent to not defining `my_barrier`
+ # at all in this target's metadata.
my_barrier = [ "" ]
}
@@ -6810,7 +6814,7 @@
```
Metadata is information attached to targets throughout the dependency tree. GN
allows for the collection of this data into files written during the generation
- step, enabing users to expose and aggregate this data based on the dependency
+ step, enabling users to expose and aggregate this data based on the dependency
tree.
```
@@ -6819,17 +6823,17 @@
```
Similar to the write_file() function, the generated_file target type
creates a file in the specified location with the specified content. The
- primary difference between the function and the target type is that the
+ primary difference between write_file() and this target type is that the
write_file function does the file write at parse time, while the
generated_file target type writes at target resolution time. See
"gn help generated_file" for more detail.
- When written at target resolution time, the generated_file enables GN to
+ When written at target resolution time, generated_file enables GN to
collect and write aggregated metadata from dependents.
- A generated_file target can declare either 'contents' (to write statically
- known contents to a file) or 'data_keys'(to aggregate metadata and write the
- result to a file). It can also specify 'walk_keys' (to restrict the metadata
+ A generated_file target can declare either 'contents' to write statically
+ known contents to a file or 'data_keys' to aggregate metadata and write the
+ result to a file. It can also specify 'walk_keys' (to restrict the metadata
collection), 'output_conversion', and 'rebase'.
```
@@ -6837,22 +6841,23 @@
```
Targets can declare a 'metadata' variable containing a scope, and this
- metadata is collected and written to file by generated_file aggregation
- targets. The 'metadata' scope must contain only list values, since the
- aggregation step collects a list of these values.
+ metadata may be collected and written out to a file specified by
+ generated_file aggregation targets. The 'metadata' scope must contain
+ only list values since the aggregation step collects a list of these values.
During the target resolution, generated_file targets will walk their
dependencies recursively, collecting metadata based on the specified
'data_keys'. 'data_keys' is specified as a list of strings, used by the walk
to identify which variables in dependencies' 'metadata' scopes to collect.
- The walk begins with the listed dependencies of the 'generated_file' target,
- for each checking the "metadata" scope for any of the "data_keys". If
- present, the data in those variables is appended to the aggregate list. Note
- that this means that if more than one walk key is specified, the data in all
- of them will be aggregated into one list. From there, the walk will then
- recurse into the dependencies of each target it encounters, collecting the
- specified metadata for each.
+ The walk begins with the listed dependencies of the 'generated_file' target.
+ The 'metadata' scope for each dependency is inspected for matching elements
+ of the 'generated_file' target's 'data_keys' list. If a match is found, the
+ data from the dependent's matching key list is appended to the aggregate walk
+ list. Note that this means that if more than one walk key is specified, the
+ data in all of them will be aggregated into one list. From there, the walk
+ will then recurse into the dependencies of each target it encounters,
+ collecting the specified metadata for each.
For example:
@@ -6885,10 +6890,10 @@
bar.cpp
baz.cpp
- The dependency walk can be limited by using the "walk_keys". This is a list of
+ The dependency walk can be limited by using the 'walk_keys'. This is a list of
labels that should be included in the walk. All labels specified here should
also be in one of the deps lists. These keys act as barriers, where the walk
- will only recurse into targets listed here. An empty list in all specified
+ will only recurse into the targets listed. An empty list in all specified
barriers will end that portion of the walk.
group("a") {
