Markdown optimization:
The GN Reference [1] guide has a lengthy document. When users click on a specific sub-item
to jump to the corresponding position, they need to scroll for a long time to return to the
top of the document. Therefore, an anchor to return to the top has been added to each sub-item.
You can view the changes here [2].
[1] https://gn.googlesource.com/gn/+/main/docs/reference.md
[2] https://github.com/ZhaoSongGOO/MyDocument/blob/main/reference.md#gn-reference
Change-Id: I7a98c95327135ed23b655dd56d9a8e3e80838a6e
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/17420
Reviewed-by: David Turner <digit@google.com>
Commit-Queue: David Turner <digit@google.com>
Reviewed-by: Takuto Ikuta <tikuta@google.com>
Reviewed-by: zhao Song <zhaosonggo@gmail.com>
diff --git a/docs/reference.md b/docs/reference.md
index a9fad5b..2c8aa92 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -191,7 +191,7 @@
## <a name="commands"></a>Commands
-### <a name="cmd_analyze"></a>**gn analyze <out_dir> <input_path> <output_path>**
+### <a name="cmd_analyze"></a>**gn analyze <out_dir> <input_path> <output_path>** [Back to Top](#gn-reference)
```
Analyze which targets are affected by a list of files.
@@ -267,7 +267,7 @@
tries really hard to always write something to the output JSON and convey
errors that way rather than via return codes.
```
-### <a name="cmd_args"></a>**gn args**: (command-line tool)
+### <a name="cmd_args"></a>**gn args**: (command-line tool) [Back to Top](#gn-reference)
```
Display or configure arguments declared by the build.
@@ -356,7 +356,7 @@
given arguments set (which may affect the values of other
arguments).
```
-### <a name="cmd_check"></a>**gn check <out_dir> [<label_pattern>] [\--force] [\--check-generated]**
+### <a name="cmd_check"></a>**gn check <out_dir> [<label_pattern>] [\--force] [\--check-generated]** [Back to Top](#gn-reference)
```
GN's include header checker validates that the includes for C-like source
@@ -494,13 +494,13 @@
gn check out/Default "//foo/*
Check only the files in targets in the //foo directory tree.
```
-### <a name="cmd_clean"></a>**gn clean <out_dir>...**
+### <a name="cmd_clean"></a>**gn clean <out_dir>...** [Back to Top](#gn-reference)
```
Deletes the contents of the output directory except for args.gn and
creates a Ninja build environment sufficient to regenerate the build.
```
-### <a name="cmd_clean_stale"></a>**gn clean_stale [\--ninja-executable=...] <out_dir>...**
+### <a name="cmd_clean_stale"></a>**gn clean_stale [\--ninja-executable=...] <out_dir>...** [Back to Top](#gn-reference)
```
Removes the no longer needed output files from the build directory and prunes
@@ -518,7 +518,7 @@
--ninja-executable=<string>
Can be used to specify the ninja executable to use.
```
-### <a name="cmd_desc"></a>**gn desc**
+### <a name="cmd_desc"></a>**gn desc** [Back to Top](#gn-reference)
```
gn desc <out_dir> <label or pattern> [<what to show>] [--blame]
@@ -690,7 +690,7 @@
Shows defines set for the //base:base target, annotated by where
each one was set from.
```
-### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <list of build_files...>)**
+### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <list of build_files...>)** [Back to Top](#gn-reference)
```
Formats .gn file to a standard format.
@@ -739,7 +739,7 @@
gn format --stdin
gn format --read-tree=json //rewritten/BUILD.gn
```
-### <a name="cmd_gen"></a>**gn gen [\--check] [<ide options>] <out_dir>**
+### <a name="cmd_gen"></a>**gn gen [\--check] [<ide options>] <out_dir>** [Back to Top](#gn-reference)
```
Generates ninja files from the current tree and puts them in the given output
@@ -989,7 +989,7 @@
and not match:
- "//foo:bar"
```
-### <a name="cmd_help"></a>**gn help <anything>**
+### <a name="cmd_help"></a>**gn help <anything>** [Back to Top](#gn-reference)
```
Yo dawg, I heard you like help on your help so I put help on the help in the
@@ -1011,7 +1011,7 @@
gn help --markdown all
Dump all help to stdout in markdown format.
```
-### <a name="cmd_ls"></a>**gn ls <out_dir> [<label_pattern>] [\--default-toolchain] [\--as=...]**
+### <a name="cmd_ls"></a>**gn ls <out_dir> [<label_pattern>] [\--default-toolchain] [\--as=...]** [Back to Top](#gn-reference)
```
[--type=...] [--testonly=...]
@@ -1079,7 +1079,7 @@
gn ls out/Debug "//base/*" --as=output | xargs ninja -C out/Debug
Builds all targets in //base and all subdirectories.
```
-### <a name="cmd_meta"></a>**gn meta**
+### <a name="cmd_meta"></a>**gn meta** [Back to Top](#gn-reference)
```
gn meta <out_dir> <target>* --data=<key>[,<key>*]* [--walk=<key>[,<key>*]*]
@@ -1137,7 +1137,7 @@
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="cmd_outputs"></a>**gn outputs <out_dir> <list of target or file names...>**
+### <a name="cmd_outputs"></a>**gn outputs <out_dir> <list of target or file names...>** [Back to Top](#gn-reference)
```
Lists the output files corresponding to the given target(s) or file name(s).
@@ -1191,7 +1191,7 @@
git diff --name-only | xargs gn outputs out/x64 | xargs ninja -C out/x64
Compiles all files changed in git.
```
-### <a name="cmd_path"></a>**gn path <out_dir> <target_one> <target_two>**
+### <a name="cmd_path"></a>**gn path <out_dir> <target_one> <target_two>** [Back to Top](#gn-reference)
```
Finds paths of dependencies between two targets. Each unique path will be
@@ -1236,7 +1236,7 @@
```
gn path out/Default //base //gn
```
-### <a name="cmd_refs"></a>**gn refs**
+### <a name="cmd_refs"></a>**gn refs** [Back to Top](#gn-reference)
```
gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)* [--all]
@@ -1365,7 +1365,7 @@
```
## <a name="targets"></a>Target declarations
-### <a name="func_action"></a>**action**: Declare a target that runs a script a single time.
+### <a name="func_action"></a>**action**: Declare a target that runs a script a single time. [Back to Top](#gn-reference)
```
This target type allows you to run a script a single time to produce one or
@@ -1477,7 +1477,7 @@
rebase_path(sources, root_build_dir)
}
```
-### <a name="func_action_foreach"></a>**action_foreach**: Declare a target that runs a script over a set of files.
+### <a name="func_action_foreach"></a>**action_foreach**: Declare a target that runs a script over a set of files. [Back to Top](#gn-reference)
```
This target type allows you to run a script once-per-file over a set of
@@ -1592,7 +1592,7 @@
"/{{source_name_part}}.h" ]
}
```
-### <a name="func_bundle_data"></a>**bundle_data**: [iOS/macOS] Declare a target without output.
+### <a name="func_bundle_data"></a>**bundle_data**: [iOS/macOS] Declare a target without output. [Back to Top](#gn-reference)
```
This target type allows one to declare data that is required at runtime. It is
@@ -1657,7 +1657,7 @@
]
}
```
-### <a name="func_copy"></a>**copy**: Declare a target that copies files.
+### <a name="func_copy"></a>**copy**: Declare a target that copies files. [Back to Top](#gn-reference)
#### **File name handling**
@@ -1729,7 +1729,7 @@
deps = [ "//src/tools/melon" ]
}
```
-### <a name="func_create_bundle"></a>**create_bundle**: [ios/macOS] Build an iOS or macOS bundle.
+### <a name="func_create_bundle"></a>**create_bundle**: [ios/macOS] Build an iOS or macOS bundle. [Back to Top](#gn-reference)
```
This target generates an iOS or macOS bundle (which is a directory with a
@@ -1894,7 +1894,7 @@
}
}
```
-### <a name="func_executable"></a>**executable**: Declare an executable target.
+### <a name="func_executable"></a>**executable**: Declare an executable target. [Back to Top](#gn-reference)
#### **Language and compilation**
@@ -1921,7 +1921,7 @@
visibility
Rust variables: aliased_deps, crate_root, crate_name
```
-### <a name="func_generated_file"></a>**generated_file**: Declare a generated_file target.
+### <a name="func_generated_file"></a>**generated_file**: Declare a generated_file target. [Back to Top](#gn-reference)
```
Writes data value(s) to disk on resolution. This target type mirrors some
@@ -2054,7 +2054,7 @@
"../base/foo.cpp", // from //base:a
]
```
-### <a name="func_group"></a>**group**: Declare a named group of targets.
+### <a name="func_group"></a>**group**: Declare a named group of targets. [Back to Top](#gn-reference)
```
This target type allows you to create meta-targets that just collect a set of
@@ -2083,7 +2083,7 @@
]
}
```
-### <a name="func_loadable_module"></a>**loadable_module**: Declare a loadable module target.
+### <a name="func_loadable_module"></a>**loadable_module**: Declare a loadable module target. [Back to Top](#gn-reference)
```
This target type allows you to create an object file that is (and can only
@@ -2120,7 +2120,7 @@
visibility
Rust variables: aliased_deps, crate_root, crate_name, crate_type
```
-### <a name="func_rust_library"></a>**rust_library**: Declare a Rust library target.
+### <a name="func_rust_library"></a>**rust_library**: Declare a Rust library target. [Back to Top](#gn-reference)
```
A Rust library is an archive containing additional rust-c provided metadata.
@@ -2153,7 +2153,7 @@
visibility
Rust variables: aliased_deps, crate_root, crate_name
```
-### <a name="func_rust_proc_macro"></a>**rust_proc_macro**: Declare a Rust procedural macro target.
+### <a name="func_rust_proc_macro"></a>**rust_proc_macro**: Declare a Rust procedural macro target. [Back to Top](#gn-reference)
```
A Rust procedural macro allows creating syntax extensions as execution of a
@@ -2189,7 +2189,7 @@
visibility
Rust variables: aliased_deps, crate_root, crate_name
```
-### <a name="func_shared_library"></a>**shared_library**: Declare a shared library target.
+### <a name="func_shared_library"></a>**shared_library**: Declare a shared library target. [Back to Top](#gn-reference)
```
A shared library will be specified on the linker line for targets listing the
@@ -2224,7 +2224,7 @@
visibility
Rust variables: aliased_deps, crate_root, crate_name, crate_type
```
-### <a name="func_source_set"></a>**source_set**: Declare a source set target.
+### <a name="func_source_set"></a>**source_set**: Declare a source set target. [Back to Top](#gn-reference)
```
Only C-language source sets are supported at the moment.
@@ -2269,7 +2269,7 @@
output_extension, output_name, public, sources, testonly,
visibility
```
-### <a name="func_static_library"></a>**static_library**: Declare a static library target.
+### <a name="func_static_library"></a>**static_library**: Declare a static library target. [Back to Top](#gn-reference)
```
Make a ".a" / ".lib" file.
@@ -2301,7 +2301,7 @@
target containing both C and C++ sources is acceptable, but a
target containing C and Rust sources is not).
```
-### <a name="func_target"></a>**target**: Declare a target with the given programmatic type.
+### <a name="func_target"></a>**target**: Declare a target with the given programmatic type. [Back to Top](#gn-reference)
```
target(target_type_string, target_name_string) { ... }
@@ -2349,7 +2349,7 @@
```
## <a name="functions"></a>Buildfile functions
-### <a name="func_assert"></a>**assert**: Assert an expression is true at generation time.
+### <a name="func_assert"></a>**assert**: Assert an expression is true at generation time. [Back to Top](#gn-reference)
```
assert(<condition> [, <error string>])
@@ -2365,7 +2365,7 @@
assert(is_win)
assert(defined(sources), "Sources must be defined");
```
-### <a name="func_config"></a>**config**: Defines a configuration object.
+### <a name="func_config"></a>**config**: Defines a configuration object. [Back to Top](#gn-reference)
```
Configuration objects can be applied to targets and specify sets of compiler
@@ -2433,7 +2433,7 @@
configs = [ ":myconfig" ]
}
```
-### <a name="func_declare_args"></a>**declare_args**: Declare build arguments.
+### <a name="func_declare_args"></a>**declare_args**: Declare build arguments. [Back to Top](#gn-reference)
```
Introduces the given arguments into the current scope. If they are not
@@ -2494,7 +2494,7 @@
This also sets the teleporter, but it's already defaulted to on so it will
have no effect.
```
-### <a name="func_defined"></a>**defined**: Returns whether an identifier is defined.
+### <a name="func_defined"></a>**defined**: Returns whether an identifier is defined. [Back to Top](#gn-reference)
```
Returns true if the given argument is defined. This is most useful in
@@ -2535,7 +2535,7 @@
}
}
```
-### <a name="func_exec_script"></a>**exec_script**: Synchronously run a script and return the output.
+### <a name="func_exec_script"></a>**exec_script**: Synchronously run a script and return the output. [Back to Top](#gn-reference)
```
exec_script(filename,
@@ -2595,7 +2595,7 @@
# result.
exec_script("//foo/bar/myscript.py")
```
-### <a name="func_filter_exclude"></a>**filter_exclude**: Remove values that match a set of patterns.
+### <a name="func_filter_exclude"></a>**filter_exclude**: Remove values that match a set of patterns. [Back to Top](#gn-reference)
```
filter_exclude(values, exclude_patterns)
@@ -2613,7 +2613,7 @@
result = filter_exclude(values, [ "*.proto" ])
# result will be [ "foo.cc", "foo.h" ]
```
-### <a name="func_filter_include"></a>**filter_include**: Remove values that do not match a set of patterns.
+### <a name="func_filter_include"></a>**filter_include**: Remove values that do not match a set of patterns. [Back to Top](#gn-reference)
```
filter_include(values, include_patterns)
@@ -2631,7 +2631,7 @@
result = filter_include(values, [ "*.proto" ])
# result will be [ "foo.proto" ]
```
-### <a name="func_filter_labels_exclude"></a>**filter_labels_exclude**: Remove labels that match a set of patterns.
+### <a name="func_filter_labels_exclude"></a>**filter_labels_exclude**: Remove labels that match a set of patterns. [Back to Top](#gn-reference)
```
filter_labels_exclude(labels, exclude_patterns)
@@ -2649,7 +2649,7 @@
result = filter_labels_exclude(labels, [ "//foo:*" ])
# result will be [ "//foo/bar:baz", "//bar:baz" ]
```
-### <a name="func_filter_labels_include"></a>**filter_labels_include**: Remove labels that do not match a set of patterns.
+### <a name="func_filter_labels_include"></a>**filter_labels_include**: Remove labels that do not match a set of patterns. [Back to Top](#gn-reference)
```
filter_labels_include(labels, include_patterns)
@@ -2667,7 +2667,7 @@
result = filter_labels_include(labels, [ "//foo:*" ])
# result will be [ "//foo:baz" ]
```
-### <a name="func_foreach"></a>**foreach**: Iterate over a list.
+### <a name="func_foreach"></a>**foreach**: Iterate over a list. [Back to Top](#gn-reference)
```
foreach(<loop_var>, <list>) {
@@ -2701,7 +2701,7 @@
b
c
```
-### <a name="func_forward_variables_from"></a>**forward_variables_from**: Copies variables from a different scope.
+### <a name="func_forward_variables_from"></a>**forward_variables_from**: Copies variables from a different scope. [Back to Top](#gn-reference)
```
forward_variables_from(from_scope, variable_list_or_star,
@@ -2779,7 +2779,7 @@
}
}
```
-### <a name="func_get_label_info"></a>**get_label_info**: Get an attribute from a target's label.
+### <a name="func_get_label_info"></a>**get_label_info**: Get an attribute from a target's label. [Back to Top](#gn-reference)
```
get_label_info(target_label, what)
@@ -2843,7 +2843,7 @@
get_label_info("//foo/bar:baz", "target_gen_dir")
# Returns string "//out/Debug/gen/foo/bar".
```
-### <a name="func_get_path_info"></a>**get_path_info**: Extract parts of a file or directory name.
+### <a name="func_get_path_info"></a>**get_path_info**: Extract parts of a file or directory name. [Back to Top](#gn-reference)
```
get_path_info(input, what)
@@ -2923,7 +2923,7 @@
# Extract the source-absolute directory name,
result = get_path_info(get_path_info(path, "dir"), "abspath")
```
-### <a name="func_get_target_outputs"></a>**get_target_outputs**: [file list] Get the list of outputs from a target.
+### <a name="func_get_target_outputs"></a>**get_target_outputs**: [file list] Get the list of outputs from a target. [Back to Top](#gn-reference)
```
get_target_outputs(target_label)
@@ -2974,7 +2974,7 @@
sources = get_target_outputs(":my_action")
}
```
-### <a name="func_getenv"></a>**getenv**: Get an environment variable.
+### <a name="func_getenv"></a>**getenv**: Get an environment variable. [Back to Top](#gn-reference)
```
value = getenv(env_var_name)
@@ -2994,7 +2994,7 @@
```
home_dir = getenv("HOME")
```
-### <a name="func_import"></a>**import**: Import a file into the current scope.
+### <a name="func_import"></a>**import**: Import a file into the current scope. [Back to Top](#gn-reference)
```
The import command loads the rules and variables resulting from executing the
@@ -3029,7 +3029,7 @@
# Looks in the current directory.
import("my_vars.gni")
```
-### <a name="func_label_matches"></a>**label_matches**: Returns true if the label matches any of a set of patterns.
+### <a name="func_label_matches"></a>**label_matches**: Returns true if the label matches any of a set of patterns. [Back to Top](#gn-reference)
```
label_matches(target_label, patterns)
@@ -3044,7 +3044,7 @@
result = label_matches("//baz:bar", [ "//foo/bar/*", "//baz:*" ])
# result will be true
```
-### <a name="func_not_needed"></a>**not_needed**: Mark variables from scope as not needed.
+### <a name="func_not_needed"></a>**not_needed**: Mark variables from scope as not needed. [Back to Top](#gn-reference)
```
not_needed(variable_list_or_star, variable_to_ignore_list = [])
@@ -3065,7 +3065,7 @@
not_needed(invoker, "*", [ "config" ])
not_needed(invoker, [ "data_deps", "deps" ])
```
-### <a name="func_pool"></a>**pool**: Defines a pool object.
+### <a name="func_pool"></a>**pool**: Defines a pool object. [Back to Top](#gn-reference)
```
Pool objects can be applied to a tool to limit the parallelism of the
@@ -3109,7 +3109,7 @@
}
}
```
-### <a name="func_print"></a>**print**: Prints to the console.
+### <a name="func_print"></a>**print**: Prints to the console. [Back to Top](#gn-reference)
```
Prints all arguments to the console separated by spaces. A newline is
@@ -3129,7 +3129,7 @@
print(sources, deps)
```
-### <a name="func_print_stack_trace"></a>**print_stack_trace**: Prints a stack trace.
+### <a name="func_print_stack_trace"></a>**print_stack_trace**: Prints a stack trace. [Back to Top](#gn-reference)
```
Prints the current file location, and all template invocations that led up to
@@ -3158,7 +3158,7 @@
foo("lala.foo") //BUILD.gn:5
print_stack_trace() //BUILD.gn:2
```
-### <a name="func_process_file_template"></a>**process_file_template**: Do template expansion over a list of files.
+### <a name="func_process_file_template"></a>**process_file_template**: Do template expansion over a list of files. [Back to Top](#gn-reference)
```
process_file_template(source_list, template)
@@ -3203,7 +3203,7 @@
"//out/Debug/bar.cc"
"//out/Debug/bar.h" ]
```
-### <a name="func_read_file"></a>**read_file**: Read a file into a variable.
+### <a name="func_read_file"></a>**read_file**: Read a file into a variable. [Back to Top](#gn-reference)
```
read_file(filename, input_conversion)
@@ -3227,7 +3227,7 @@
```
lines = read_file("foo.txt", "list lines")
```
-### <a name="func_rebase_path"></a>**rebase_path**: Rebase a file or directory to another location.
+### <a name="func_rebase_path"></a>**rebase_path**: Rebase a file or directory to another location. [Back to Top](#gn-reference)
```
converted = rebase_path(input,
@@ -3323,7 +3323,7 @@
] + rebase_path(sources, root_build_dir)
}
```
-### <a name="func_set_default_toolchain"></a>**set_default_toolchain**: Sets the default toolchain name.
+### <a name="func_set_default_toolchain"></a>**set_default_toolchain**: Sets the default toolchain name. [Back to Top](#gn-reference)
```
set_default_toolchain(toolchain_label)
@@ -3363,7 +3363,7 @@
set_default_toolchain("//toolchains:32")
}
```
-### <a name="func_set_defaults"></a>**set_defaults**: Set default values for a target type.
+### <a name="func_set_defaults"></a>**set_defaults**: Set default values for a target type. [Back to Top](#gn-reference)
```
set_defaults(<target_type_name>) { <values...> }
@@ -3397,7 +3397,7 @@
configs -= [ "//tools/mything:settings" ]
}
```
-### <a name="func_split_list"></a>**split_list**: Splits a list into N different sub-lists.
+### <a name="func_split_list"></a>**split_list**: Splits a list into N different sub-lists. [Back to Top](#gn-reference)
```
result = split_list(input, n)
@@ -3420,7 +3420,7 @@
Will print:
[[1, 2], [3, 4], [5, 6]
```
-### <a name="func_string_join"></a>**string_join**: Concatenates a list of strings with a separator.
+### <a name="func_string_join"></a>**string_join**: Concatenates a list of strings with a separator. [Back to Top](#gn-reference)
```
result = string_join(separator, strings)
@@ -3436,7 +3436,7 @@
string_join(", ", ["a", "b", "c"]) --> "a, b, c"
string_join("s", ["", ""]) --> "s"
```
-### <a name="func_string_replace"></a>**string_replace**: Replaces substring in the given string.
+### <a name="func_string_replace"></a>**string_replace**: Replaces substring in the given string. [Back to Top](#gn-reference)
```
result = string_replace(str, old, new[, max])
@@ -3457,7 +3457,7 @@
Will print:
Hello, GN!
```
-### <a name="func_string_split"></a>**string_split**: Split string into a list of strings.
+### <a name="func_string_split"></a>**string_split**: Split string into a list of strings. [Back to Top](#gn-reference)
```
result = string_split(str[, sep])
@@ -3484,7 +3484,7 @@
string_split(" a b ", " ") --> ["", "", "a", "b", "", ""]
string_split("aa+-bb+-c", "+-") --> ["aa", "bb", "c"]
```
-### <a name="func_template"></a>**template**: Define a template rule.
+### <a name="func_template"></a>**template**: Define a template rule. [Back to Top](#gn-reference)
```
A template defines a custom name that acts like a function. It provides a way
@@ -3647,7 +3647,7 @@
deps = [ ":foo_idl_files" ]
}
```
-### <a name="func_tool"></a>**tool**: Specify arguments to a toolchain tool.
+### <a name="func_tool"></a>**tool**: Specify arguments to a toolchain tool. [Back to Top](#gn-reference)
#### **Usage**
@@ -4306,7 +4306,7 @@
}
};
```
-### <a name="func_toolchain"></a>**toolchain**: Defines a toolchain.
+### <a name="func_toolchain"></a>**toolchain**: Defines a toolchain. [Back to Top](#gn-reference)
```
A toolchain is a set of commands and build flags used to compile the source
@@ -4460,7 +4460,7 @@
}
}
```
-### <a name="func_write_file"></a>**write_file**: Write a file to disk.
+### <a name="func_write_file"></a>**write_file**: Write a file to disk. [Back to Top](#gn-reference)
```
write_file(filename, data, output_conversion = "")
@@ -4491,7 +4491,7 @@
```
## <a name="predefined_variables"></a>Built-in predefined variables
-### <a name="var_current_cpu"></a>**current_cpu**: The processor architecture of the current toolchain.
+### <a name="var_current_cpu"></a>**current_cpu**: The processor architecture of the current toolchain. [Back to Top](#gn-reference)
```
The build configuration usually sets this value based on the value of
@@ -4505,7 +4505,7 @@
See "gn help target_cpu" for a list of common values returned.
```
-### <a name="var_current_os"></a>**current_os**: The operating system of the current toolchain.
+### <a name="var_current_os"></a>**current_os**: The operating system of the current toolchain. [Back to Top](#gn-reference)
```
The build configuration usually sets this value based on the value of
@@ -4519,7 +4519,7 @@
See "gn help target_os" for a list of common values returned.
```
-### <a name="var_current_toolchain"></a>**current_toolchain**: Label of the current toolchain.
+### <a name="var_current_toolchain"></a>**current_toolchain**: Label of the current toolchain. [Back to Top](#gn-reference)
```
A fully-qualified label representing the current toolchain. You can use this
@@ -4534,13 +4534,13 @@
executable("output_thats_64_bit_only") {
...
```
-### <a name="var_default_toolchain"></a>**default_toolchain**: [string] Label of the default toolchain.
+### <a name="var_default_toolchain"></a>**default_toolchain**: [string] Label of the default toolchain. [Back to Top](#gn-reference)
```
A fully-qualified label representing the default toolchain, which may not
necessarily be the current one (see "current_toolchain").
```
-### <a name="var_gn_version"></a>**gn_version**: [number] The version of gn.
+### <a name="var_gn_version"></a>**gn_version**: [number] The version of gn. [Back to Top](#gn-reference)
```
Corresponds to the number printed by `gn --version`.
@@ -4551,7 +4551,7 @@
```
assert(gn_version >= 1700, "need GN version 1700 for the frobulate feature")
```
-### <a name="var_host_cpu"></a>**host_cpu**: The processor architecture that GN is running on.
+### <a name="var_host_cpu"></a>**host_cpu**: The processor architecture that GN is running on. [Back to Top](#gn-reference)
```
This is value is exposed so that cross-compile toolchains can access the host
@@ -4569,7 +4569,7 @@
- "x64"
- "x86"
```
-### <a name="var_host_os"></a>**host_os**: [string] The operating system that GN is running on.
+### <a name="var_host_os"></a>**host_os**: [string] The operating system that GN is running on. [Back to Top](#gn-reference)
```
This value is exposed so that cross-compiles can access the host build
@@ -4586,7 +4586,7 @@
- "mac"
- "win"
```
-### <a name="var_invoker"></a>**invoker**: [string] The invoking scope inside a template.
+### <a name="var_invoker"></a>**invoker**: [string] The invoking scope inside a template. [Back to Top](#gn-reference)
```
Inside a template invocation, this variable refers to the scope of the
@@ -4617,14 +4617,14 @@
bar = 123
}
```
-### <a name="var_python_path"></a>**python_path**: Absolute path of Python.
+### <a name="var_python_path"></a>**python_path**: Absolute path of Python. [Back to Top](#gn-reference)
```
Normally used in toolchain definitions if running some command requires
Python. You will normally not need this when invoking scripts since GN
automatically finds it for you.
```
-### <a name="var_root_build_dir"></a>**root_build_dir**: [string] Directory where build commands are run.
+### <a name="var_root_build_dir"></a>**root_build_dir**: [string] Directory where build commands are run. [Back to Top](#gn-reference)
```
This is the root build output directory which will be the current directory
@@ -4633,7 +4633,7 @@
Most often this is used with rebase_path (see "gn help rebase_path") to
convert arguments to be relative to a script's current directory.
```
-### <a name="var_root_gen_dir"></a>**root_gen_dir**: Directory for the toolchain's generated files.
+### <a name="var_root_gen_dir"></a>**root_gen_dir**: Directory for the toolchain's generated files. [Back to Top](#gn-reference)
```
Absolute path to the root of the generated output directory tree for the
@@ -4648,7 +4648,7 @@
See also "target_gen_dir" which is usually a better location for generated
files. It will be inside the root generated dir.
```
-### <a name="var_root_out_dir"></a>**root_out_dir**: [string] Root directory for toolchain output files.
+### <a name="var_root_out_dir"></a>**root_out_dir**: [string] Root directory for toolchain output files. [Back to Top](#gn-reference)
```
Absolute path to the root of the output directory tree for the current
@@ -4674,7 +4674,7 @@
args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
}
```
-### <a name="var_target_cpu"></a>**target_cpu**: The desired cpu architecture for the build.
+### <a name="var_target_cpu"></a>**target_cpu**: The desired cpu architecture for the build. [Back to Top](#gn-reference)
```
This value should be used to indicate the desired architecture for the
@@ -4710,7 +4710,7 @@
- "e2k"
- "loong64"
```
-### <a name="var_target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files.
+### <a name="var_target_gen_dir"></a>**target_gen_dir**: Directory for a target's generated files. [Back to Top](#gn-reference)
```
Absolute path to the target's generated file directory. This will be the
@@ -4734,7 +4734,7 @@
args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]
}
```
-### <a name="var_target_name"></a>**target_name**: [string] The name of the current target.
+### <a name="var_target_name"></a>**target_name**: [string] The name of the current target. [Back to Top](#gn-reference)
```
Inside a target or template invocation, this variable refers to the name
@@ -4773,7 +4773,7 @@
my_template("space_ray") {
}
```
-### <a name="var_target_os"></a>**target_os**: The desired operating system for the build.
+### <a name="var_target_os"></a>**target_os**: The desired operating system for the build. [Back to Top](#gn-reference)
```
This value should be used to indicate the desired operating system for the
@@ -4814,7 +4814,7 @@
- "mac"
- "win"
```
-### <a name="var_target_out_dir"></a>**target_out_dir**: [string] Directory for target output files.
+### <a name="var_target_out_dir"></a>**target_out_dir**: [string] Directory for target output files. [Back to Top](#gn-reference)
```
Absolute path to the target's generated file directory. If your current
@@ -4839,7 +4839,7 @@
```
## <a name="target_variables"></a>Variables you set in targets
-### <a name="var_aliased_deps"></a>**aliased_deps**: [scope] Set of crate-dependency pairs.
+### <a name="var_aliased_deps"></a>**aliased_deps**: [scope] Set of crate-dependency pairs. [Back to Top](#gn-reference)
```
Valid for `rust_library` targets and `executable`, `static_library`, and
@@ -4869,7 +4869,7 @@
With the addition of `aliased_deps`, above target would instead compile with:
`rustc ...command... --extern bar_renamed=<build_out_dir>/obj/bar`
```
-### <a name="var_all_dependent_configs"></a>**all_dependent_configs**: Configs to be forced on dependents.
+### <a name="var_all_dependent_configs"></a>**all_dependent_configs**: Configs to be forced on dependents. [Back to Top](#gn-reference)
```
A list of config labels.
@@ -4905,7 +4905,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_allow_circular_includes_from"></a>**allow_circular_includes_from**: Permit includes from deps.
+### <a name="var_allow_circular_includes_from"></a>**allow_circular_includes_from**: Permit includes from deps. [Back to Top](#gn-reference)
```
A list of target labels. Must be a subset of the target's "deps". These
@@ -4978,7 +4978,7 @@
public_deps = [ ":c" ]
}
```
-### <a name="var_arflags"></a>**arflags**: Arguments passed to static_library archiver.
+### <a name="var_arflags"></a>**arflags**: Arguments passed to static_library archiver. [Back to Top](#gn-reference)
```
A list of flags passed to the archive/lib command that creates static
@@ -5011,7 +5011,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_args"></a>**args**: (target variable) Arguments passed to an action.
+### <a name="var_args"></a>**args**: (target variable) Arguments passed to an action. [Back to Top](#gn-reference)
```
For action and action_foreach targets, args is the list of arguments to pass
@@ -5028,7 +5028,7 @@
See also "gn help action" and "gn help action_foreach".
```
-### <a name="var_asmflags"></a>**asmflags**: Flags passed to the assembler.
+### <a name="var_asmflags"></a>**asmflags**: Flags passed to the assembler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -5054,7 +5054,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_assert_no_deps"></a>**assert_no_deps**: Ensure no deps on these targets.
+### <a name="var_assert_no_deps"></a>**assert_no_deps**: Ensure no deps on these targets. [Back to Top](#gn-reference)
```
A list of label patterns.
@@ -5094,7 +5094,7 @@
]
}
```
-### <a name="var_bridge_header"></a>**bridge_header**: [string] Path to C/Objective-C compatibility header.
+### <a name="var_bridge_header"></a>**bridge_header**: [string] Path to C/Objective-C compatibility header. [Back to Top](#gn-reference)
```
Valid for binary targets that contain Swift sources.
@@ -5102,7 +5102,7 @@
Path to an header that includes C/Objective-C functions and types that
needs to be made available to the Swift module.
```
-### <a name="var_bundle_contents_dir"></a>**bundle_contents_dir**: Expansion of {{bundle_contents_dir}} in
+### <a name="var_bundle_contents_dir"></a>**bundle_contents_dir**: Expansion of {{bundle_contents_dir}} in [Back to Top](#gn-reference)
```
create_bundle.
@@ -5114,7 +5114,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="var_bundle_deps_filter"></a>**bundle_deps_filter**: [label list] A list of labels that are filtered out.
+### <a name="var_bundle_deps_filter"></a>**bundle_deps_filter**: [label list] A list of labels that are filtered out. [Back to Top](#gn-reference)
```
A list of target labels.
@@ -5145,7 +5145,7 @@
]
}
```
-### <a name="var_bundle_executable_dir"></a>**bundle_executable_dir**
+### <a name="var_bundle_executable_dir"></a>**bundle_executable_dir** [Back to Top](#gn-reference)
```
bundle_executable_dir: Expansion of {{bundle_executable_dir}} in
@@ -5159,7 +5159,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="var_bundle_resources_dir"></a>**bundle_resources_dir**
+### <a name="var_bundle_resources_dir"></a>**bundle_resources_dir** [Back to Top](#gn-reference)
```
bundle_resources_dir: Expansion of {{bundle_resources_dir}} in
@@ -5173,7 +5173,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="var_bundle_root_dir"></a>**bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle.
+### <a name="var_bundle_root_dir"></a>**bundle_root_dir**: Expansion of {{bundle_root_dir}} in create_bundle. [Back to Top](#gn-reference)
```
A string corresponding to a path in root_build_dir.
@@ -5199,7 +5199,7 @@
bundle_executable_dir = "${bundle_contents_dir}/MacOS"
}
```
-### <a name="var_cflags"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags"></a>**cflags***: Flags passed to the C compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -5233,7 +5233,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_cflags_c"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_c"></a>**cflags***: Flags passed to the C compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -5267,7 +5267,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_cflags_cc"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_cc"></a>**cflags***: Flags passed to the C compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -5301,7 +5301,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_cflags_objc"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_objc"></a>**cflags***: Flags passed to the C compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -5335,7 +5335,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_cflags_objcc"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_objcc"></a>**cflags***: Flags passed to the C compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -5369,7 +5369,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_check_includes"></a>**check_includes**: [boolean] Controls whether a target's files are checked.
+### <a name="var_check_includes"></a>**check_includes**: [boolean] Controls whether a target's files are checked. [Back to Top](#gn-reference)
```
When true (the default), the "gn check" command (as well as "gn gen" with the
@@ -5397,7 +5397,7 @@
...
}
```
-### <a name="var_code_signing_args"></a>**code_signing_args**: [string list] [deprecated] Args for the post-processing script.
+### <a name="var_code_signing_args"></a>**code_signing_args**: [string list] [deprecated] Args for the post-processing script. [Back to Top](#gn-reference)
```
For create_bundle targets, post_processing_args is the list of arguments to
@@ -5410,7 +5410,7 @@
See also "gn help create_bundle" and "gn help post_processing_args".
```
-### <a name="var_code_signing_outputs"></a>**code_signing_outputs**: [file list] [deprecated] Outputs of the post-processing step.
+### <a name="var_code_signing_outputs"></a>**code_signing_outputs**: [file list] [deprecated] Outputs of the post-processing step. [Back to Top](#gn-reference)
```
Outputs from the post-processing step of a create_bundle target. Must refer to
@@ -5422,7 +5422,7 @@
See also "gn help create_bundle" and "gn help post_processing_args".
```
-### <a name="var_code_signing_script"></a>**code_signing_script**: [file name] [deprecated] Script for the post-processing step."
+### <a name="var_code_signing_script"></a>**code_signing_script**: [file name] [deprecated] Script for the post-processing step." [Back to Top](#gn-reference)
```
An absolute or buildfile-relative file name of a Python script to run for a
@@ -5434,7 +5434,7 @@
See also "gn help create_bundle" and "gn help post_processing_args".
```
-### <a name="var_code_signing_sources"></a>**code_signing_sources**: [file list] [deprecated] Sources for the post-processing step.
+### <a name="var_code_signing_sources"></a>**code_signing_sources**: [file list] [deprecated] Sources for the post-processing step. [Back to Top](#gn-reference)
```
A list of files used as input for the post-processing step of a create_bundle
@@ -5447,7 +5447,7 @@
See also "gn help create_bundle" and "gn help post_processing_args".
```
-### <a name="var_complete_static_lib"></a>**complete_static_lib**: [boolean] Links all deps into a static library.
+### <a name="var_complete_static_lib"></a>**complete_static_lib**: [boolean] Links all deps into a static library. [Back to Top](#gn-reference)
```
A static library normally doesn't include code from dependencies, but instead
@@ -5482,7 +5482,7 @@
deps = [ "bar" ]
}
```
-### <a name="var_configs"></a>**configs**: Configs applying to this target or config.
+### <a name="var_configs"></a>**configs**: Configs applying to this target or config. [Back to Top](#gn-reference)
```
A list of config labels.
@@ -5575,13 +5575,13 @@
}
}
```
-### <a name="var_contents"></a>**contents**: Contents to write to file.
+### <a name="var_contents"></a>**contents**: Contents to write to file. [Back to Top](#gn-reference)
```
The contents of the file for a generated_file target.
See "gn help generated_file".
```
-### <a name="var_crate_name"></a>**crate_name**: [string] The name for the compiled crate.
+### <a name="var_crate_name"></a>**crate_name**: [string] The name for the compiled crate. [Back to Top](#gn-reference)
```
Valid for `rust_library` targets and `executable`, `static_library`,
@@ -5589,7 +5589,7 @@
If crate_name is not set, then this rule will use the target name.
```
-### <a name="var_crate_root"></a>**crate_root**: [string] The root source file for a binary or library.
+### <a name="var_crate_root"></a>**crate_root**: [string] The root source file for a binary or library. [Back to Top](#gn-reference)
```
Valid for `rust_library` targets and `executable`, `static_library`,
@@ -5602,7 +5602,7 @@
main.rs for executable) or a single file in sources, if sources contains
only one file.
```
-### <a name="var_crate_type"></a>**crate_type**: [string] The type of linkage to use on a shared_library.
+### <a name="var_crate_type"></a>**crate_type**: [string] The type of linkage to use on a shared_library. [Back to Top](#gn-reference)
```
Valid for `rust_library` targets and `executable`, `static_library`,
@@ -5622,7 +5622,7 @@
Static libraries, rust libraries, and executables have this field set
automatically.
```
-### <a name="var_data"></a>**data**: Runtime data file dependencies.
+### <a name="var_data"></a>**data**: Runtime data file dependencies. [Back to Top](#gn-reference)
```
Lists files or directories required to run the given target. These are
@@ -5651,7 +5651,7 @@
See "gn help runtime_deps" for how these are used.
```
-### <a name="var_data_deps"></a>**data_deps**: Non-linked dependencies.
+### <a name="var_data_deps"></a>**data_deps**: Non-linked dependencies. [Back to Top](#gn-reference)
```
A list of target labels.
@@ -5677,7 +5677,7 @@
data_deps = [ "//plugins:my_runtime_plugin" ]
}
```
-### <a name="var_data_keys"></a>**data_keys**: Keys from which to collect metadata.
+### <a name="var_data_keys"></a>**data_keys**: Keys from which to collect metadata. [Back to Top](#gn-reference)
```
These keys are used to identify metadata to collect. If a walked target
@@ -5686,7 +5686,7 @@
See "gn help generated_file".
```
-### <a name="var_defines"></a>**defines**: C preprocessor defines.
+### <a name="var_defines"></a>**defines**: C preprocessor defines. [Back to Top](#gn-reference)
```
A list of strings
@@ -5718,7 +5718,7 @@
```
defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ]
```
-### <a name="var_depfile"></a>**depfile**: [string] File name for input dependencies for actions.
+### <a name="var_depfile"></a>**depfile**: [string] File name for input dependencies for actions. [Back to Top](#gn-reference)
```
If nonempty, this string specifies that the current action or action_foreach
@@ -5757,7 +5757,7 @@
args = [ "{{source}}", "-o", rebase_path(depfile, root_build_dir)]
}
```
-### <a name="var_deps"></a>**deps**: Private linked dependencies.
+### <a name="var_deps"></a>**deps**: Private linked dependencies. [Back to Top](#gn-reference)
```
A list of target labels.
@@ -5794,7 +5794,7 @@
See also "public_deps".
```
-### <a name="var_externs"></a>**externs**: [scope] Set of Rust crate-dependency pairs.
+### <a name="var_externs"></a>**externs**: [scope] Set of Rust crate-dependency pairs. [Back to Top](#gn-reference)
```
A list, each value being a scope indicating a pair of crate name and the path
@@ -5818,7 +5818,7 @@
This target would compile the `foo` crate with the following `extern` flag:
`--extern bar=path/to/bar.rlib`.
```
-### <a name="var_framework_dirs"></a>**framework_dirs**: [directory list] Additional framework search directories.
+### <a name="var_framework_dirs"></a>**framework_dirs**: [directory list] Additional framework search directories. [Back to Top](#gn-reference)
```
A list of source directories.
@@ -5850,7 +5850,7 @@
```
framework_dirs = [ "src/include", "//third_party/foo" ]
```
-### <a name="var_frameworks"></a>**frameworks**: [name list] Name of frameworks that must be linked.
+### <a name="var_frameworks"></a>**frameworks**: [name list] Name of frameworks that must be linked. [Back to Top](#gn-reference)
```
A list of framework names.
@@ -5882,7 +5882,7 @@
```
frameworks = [ "Foundation.framework", "Foo.framework" ]
```
-### <a name="var_friend"></a>**friend**: Allow targets to include private headers.
+### <a name="var_friend"></a>**friend**: Allow targets to include private headers. [Back to Top](#gn-reference)
```
A list of label patterns (see "gn help label_pattern") that allow dependent
@@ -5943,7 +5943,7 @@
]
}
```
-### <a name="var_gen_deps"></a>**gen_deps**: Declares targets that should generate when this one does.
+### <a name="var_gen_deps"></a>**gen_deps**: Declares targets that should generate when this one does. [Back to Top](#gn-reference)
```
A list of target labels.
@@ -5955,7 +5955,7 @@
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.
+### <a name="var_include_dirs"></a>**include_dirs**: Additional include directories. [Back to Top](#gn-reference)
```
A list of source directories.
@@ -5987,7 +5987,7 @@
```
include_dirs = [ "src/include", "//third_party/foo" ]
```
-### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies.
+### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies. [Back to Top](#gn-reference)
```
Inputs are compile-time dependencies of the current target. This means that
@@ -6057,7 +6057,7 @@
inputs = [ "input.data" ]
}
```
-### <a name="var_ldflags"></a>**ldflags**: Flags passed to the linker.
+### <a name="var_ldflags"></a>**ldflags**: Flags passed to the linker. [Back to Top](#gn-reference)
```
A list of strings.
@@ -6089,7 +6089,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_lib_dirs"></a>**lib_dirs**: Additional library directories.
+### <a name="var_lib_dirs"></a>**lib_dirs**: Additional library directories. [Back to Top](#gn-reference)
```
A list of directories.
@@ -6132,7 +6132,7 @@
```
lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
```
-### <a name="var_libs"></a>**libs**: Additional libraries to link.
+### <a name="var_libs"></a>**libs**: Additional libraries to link. [Back to Top](#gn-reference)
```
A list of library names or library paths.
@@ -6199,7 +6199,7 @@
On Linux:
libs = [ "ld" ]
```
-### <a name="var_metadata"></a>**metadata**: Metadata of this target.
+### <a name="var_metadata"></a>**metadata**: Metadata of this target. [Back to Top](#gn-reference)
```
Metadata is a collection of keys and values relating to a particular target.
@@ -6224,7 +6224,7 @@
}
}
```
-### <a name="var_mnemonic"></a>**mnemonic**: [string] Prefix displayed when ninja runs this action.
+### <a name="var_mnemonic"></a>**mnemonic**: [string] Prefix displayed when ninja runs this action. [Back to Top](#gn-reference)
```
Tools in GN can set their ninja "description" which is displayed when
@@ -6235,20 +6235,20 @@
Whitespace is not allowed within a mnemonic.
```
-### <a name="var_module_name"></a>**module_name**: [string] The name for the compiled module.
+### <a name="var_module_name"></a>**module_name**: [string] The name for the compiled module. [Back to Top](#gn-reference)
```
Valid for binary targets that contain Swift sources.
If module_name is not set, then this rule will use the target name.
```
-### <a name="var_output_conversion"></a>**output_conversion**: Data format for generated_file targets.
+### <a name="var_output_conversion"></a>**output_conversion**: Data format for generated_file targets. [Back to Top](#gn-reference)
```
Controls how the "contents" of a generated_file target is formatted.
See `gn help io_conversion`.
```
-### <a name="var_output_dir"></a>**output_dir**: [directory] Directory to put output file in.
+### <a name="var_output_dir"></a>**output_dir**: [directory] Directory to put output file in. [Back to Top](#gn-reference)
```
For library and executable targets, overrides the directory for the final
@@ -6275,7 +6275,7 @@
...
}
```
-### <a name="var_output_extension"></a>**output_extension**: Value to use for the output's file extension.
+### <a name="var_output_extension"></a>**output_extension**: Value to use for the output's file extension. [Back to Top](#gn-reference)
```
Normally the file extension for a target is based on the target type and the
@@ -6311,7 +6311,7 @@
}
}
```
-### <a name="var_output_name"></a>**output_name**: Define a name for the output file other than the default.
+### <a name="var_output_name"></a>**output_name**: Define a name for the output file other than the default. [Back to Top](#gn-reference)
```
Normally the output name of a target will be based on the target name, so the
@@ -6337,7 +6337,7 @@
output_name = "fluffy_bunny"
}
```
-### <a name="var_output_prefix_override"></a>**output_prefix_override**: Don't use prefix for output name.
+### <a name="var_output_prefix_override"></a>**output_prefix_override**: Don't use prefix for output name. [Back to Top](#gn-reference)
```
A boolean that overrides the output prefix for a target. Defaults to false.
@@ -6361,7 +6361,7 @@
...
}
```
-### <a name="var_outputs"></a>**outputs**: Output files for actions and copy targets.
+### <a name="var_outputs"></a>**outputs**: Output files for actions and copy targets. [Back to Top](#gn-reference)
```
Outputs is valid for "copy", "action", and "action_foreach" target types and
@@ -6384,7 +6384,7 @@
Action targets (excluding action_foreach) must list literal output file(s)
with no source expansions. See "gn help action".
```
-### <a name="var_partial_info_plist"></a>**partial_info_plist**: [filename] Path plist from asset catalog compiler.
+### <a name="var_partial_info_plist"></a>**partial_info_plist**: [filename] Path plist from asset catalog compiler. [Back to Top](#gn-reference)
```
Valid for create_bundle target, corresponds to the path for the partial
@@ -6394,7 +6394,7 @@
The file will be generated regardless of whether the asset compiler has
been invoked or not. See "gn help create_bundle".
```
-### <a name="var_pool"></a>**pool**: Label of the pool used by binary targets actions.
+### <a name="var_pool"></a>**pool**: Label of the pool used by binary targets actions. [Back to Top](#gn-reference)
```
A fully-qualified label representing the pool that will be used for binary
@@ -6414,7 +6414,7 @@
...
}
```
-### <a name="var_post_processing_args"></a>**post_processing_args**: [string list] Args for the post-processing script.
+### <a name="var_post_processing_args"></a>**post_processing_args**: [string list] Args for the post-processing script. [Back to Top](#gn-reference)
```
For create_bundle targets, post_processing_args is the list of arguments to
@@ -6423,7 +6423,7 @@
See also "gn help create_bundle".
```
-### <a name="var_post_processing_outputs"></a>**post_processing_outputs**: [file list] Outputs of the post-processing step.
+### <a name="var_post_processing_outputs"></a>**post_processing_outputs**: [file list] Outputs of the post-processing step. [Back to Top](#gn-reference)
```
Outputs from the post-processing step of a create_bundle target. Must refer to
@@ -6431,7 +6431,7 @@
See also "gn help create_bundle".
```
-### <a name="var_post_processing_script"></a>**post_processing_script**: [file name] Script for the post-processing step."
+### <a name="var_post_processing_script"></a>**post_processing_script**: [file name] Script for the post-processing step." [Back to Top](#gn-reference)
```
An absolute or buildfile-relative file name of a Python script to run for a
@@ -6439,7 +6439,7 @@
See also "gn help create_bundle".
```
-### <a name="var_post_processing_sources"></a>**post_processing_sources**: [file list] Sources for the post-processing step.
+### <a name="var_post_processing_sources"></a>**post_processing_sources**: [file list] Sources for the post-processing step. [Back to Top](#gn-reference)
```
A list of files used as input for the post-processing step of a create_bundle
@@ -6448,7 +6448,7 @@
See also "gn help create_bundle".
```
-### <a name="var_precompiled_header"></a>**precompiled_header**: [string] Header file to precompile.
+### <a name="var_precompiled_header"></a>**precompiled_header**: [string] Header file to precompile. [Back to Top](#gn-reference)
```
Precompiled headers will be used when a target specifies this value, or a
@@ -6516,19 +6516,19 @@
configs += [ ":use_precompiled_headers" ]
...
```
-### <a name="var_precompiled_header_type"></a>**precompiled_header_type**: [string] "gcc" or "msvc".
+### <a name="var_precompiled_header_type"></a>**precompiled_header_type**: [string] "gcc" or "msvc". [Back to Top](#gn-reference)
```
See "gn help precompiled_header".
```
-### <a name="var_precompiled_source"></a>**precompiled_source**: [file name] Source file to precompile.
+### <a name="var_precompiled_source"></a>**precompiled_source**: [file name] Source file to precompile. [Back to Top](#gn-reference)
```
The source file that goes along with the precompiled_header when using
"msvc"-style precompiled headers. It will be implicitly added to the sources
of the target. See "gn help precompiled_header".
```
-### <a name="var_product_type"></a>**product_type**: [string] Product type for the bundle.
+### <a name="var_product_type"></a>**product_type**: [string] Product type for the bundle. [Back to Top](#gn-reference)
```
Valid for "create_bundle" and "bundle_data" targets.
@@ -6540,7 +6540,7 @@
"create_bundle" with a non-empty product_type will have a corresponding
target in the project.
```
-### <a name="var_public"></a>**public**: Declare public header files for a target.
+### <a name="var_public"></a>**public**: Declare public header files for a target. [Back to Top](#gn-reference)
```
A list of files that other targets can include. These permissions are checked
@@ -6593,7 +6593,7 @@
# This allows starting compilation in dependent targets earlier.
public = []
```
-### <a name="var_public_configs"></a>**public_configs**: Configs to be applied on dependents.
+### <a name="var_public_configs"></a>**public_configs**: Configs to be applied on dependents. [Back to Top](#gn-reference)
```
A list of config labels.
@@ -6684,7 +6684,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_public_deps"></a>**public_deps**: Declare public dependencies.
+### <a name="var_public_deps"></a>**public_deps**: Declare public dependencies. [Back to Top](#gn-reference)
```
Public dependencies are like private dependencies (see "gn help deps") but
@@ -6735,7 +6735,7 @@
public_deps = [ ":c" ]
}
```
-### <a name="var_rebase"></a>**rebase**: Rebase collected metadata as files.
+### <a name="var_rebase"></a>**rebase**: Rebase collected metadata as files. [Back to Top](#gn-reference)
```
A boolean that triggers a rebase of collected metadata strings based on their
@@ -6751,7 +6751,7 @@
See also "gn help generated_file".
```
-### <a name="var_response_file_contents"></a>**response_file_contents**: Contents of a response file for actions.
+### <a name="var_response_file_contents"></a>**response_file_contents**: Contents of a response file for actions. [Back to Top](#gn-reference)
```
Sometimes the arguments passed to a script can be too long for the system's
@@ -6789,21 +6789,21 @@
]
}
```
-### <a name="var_rustflags"></a>**rustflags**: Flags passed to the Rust compiler.
+### <a name="var_rustflags"></a>**rustflags**: Flags passed to the Rust compiler. [Back to Top](#gn-reference)
```
A list of strings.
"rustflags" are passed to all invocations of the Rust compiler.
```
-### <a name="var_script"></a>**script**: Script file for actions.
+### <a name="var_script"></a>**script**: Script file for actions. [Back to Top](#gn-reference)
```
An absolute or buildfile-relative file name of a Python script to run for a
action and action_foreach targets (see "gn help action" and "gn help
action_foreach").
```
-### <a name="var_sources"></a>**sources**: Source files for a target
+### <a name="var_sources"></a>**sources**: Source files for a target [Back to Top](#gn-reference)
```
A list of files. Non-absolute paths will be resolved relative to the current
@@ -6845,7 +6845,7 @@
copy
The source are the source files to copy.
```
-### <a name="var_swiftflags"></a>**swiftflags**: Flags passed to the swift compiler.
+### <a name="var_swiftflags"></a>**swiftflags**: Flags passed to the swift compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -6871,7 +6871,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="var_testonly"></a>**testonly**: Declares a target must only be used for testing.
+### <a name="var_testonly"></a>**testonly**: Declares a target must only be used for testing. [Back to Top](#gn-reference)
```
Boolean. Defaults to false.
@@ -6892,7 +6892,7 @@
...
}
```
-### <a name="var_transparent"></a>**transparent**: [bool] True if the bundle is transparent.
+### <a name="var_transparent"></a>**transparent**: [bool] True if the bundle is transparent. [Back to Top](#gn-reference)
```
A boolean.
@@ -6902,7 +6902,7 @@
depends on it (unless the "bundle_data" target sets "product_type" to the
same value as the "create_bundle" target).
```
-### <a name="var_visibility"></a>**visibility**: A list of labels that can depend on a target.
+### <a name="var_visibility"></a>**visibility**: A list of labels that can depend on a target. [Back to Top](#gn-reference)
```
A list of labels and label patterns that define which targets can depend on
@@ -6957,7 +6957,7 @@
any targets in "//bar/" and any subdirectory thereof.
visibility = [ "./*", "//bar/*" ]
```
-### <a name="var_walk_keys"></a>**walk_keys**: Key(s) for managing the metadata collection walk.
+### <a name="var_walk_keys"></a>**walk_keys**: Key(s) for managing the metadata collection walk. [Back to Top](#gn-reference)
```
Defaults to [""].
@@ -6971,7 +6971,7 @@
See "gn help generated_file".
```
-### <a name="var_weak_frameworks"></a>**weak_frameworks**: [name list] Name of frameworks that must be weak linked.
+### <a name="var_weak_frameworks"></a>**weak_frameworks**: [name list] Name of frameworks that must be weak linked. [Back to Top](#gn-reference)
```
A list of framework names.
@@ -7007,7 +7007,7 @@
```
weak_frameworks = [ "OnlyOnNewerOSes.framework" ]
```
-### <a name="var_write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps to the given path.
+### <a name="var_write_runtime_deps"></a>**write_runtime_deps**: Writes the target's runtime_deps to the given path. [Back to Top](#gn-reference)
```
Does not synchronously write the file, but rather schedules it to be written
@@ -7027,7 +7027,7 @@
same as requesting the runtime deps be written on the command line (see "gn
help --runtime-deps-list-file").
```
-### <a name="var_xcasset_compiler_flags"></a>**xcasset_compiler_flags**: Flags passed to xcassets compiler.
+### <a name="var_xcasset_compiler_flags"></a>**xcasset_compiler_flags**: Flags passed to xcassets compiler. [Back to Top](#gn-reference)
```
A list of strings.
@@ -7036,7 +7036,7 @@
xcassets compiler, corresponding to {{xcasset_compiler_flags}} substitution
in compile_xcassets tool.
```
-### <a name="var_xcode_extra_attributes"></a>**xcode_extra_attributes**: [scope] Extra attributes for Xcode projects.
+### <a name="var_xcode_extra_attributes"></a>**xcode_extra_attributes**: [scope] Extra attributes for Xcode projects. [Back to Top](#gn-reference)
```
The value defined in this scope will be copied to the EXTRA_ATTRIBUTES
@@ -7045,7 +7045,7 @@
See "gn help create_bundle" for more information.
```
-### <a name="var_xcode_test_application_name"></a>**xcode_test_application_name**: Name for Xcode test target.
+### <a name="var_xcode_test_application_name"></a>**xcode_test_application_name**: Name for Xcode test target. [Back to Top](#gn-reference)
```
Each unit and ui test target must have a test application target, and this
@@ -7065,7 +7065,7 @@
```
## <a name="other"></a>Other help topics
-### <a name="buildargs"></a>**Build Arguments Overview**
+### <a name="buildargs"></a>**Build Arguments Overview** [Back to Top](#gn-reference)
```
Build arguments are variables passed in from outside of the build that build
@@ -7129,7 +7129,7 @@
that apply only to those files. It is also useful to specify build args in an
"import"-ed file if you want such arguments to apply to multiple buildfiles.
```
-### <a name="dotfile"></a>**.gn file**
+### <a name="dotfile"></a>**.gn file** [Back to Top](#gn-reference)
```
When gn starts, it will search the current directory and parent directories
@@ -7312,7 +7312,7 @@
is_component_build = false
}
```
-### <a name="execution"></a>**Build graph and execution overview**
+### <a name="execution"></a>**Build graph and execution overview** [Back to Top](#gn-reference)
#### **Overall build flow**
@@ -7405,7 +7405,7 @@
from a build performance perspective. Since we hope to change this in the
future, do not rely on this behavior.
```
-### <a name="grammar"></a>**Language and grammar for GN build files**
+### <a name="grammar"></a>**Language and grammar for GN build files** [Back to Top](#gn-reference)
#### **Tokens**
@@ -7632,7 +7632,7 @@
within the second, and vice versa. Note that this means inherited scopes are
always unequal by definition.
```
-### <a name="io_conversion"></a>**Input and output conversion**
+### <a name="io_conversion"></a>**Input and output conversion** [Back to Top](#gn-reference)
```
Input and output conversions are arguments to file and process functions
@@ -7736,7 +7736,7 @@
Note that "trim value" is useless because the value parser skips
whitespace anyway.
```
-### <a name="file_pattern"></a>**File patterns**
+### <a name="file_pattern"></a>**File patterns** [Back to Top](#gn-reference)
```
File patterns are VERY limited regular expressions. They must match the
@@ -7770,7 +7770,7 @@
"\bwin/*"
Matches "win/foo" and "foo/win/bar.cc" but not "iwin/foo".
```
-### <a name="label_pattern"></a>**Label patterns**
+### <a name="label_pattern"></a>**Label patterns** [Back to Top](#gn-reference)
```
A label pattern is a way of expressing one or more labels in a portion of the
@@ -7806,7 +7806,7 @@
All targets in //foo and any subdirectory using the Windows
toolchain.
```
-### <a name="labels"></a>**About labels**
+### <a name="labels"></a>**About labels** [Back to Top](#gn-reference)
```
Everything that can participate in the dependency graph (targets, configs,
@@ -7866,7 +7866,7 @@
//net -> //net:net
//tools/gn -> //tools/gn:gn
```
-### <a name="metadata_collection"></a>**Metadata Collection**
+### <a name="metadata_collection"></a>**Metadata Collection** [Back to Top](#gn-reference)
```
Metadata is information attached to targets throughout the dependency tree. GN
@@ -8009,7 +8009,7 @@
various pieces of information about the components it should include in order
to put together the correct image.
```
-### <a name="ninja_rules"></a>**Ninja build rules**
+### <a name="ninja_rules"></a>**Ninja build rules** [Back to Top](#gn-reference)
#### **The "all" and "default" rules**
@@ -8062,7 +8062,7 @@
To explicitly compile a target in a non-default toolchain, you must give
Ninja the exact name of the output file relative to the build directory.
```
-### <a name="nogncheck"></a>**nogncheck**: Skip an include line from checking.
+### <a name="nogncheck"></a>**nogncheck**: Skip an include line from checking. [Back to Top](#gn-reference)
```
GN's header checker helps validate that the includes match the build
@@ -8099,7 +8099,7 @@
advice on fixing problems. Targets can also opt-out of checking, see
"gn help check_includes".
```
-### <a name="runtime_deps"></a>**Runtime dependencies**
+### <a name="runtime_deps"></a>**Runtime dependencies** [Back to Top](#gn-reference)
```
Runtime dependencies of a target are exposed via the "runtime_deps" category
@@ -8175,7 +8175,7 @@
computing the runtime deps by setting runtime_outputs. If this is unset on
the tool, the default will be the first output only.
```
-### <a name="source_expansion"></a>**How Source Expansion Works**
+### <a name="source_expansion"></a>**How Source Expansion Works** [Back to Top](#gn-reference)
```
Source expansion is used for the action_foreach and copy target types to map
@@ -8290,7 +8290,7 @@
//out/Debug/obj/mydirectory/input2.h
//out/Debug/obj/mydirectory/input2.cc
```
-### <a name="switch_list"></a>**Available global switches**
+### <a name="switch_list"></a>**Available global switches** [Back to Top](#gn-reference)
```
Do "gn help --the_switch_you_want_help_on" for more. Individual commands may
diff --git a/src/gn/standard_out.cc b/src/gn/standard_out.cc
index 1d43e05..2ff353c 100644
--- a/src/gn/standard_out.cc
+++ b/src/gn/standard_out.cc
@@ -297,7 +297,6 @@
if (first_header && !tag.empty()) {
OutputString("### <a name=\"" + tag + "\"></a>", DECORATION_NONE,
NO_ESCAPING);
- first_header = false;
} else {
OutputString("#### ", DECORATION_NONE);
}
@@ -310,6 +309,10 @@
OutputString(line.substr(0, chars_to_highlight), DECORATION_YELLOW);
OutputString(line.substr(chars_to_highlight));
+ if (first_header) {
+ OutputString(" [Back to Top](#gn-reference)", DECORATION_NONE);
+ first_header = false;
+ }
OutputString("\n");
continue;
} else if (is_markdown && !line.empty() && !in_body) {
