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) {