Improve help output.
Make the links in markdown for the "args" command and target variable
work by disambiguating href names in by variable type.
Special-case "gn help args" on the command line by printing help for
both the command and the variable.
Fix misnaming of xcode_test_application_name.
Fix incorrect linking of switch help and bad hadings and wrapping for
input and output conversion help.
Simplify markdown tag emitting by requiring the the caller generate
a tag for linking rather than trying to autogenerate one based on
text that comes before a colon. This autogeneration code was not
used.
Change-Id: I7dd3f806eac5afaef746b2e37bf0903d9ae72b14
Reviewed-on: https://gn-review.googlesource.com/c/3520
Reviewed-by: Julie Hockett <juliehockett@google.com>
Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/docs/reference.md b/docs/reference.md
index cb6960d..11e8212 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -5,143 +5,143 @@
## Contents
* [Commands](#commands)
- * [analyze: Analyze which targets are affected by a list of files.](#analyze)
- * [args: Display or configure arguments declared by the build.](#args)
- * [check: Check header dependencies.](#check)
- * [clean: Cleans the output directory.](#clean)
- * [desc: Show lots of insightful information about a target or config.](#desc)
- * [format: Format .gn file.](#format)
- * [gen: Generate ninja files.](#gen)
- * [help: Does what you think.](#help)
- * [ls: List matching targets.](#ls)
- * [meta: List target metadata collection results.](#meta)
- * [path: Find paths between two targets.](#path)
- * [refs: Find stuff referencing a target or file.](#refs)
+ * [analyze: Analyze which targets are affected by a list of files.](#cmd_analyze)
+ * [args: Display or configure arguments declared by the build.](#cmd_args)
+ * [check: Check header dependencies.](#cmd_check)
+ * [clean: Cleans the output directory.](#cmd_clean)
+ * [desc: Show lots of insightful information about a target or config.](#cmd_desc)
+ * [format: Format .gn file.](#cmd_format)
+ * [gen: Generate ninja files.](#cmd_gen)
+ * [help: Does what you think.](#cmd_help)
+ * [ls: List matching targets.](#cmd_ls)
+ * [meta: List target metadata collection results.](#cmd_meta)
+ * [path: Find paths between two targets.](#cmd_path)
+ * [refs: Find stuff referencing a target or file.](#cmd_refs)
* [Target declarations](#targets)
- * [action: Declare a target that runs a script a single time.](#action)
- * [action_foreach: Declare a target that runs a script over a set of files.](#action_foreach)
- * [bundle_data: [iOS/macOS] Declare a target without output.](#bundle_data)
- * [copy: Declare a target that copies files.](#copy)
- * [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#create_bundle)
- * [executable: Declare an executable target.](#executable)
- * [generated_file: Declare a generated_file target.](#generated_file)
- * [group: Declare a named group of targets.](#group)
- * [loadable_module: Declare a loadable module target.](#loadable_module)
- * [shared_library: Declare a shared library target.](#shared_library)
- * [source_set: Declare a source set target.](#source_set)
- * [static_library: Declare a static library target.](#static_library)
- * [target: Declare an target with the given programmatic type.](#target)
+ * [action: Declare a target that runs a script a single time.](#func_action)
+ * [action_foreach: Declare a target that runs a script over a set of files.](#func_action_foreach)
+ * [bundle_data: [iOS/macOS] Declare a target without output.](#func_bundle_data)
+ * [copy: Declare a target that copies files.](#func_copy)
+ * [create_bundle: [iOS/macOS] Build an iOS or macOS bundle.](#func_create_bundle)
+ * [executable: Declare an executable target.](#func_executable)
+ * [generated_file: Declare a generated_file target.](#func_generated_file)
+ * [group: Declare a named group of targets.](#func_group)
+ * [loadable_module: Declare a loadable module target.](#func_loadable_module)
+ * [shared_library: Declare a shared library target.](#func_shared_library)
+ * [source_set: Declare a source set target.](#func_source_set)
+ * [static_library: Declare a static library target.](#func_static_library)
+ * [target: Declare an target with the given programmatic type.](#func_target)
* [Buildfile functions](#functions)
- * [assert: Assert an expression is true at generation time.](#assert)
- * [config: Defines a configuration object.](#config)
- * [declare_args: Declare build arguments.](#declare_args)
- * [defined: Returns whether an identifier is defined.](#defined)
- * [exec_script: Synchronously run a script and return the output.](#exec_script)
- * [foreach: Iterate over a list.](#foreach)
- * [forward_variables_from: Copies variables from a different scope.](#forward_variables_from)
- * [get_label_info: Get an attribute from a target's label.](#get_label_info)
- * [get_path_info: Extract parts of a file or directory name.](#get_path_info)
- * [get_target_outputs: [file list] Get the list of outputs from a target.](#get_target_outputs)
- * [getenv: Get an environment variable.](#getenv)
- * [import: Import a file into the current scope.](#import)
- * [not_needed: Mark variables from scope as not needed.](#not_needed)
- * [pool: Defines a pool object.](#pool)
- * [print: Prints to the console.](#print)
- * [process_file_template: Do template expansion over a list of files.](#process_file_template)
- * [read_file: Read a file into a variable.](#read_file)
- * [rebase_path: Rebase a file or directory to another location.](#rebase_path)
- * [set_default_toolchain: Sets the default toolchain name.](#set_default_toolchain)
- * [set_defaults: Set default values for a target type.](#set_defaults)
- * [set_sources_assignment_filter: Set a pattern to filter source files.](#set_sources_assignment_filter)
- * [split_list: Splits a list into N different sub-lists.](#split_list)
- * [string_replace: Replaces substring in the given string.](#string_replace)
- * [template: Define a template rule.](#template)
- * [tool: Specify arguments to a toolchain tool.](#tool)
- * [toolchain: Defines a toolchain.](#toolchain)
- * [write_file: Write a file to disk.](#write_file)
+ * [assert: Assert an expression is true at generation time.](#func_assert)
+ * [config: Defines a configuration object.](#func_config)
+ * [declare_args: Declare build arguments.](#func_declare_args)
+ * [defined: Returns whether an identifier is defined.](#func_defined)
+ * [exec_script: Synchronously run a script and return the output.](#func_exec_script)
+ * [foreach: Iterate over a list.](#func_foreach)
+ * [forward_variables_from: Copies variables from a different scope.](#func_forward_variables_from)
+ * [get_label_info: Get an attribute from a target's label.](#func_get_label_info)
+ * [get_path_info: Extract parts of a file or directory name.](#func_get_path_info)
+ * [get_target_outputs: [file list] Get the list of outputs from a target.](#func_get_target_outputs)
+ * [getenv: Get an environment variable.](#func_getenv)
+ * [import: Import a file into the current scope.](#func_import)
+ * [not_needed: Mark variables from scope as not needed.](#func_not_needed)
+ * [pool: Defines a pool object.](#func_pool)
+ * [print: Prints to the console.](#func_print)
+ * [process_file_template: Do template expansion over a list of files.](#func_process_file_template)
+ * [read_file: Read a file into a variable.](#func_read_file)
+ * [rebase_path: Rebase a file or directory to another location.](#func_rebase_path)
+ * [set_default_toolchain: Sets the default toolchain name.](#func_set_default_toolchain)
+ * [set_defaults: Set default values for a target type.](#func_set_defaults)
+ * [set_sources_assignment_filter: Set a pattern to filter source files.](#func_set_sources_assignment_filter)
+ * [split_list: Splits a list into N different sub-lists.](#func_split_list)
+ * [string_replace: Replaces substring in the given string.](#func_string_replace)
+ * [template: Define a template rule.](#func_template)
+ * [tool: Specify arguments to a toolchain tool.](#func_tool)
+ * [toolchain: Defines a toolchain.](#func_toolchain)
+ * [write_file: Write a file to disk.](#func_write_file)
* [Built-in predefined variables](#predefined_variables)
- * [current_cpu: [string] The processor architecture of the current toolchain.](#current_cpu)
- * [current_os: [string] The operating system of the current toolchain.](#current_os)
- * [current_toolchain: [string] Label of the current toolchain.](#current_toolchain)
- * [default_toolchain: [string] Label of the default toolchain.](#default_toolchain)
- * [host_cpu: [string] The processor architecture that GN is running on.](#host_cpu)
- * [host_os: [string] The operating system that GN is running on.](#host_os)
- * [invoker: [string] The invoking scope inside a template.](#invoker)
- * [python_path: [string] Absolute path of Python.](#python_path)
- * [root_build_dir: [string] Directory where build commands are run.](#root_build_dir)
- * [root_gen_dir: [string] Directory for the toolchain's generated files.](#root_gen_dir)
- * [root_out_dir: [string] Root directory for toolchain output files.](#root_out_dir)
- * [target_cpu: [string] The desired cpu architecture for the build.](#target_cpu)
- * [target_gen_dir: [string] Directory for a target's generated files.](#target_gen_dir)
- * [target_name: [string] The name of the current target.](#target_name)
- * [target_os: [string] The desired operating system for the build.](#target_os)
- * [target_out_dir: [string] Directory for target output files.](#target_out_dir)
+ * [current_cpu: [string] The processor architecture of the current toolchain.](#var_current_cpu)
+ * [current_os: [string] The operating system of the current toolchain.](#var_current_os)
+ * [current_toolchain: [string] Label of the current toolchain.](#var_current_toolchain)
+ * [default_toolchain: [string] Label of the default toolchain.](#var_default_toolchain)
+ * [host_cpu: [string] The processor architecture that GN is running on.](#var_host_cpu)
+ * [host_os: [string] The operating system that GN is running on.](#var_host_os)
+ * [invoker: [string] The invoking scope inside a template.](#var_invoker)
+ * [python_path: [string] Absolute path of Python.](#var_python_path)
+ * [root_build_dir: [string] Directory where build commands are run.](#var_root_build_dir)
+ * [root_gen_dir: [string] Directory for the toolchain's generated files.](#var_root_gen_dir)
+ * [root_out_dir: [string] Root directory for toolchain output files.](#var_root_out_dir)
+ * [target_cpu: [string] The desired cpu architecture for the build.](#var_target_cpu)
+ * [target_gen_dir: [string] Directory for a target's generated files.](#var_target_gen_dir)
+ * [target_name: [string] The name of the current target.](#var_target_name)
+ * [target_os: [string] The desired operating system for the build.](#var_target_os)
+ * [target_out_dir: [string] Directory for target output files.](#var_target_out_dir)
* [Variables you set in targets](#target_variables)
- * [all_dependent_configs: [label list] Configs to be forced on dependents.](#all_dependent_configs)
- * [allow_circular_includes_from: [label list] Permit includes from deps.](#allow_circular_includes_from)
- * [arflags: [string list] Arguments passed to static_library archiver.](#arflags)
- * [args: [string list] Arguments passed to an action.](#args)
- * [asmflags: [string list] Flags passed to the assembler.](#asmflags)
- * [assert_no_deps: [label pattern list] Ensure no deps on these targets.](#assert_no_deps)
- * [bundle_contents_dir: Expansion of {{bundle_contents_dir}} in create_bundle.](#bundle_contents_dir)
- * [bundle_deps_filter: [label list] A list of labels that are filtered out.](#bundle_deps_filter)
- * [bundle_executable_dir: Expansion of {{bundle_executable_dir}} in create_bundle](#bundle_executable_dir)
- * [bundle_plugins_dir: Expansion of {{bundle_plugins_dir}} in create_bundle.](#bundle_plugins_dir)
- * [bundle_resources_dir: Expansion of {{bundle_resources_dir}} in create_bundle.](#bundle_resources_dir)
- * [bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.](#bundle_root_dir)
- * [cflags: [string list] Flags passed to all C compiler variants.](#cflags)
- * [cflags_c: [string list] Flags passed to the C compiler.](#cflags_c)
- * [cflags_cc: [string list] Flags passed to the C++ compiler.](#cflags_cc)
- * [cflags_objc: [string list] Flags passed to the Objective C compiler.](#cflags_objc)
- * [cflags_objcc: [string list] Flags passed to the Objective C++ compiler.](#cflags_objcc)
- * [check_includes: [boolean] Controls whether a target's files are checked.](#check_includes)
- * [code_signing_args: [string list] Arguments passed to code signing script.](#code_signing_args)
- * [code_signing_outputs: [file list] Output files for code signing step.](#code_signing_outputs)
- * [code_signing_script: [file name] Script for code signing.](#code_signing_script)
- * [code_signing_sources: [file list] Sources for code signing step.](#code_signing_sources)
- * [complete_static_lib: [boolean] Links all deps into a static library.](#complete_static_lib)
- * [configs: [label list] Configs applying to this target or config.](#configs)
- * [contents: Contents to write to file.](#contents)
- * [data: [file list] Runtime data file dependencies.](#data)
- * [data_deps: [label list] Non-linked dependencies.](#data_deps)
- * [data_keys: [string list] Keys from which to collect metadata.](#data_keys)
- * [defines: [string list] C preprocessor defines.](#defines)
- * [depfile: [string] File name for input dependencies for actions.](#depfile)
- * [deps: [label list] Private linked dependencies.](#deps)
- * [friend: [label pattern list] Allow targets to include private headers.](#friend)
- * [include_dirs: [directory list] Additional include directories.](#include_dirs)
- * [inputs: [file list] Additional compile-time dependencies.](#inputs)
- * [ldflags: [string list] Flags passed to the linker.](#ldflags)
- * [lib_dirs: [directory list] Additional library directories.](#lib_dirs)
- * [libs: [string list] Additional libraries to link.](#libs)
- * [metadata: [scope] Metadata of this target.](#metadata)
- * [output_conversion: Data format for generated_file targets.](#output_conversion)
- * [output_dir: [directory] Directory to put output file in.](#output_dir)
- * [output_extension: [string] Value to use for the output's file extension.](#output_extension)
- * [output_name: [string] Name for the output file other than the default.](#output_name)
- * [output_prefix_override: [boolean] Don't use prefix for output name.](#output_prefix_override)
- * [outputs: [file list] Output files for actions and copy targets.](#outputs)
- * [partial_info_plist: [filename] Path plist from asset catalog compiler.](#partial_info_plist)
- * [pool: [string] Label of the pool used by the action.](#pool)
- * [precompiled_header: [string] Header file to precompile.](#precompiled_header)
- * [precompiled_header_type: [string] "gcc" or "msvc".](#precompiled_header_type)
- * [precompiled_source: [file name] Source file to precompile.](#precompiled_source)
- * [product_type: [string] Product type for Xcode projects.](#product_type)
- * [public: [file list] Declare public header files for a target.](#public)
- * [public_configs: [label list] Configs applied to dependents.](#public_configs)
- * [public_deps: [label list] Declare public dependencies.](#public_deps)
- * [rebase: [boolean] Rebase collected metadata as files.](#rebase)
- * [response_file_contents: [string list] Contents of .rsp file for actions.](#response_file_contents)
- * [script: [file name] Script file for actions.](#script)
- * [sources: [file list] Source files for a target.](#sources)
- * [testonly: [boolean] Declares a target must only be used for testing.](#testonly)
- * [visibility: [label list] A list of labels that can depend on a target.](#visibility)
- * [walk_keys: [string list] Key(s) for managing the metadata collection walk.](#walk_keys)
- * [write_runtime_deps: Writes the target's runtime_deps to the given path.](#write_runtime_deps)
- * [xcode_extra_attributes: [scope] Extra attributes for Xcode projects.](#xcode_extra_attributes)
- * [test_application_name: [string] Test application name for unit or ui test target.](#test_application_name)
+ * [all_dependent_configs: [label list] Configs to be forced on dependents.](#var_all_dependent_configs)
+ * [allow_circular_includes_from: [label list] Permit includes from deps.](#var_allow_circular_includes_from)
+ * [arflags: [string list] Arguments passed to static_library archiver.](#var_arflags)
+ * [args: [string list] Arguments passed to an action.](#var_args)
+ * [asmflags: [string list] Flags passed to the assembler.](#var_asmflags)
+ * [assert_no_deps: [label pattern list] Ensure no deps on these targets.](#var_assert_no_deps)
+ * [bundle_contents_dir: Expansion of {{bundle_contents_dir}} in create_bundle.](#var_bundle_contents_dir)
+ * [bundle_deps_filter: [label list] A list of labels that are filtered out.](#var_bundle_deps_filter)
+ * [bundle_executable_dir: Expansion of {{bundle_executable_dir}} in create_bundle](#var_bundle_executable_dir)
+ * [bundle_plugins_dir: Expansion of {{bundle_plugins_dir}} in create_bundle.](#var_bundle_plugins_dir)
+ * [bundle_resources_dir: Expansion of {{bundle_resources_dir}} in create_bundle.](#var_bundle_resources_dir)
+ * [bundle_root_dir: Expansion of {{bundle_root_dir}} in create_bundle.](#var_bundle_root_dir)
+ * [cflags: [string list] Flags passed to all C compiler variants.](#var_cflags)
+ * [cflags_c: [string list] Flags passed to the C compiler.](#var_cflags_c)
+ * [cflags_cc: [string list] Flags passed to the C++ compiler.](#var_cflags_cc)
+ * [cflags_objc: [string list] Flags passed to the Objective C compiler.](#var_cflags_objc)
+ * [cflags_objcc: [string list] Flags passed to the Objective C++ compiler.](#var_cflags_objcc)
+ * [check_includes: [boolean] Controls whether a target's files are checked.](#var_check_includes)
+ * [code_signing_args: [string list] Arguments passed to code signing script.](#var_code_signing_args)
+ * [code_signing_outputs: [file list] Output files for code signing step.](#var_code_signing_outputs)
+ * [code_signing_script: [file name] Script for code signing.](#var_code_signing_script)
+ * [code_signing_sources: [file list] Sources for code signing step.](#var_code_signing_sources)
+ * [complete_static_lib: [boolean] Links all deps into a static library.](#var_complete_static_lib)
+ * [configs: [label list] Configs applying to this target or config.](#var_configs)
+ * [contents: Contents to write to file.](#var_contents)
+ * [data: [file list] Runtime data file dependencies.](#var_data)
+ * [data_deps: [label list] Non-linked dependencies.](#var_data_deps)
+ * [data_keys: [string list] Keys from which to collect metadata.](#var_data_keys)
+ * [defines: [string list] C preprocessor defines.](#var_defines)
+ * [depfile: [string] File name for input dependencies for actions.](#var_depfile)
+ * [deps: [label list] Private linked dependencies.](#var_deps)
+ * [friend: [label pattern list] Allow targets to include private headers.](#var_friend)
+ * [include_dirs: [directory list] Additional include directories.](#var_include_dirs)
+ * [inputs: [file list] Additional compile-time dependencies.](#var_inputs)
+ * [ldflags: [string list] Flags passed to the linker.](#var_ldflags)
+ * [lib_dirs: [directory list] Additional library directories.](#var_lib_dirs)
+ * [libs: [string list] Additional libraries to link.](#var_libs)
+ * [metadata: [scope] Metadata of this target.](#var_metadata)
+ * [output_conversion: Data format for generated_file targets.](#var_output_conversion)
+ * [output_dir: [directory] Directory to put output file in.](#var_output_dir)
+ * [output_extension: [string] Value to use for the output's file extension.](#var_output_extension)
+ * [output_name: [string] Name for the output file other than the default.](#var_output_name)
+ * [output_prefix_override: [boolean] Don't use prefix for output name.](#var_output_prefix_override)
+ * [outputs: [file list] Output files for actions and copy targets.](#var_outputs)
+ * [partial_info_plist: [filename] Path plist from asset catalog compiler.](#var_partial_info_plist)
+ * [pool: [string] Label of the pool used by the action.](#var_pool)
+ * [precompiled_header: [string] Header file to precompile.](#var_precompiled_header)
+ * [precompiled_header_type: [string] "gcc" or "msvc".](#var_precompiled_header_type)
+ * [precompiled_source: [file name] Source file to precompile.](#var_precompiled_source)
+ * [product_type: [string] Product type for Xcode projects.](#var_product_type)
+ * [public: [file list] Declare public header files for a target.](#var_public)
+ * [public_configs: [label list] Configs applied to dependents.](#var_public_configs)
+ * [public_deps: [label list] Declare public dependencies.](#var_public_deps)
+ * [rebase: [boolean] Rebase collected metadata as files.](#var_rebase)
+ * [response_file_contents: [string list] Contents of .rsp file for actions.](#var_response_file_contents)
+ * [script: [file name] Script file for actions.](#var_script)
+ * [sources: [file list] Source files for a target.](#var_sources)
+ * [testonly: [boolean] Declares a target must only be used for testing.](#var_testonly)
+ * [visibility: [label list] A list of labels that can depend on a target.](#var_visibility)
+ * [walk_keys: [string list] Key(s) for managing the metadata collection walk.](#var_walk_keys)
+ * [write_runtime_deps: Writes the target's runtime_deps to the given path.](#var_write_runtime_deps)
+ * [xcode_extra_attributes: [scope] Extra attributes for Xcode projects.](#var_xcode_extra_attributes)
+ * [xcode_test_application_name: [string] Name for Xcode test target.](#var_xcode_test_application_name)
* [Other help topics](#other)
- * [all: Print all the help at once](#all)
+ * all: Print all the help at once
* [buildargs: How build arguments work.](#buildargs)
* [dotfile: Info about the toplevel .gn file.](#dotfile)
* [execution: Build graph and execution overview.](#execution)
@@ -154,11 +154,11 @@
* [output_conversion: Specifies how to transform a value to output.](#output_conversion)
* [runtime_deps: How runtime dependency computation works.](#runtime_deps)
* [source_expansion: Map sources to outputs for scripts.](#source_expansion)
- * [switches: Show available command-line switches.](#switches)
+ * [switches: Show available command-line switches.](#switch_list)
## <a name="commands"></a>Commands
-### <a name="analyze"></a>**gn analyze <out_dir> <input_path> <output_path>**
+### <a name="cmd_analyze"></a>**gn analyze <out_dir> <input_path> <output_path>**
```
Analyze which targets are affected by a list of files.
@@ -228,9 +228,13 @@
tries really hard to always write something to the output JSON and convey
errors that way rather than via return codes.
```
-### <a name="args"></a>**gn args <out_dir> [\--list] [\--short] [\--args] [\--overrides-only]**
+### <a name="cmd_args"></a>**gn args**: (command-line tool)
```
+ Display or configure arguments declared by the build.
+
+ gn args <out_dir> [--list] [--short] [--args] [--overrides-only]
+
See also "gn help buildargs" for a more high-level overview of how
build arguments work.
```
@@ -313,7 +317,7 @@
given arguments set (which may affect the values of other
arguments).
```
-### <a name="check"></a>**gn check <out_dir> [<label_pattern>] [\--force]**
+### <a name="cmd_check"></a>**gn check <out_dir> [<label_pattern>] [\--force]**
```
GN's include header checker validates that the includes for C-like source
@@ -428,13 +432,13 @@
gn check out/Default "//foo/*
Check only the files in targets in the //foo directory tree.
```
-### <a name="clean"></a>**gn clean <out_dir>**
+### <a name="cmd_clean"></a>**gn clean <out_dir>**
```
Deletes the contents of the output directory except for args.gn and
creates a Ninja build environment sufficient to regenerate the build.
```
-### <a name="desc"></a>**gn desc <out_dir> <label or pattern> [<what to show>] [\--blame] "**
+### <a name="cmd_desc"></a>**gn desc <out_dir> <label or pattern> [<what to show>] [\--blame] "**
#### **[\--format=json]**
```
@@ -598,7 +602,7 @@
Shows defines set for the //base:base target, annotated by where
each one was set from.
```
-### <a name="format"></a>**gn format [\--dump-tree] (\--stdin | <build_file>)**
+### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <build_file>)**
```
Formats .gn file to a standard format.
@@ -641,7 +645,7 @@
gn format /abspath/some/BUILD.gn
gn format --stdin
```
-### <a name="gen"></a>**gn gen [\--check] [<ide options>] <out_dir>**
+### <a name="cmd_gen"></a>**gn gen [\--check] [<ide options>] <out_dir>**
```
Generates ninja files from the current tree and puts them in the given output
@@ -771,7 +775,7 @@
used for various Clang-based tooling, allowing for the replay of individual
compilations independent of the build system.
```
-### <a name="help"></a>**gn help <anything>**
+### <a name="cmd_help"></a>**gn help <anything>**
```
Yo dawg, I heard you like help on your help so I put help on the help in the
@@ -793,7 +797,7 @@
gn help --markdown all
Dump all help to stdout in markdown format.
```
-### <a name="ls"></a>**gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]**
+### <a name="cmd_ls"></a>**gn ls <out_dir> [<label_pattern>] [\--all-toolchains] [\--as=...]**
```
[--type=...] [--testonly=...]
@@ -866,7 +870,7 @@
Lists all variants of the target //base:base (it may be referenced
in multiple toolchains).
```
-### <a name="meta"></a>**gn meta <out_dir> <target>* \--data=<key>[,<key>*]* [\--walk=<key>[,<key>*]*]**
+### <a name="cmd_meta"></a>**gn meta <out_dir> <target>* \--data=<key>[,<key>*]* [\--walk=<key>[,<key>*]*]**
```
[--rebase=<dest dir>]
@@ -921,7 +925,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="path"></a>**gn path <out_dir> <target_one> <target_two>**
+### <a name="cmd_path"></a>**gn path <out_dir> <target_one> <target_two>**
```
Finds paths of dependencies between two targets. Each unique path will be
@@ -966,7 +970,7 @@
```
gn path out/Default //base //tools/gn
```
-### <a name="refs"></a>**gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)***
+### <a name="cmd_refs"></a>**gn refs <out_dir> (<label_pattern>|<label>|<file>|@<response_file>)***
```
[--all] [--all-toolchains] [--as=...] [--testonly=...] [--type=...]
@@ -1091,7 +1095,7 @@
```
## <a name="targets"></a>Target declarations
-### <a name="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.
```
This target type allows you to run a script a single time to produce one or
@@ -1177,7 +1181,7 @@
rebase_path(sources, root_build_dir)
}
```
-### <a name="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.
```
This target type allows you to run a script once-per-file over a set of
@@ -1268,7 +1272,7 @@
"/{{source_name_part}}.h" ]
}
```
-### <a name="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.
```
This target type allows to declare data that is required at runtime. It is
@@ -1322,7 +1326,7 @@
]
}
```
-### <a name="copy"></a>**copy**: Declare a target that copies files.
+### <a name="func_copy"></a>**copy**: Declare a target that copies files.
#### **File name handling**
@@ -1359,7 +1363,7 @@
outputs = [ "$target_gen_dir/{{source_file_part}}" ]
}
```
-### <a name="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.
```
This target generates an iOS or macOS bundle (which is a directory with a
@@ -1512,7 +1516,7 @@
}
}
```
-### <a name="executable"></a>**executable**: Declare an executable target.
+### <a name="func_executable"></a>**executable**: Declare an executable target.
#### **Variables**
@@ -1526,7 +1530,7 @@
output_name, output_extension, public, sources, testonly,
visibility
```
-### <a name="generated_file"></a>**generated_file**: Declare a generated_file target.
+### <a name="func_generated_file"></a>**generated_file**: Declare a generated_file target.
```
Writes data value(s) to disk on resolution. This target type mirrors some
@@ -1658,7 +1662,7 @@
Deps: data_deps, deps, public_deps
Dependent configs: all_dependent_configs, public_configs
```
-### <a name="group"></a>**group**: Declare a named group of targets.
+### <a name="func_group"></a>**group**: Declare a named group of targets.
```
This target type allows you to create meta-targets that just collect a set of
@@ -1683,7 +1687,7 @@
]
}
```
-### <a name="loadable_module"></a>**loadable_module**: Declare a loadable module target.
+### <a name="func_loadable_module"></a>**loadable_module**: Declare a loadable module target.
```
This target type allows you to create an object file that is (and can only
@@ -1707,7 +1711,7 @@
output_name, output_extension, public, sources, testonly,
visibility
```
-### <a name="shared_library"></a>**shared_library**: Declare a shared library target.
+### <a name="func_shared_library"></a>**shared_library**: Declare a shared library target.
```
A shared library will be specified on the linker line for targets listing the
@@ -1729,7 +1733,7 @@
output_name, output_extension, public, sources, testonly,
visibility
```
-### <a name="source_set"></a>**source_set**: Declare a source set target.
+### <a name="func_source_set"></a>**source_set**: Declare a source set target.
```
A source set is a collection of sources that get compiled, but are not linked
@@ -1766,7 +1770,7 @@
output_name, output_extension, public, sources, testonly,
visibility
```
-### <a name="static_library"></a>**static_library**: Declare a static library target.
+### <a name="func_static_library"></a>**static_library**: Declare a static library target.
```
Make a ".a" / ".lib" file.
@@ -1789,7 +1793,7 @@
output_name, output_extension, public, sources, testonly,
visibility
```
-### <a name="target"></a>**target**: Declare an target with the given programmatic type.
+### <a name="func_target"></a>**target**: Declare an target with the given programmatic type.
```
target(target_type_string, target_name_string) { ... }
@@ -1823,7 +1827,7 @@
```
## <a name="functions"></a>Buildfile functions
-### <a name="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.
```
assert(<condition> [, <error string>])
@@ -1839,7 +1843,7 @@
assert(is_win)
assert(defined(sources), "Sources must be defined");
```
-### <a name="config"></a>**config**: Defines a configuration object.
+### <a name="func_config"></a>**config**: Defines a configuration object.
```
Configuration objects can be applied to targets and specify sets of compiler
@@ -1886,7 +1890,7 @@
configs = [ ":myconfig" ]
}
```
-### <a name="declare_args"></a>**declare_args**: Declare build arguments.
+### <a name="func_declare_args"></a>**declare_args**: Declare build arguments.
```
Introduces the given arguments into the current scope. If they are not
@@ -1946,7 +1950,7 @@
This also sets the teleporter, but it's already defaulted to on so it will
have no effect.
```
-### <a name="defined"></a>**defined**: Returns whether an identifier is defined.
+### <a name="func_defined"></a>**defined**: Returns whether an identifier is defined.
```
Returns true if the given argument is defined. This is most useful in
@@ -1980,7 +1984,7 @@
}
}
```
-### <a name="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.
```
exec_script(filename,
@@ -2040,7 +2044,7 @@
# result.
exec_script("//foo/bar/myscript.py")
```
-### <a name="foreach"></a>**foreach**: Iterate over a list.
+### <a name="func_foreach"></a>**foreach**: Iterate over a list.
```
foreach(<loop_var>, <list>) {
@@ -2074,7 +2078,7 @@
b
c
```
-### <a name="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.
```
forward_variables_from(from_scope, variable_list_or_star,
@@ -2156,7 +2160,7 @@
}
}
```
-### <a name="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.
```
get_label_info(target_label, what)
@@ -2220,7 +2224,7 @@
get_label_info("//foo/bar:baz", "target_gen_dir")
# Returns string "//out/Debug/gen/foo/bar".
```
-### <a name="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.
```
get_path_info(input, what)
@@ -2300,7 +2304,7 @@
# Extract the source-absolute directory name,
result = get_path_info(get_path_info(path, "dir"), "abspath"
```
-### <a name="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.
```
get_target_outputs(target_label)
@@ -2357,7 +2361,7 @@
sources = get_target_outputs(":my_action")
}
```
-### <a name="getenv"></a>**getenv**: Get an environment variable.
+### <a name="func_getenv"></a>**getenv**: Get an environment variable.
```
value = getenv(env_var_name)
@@ -2377,7 +2381,7 @@
```
home_dir = getenv("HOME")
```
-### <a name="import"></a>**import**: Import a file into the current scope.
+### <a name="func_import"></a>**import**: Import a file into the current scope.
```
The import command loads the rules and variables resulting from executing the
@@ -2412,7 +2416,7 @@
# Looks in the current directory.
import("my_vars.gni")
```
-### <a name="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.
```
not_needed(variable_list_or_star, variable_to_ignore_list = [])
@@ -2433,7 +2437,7 @@
not_needed(invoker, "*", [ "config" ])
not_needed(invoker, [ "data_deps", "deps" ])
```
-### <a name="pool"></a>**pool**: Defines a pool object.
+### <a name="func_pool"></a>**pool**: Defines a pool object.
```
Pool objects can be applied to a tool to limit the parallelism of the
@@ -2477,7 +2481,7 @@
}
}
```
-### <a name="print"></a>**print**: Prints to the console.
+### <a name="func_print"></a>**print**: Prints to the console.
```
Prints all arguments to the console separated by spaces. A newline is
@@ -2497,7 +2501,7 @@
print(sources, deps)
```
-### <a name="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.
```
process_file_template(source_list, template)
@@ -2542,7 +2546,7 @@
"//out/Debug/bar.cc"
"//out/Debug/bar.h" ]
```
-### <a name="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.
```
read_file(filename, input_conversion)
@@ -2566,7 +2570,7 @@
```
lines = read_file("foo.txt", "list lines")
```
-### <a name="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.
```
converted = rebase_path(input,
@@ -2662,7 +2666,7 @@
] + rebase_path(sources, root_build_dir)
}
```
-### <a name="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.
```
set_default_toolchain(toolchain_label)
@@ -2702,7 +2706,7 @@
set_default_toolchain("//toolchains:32")
}
```
-### <a name="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.
```
set_defaults(<target_type_name>) { <values...> }
@@ -2736,7 +2740,7 @@
configs -= [ "//tools/mything:settings" ]
}
```
-### <a name="set_sources_assignment_filter"></a>**set_sources_assignment_filter**: Set a pattern to filter source files.
+### <a name="func_set_sources_assignment_filter"></a>**set_sources_assignment_filter**: Set a pattern to filter source files.
```
The sources assignment filter is a list of patterns that remove files from
@@ -2800,7 +2804,7 @@
print(sources)
# Will print [ "a.cc" ]. b_win one was filtered out.
```
-### <a name="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.
```
result = split_list(input, n)
@@ -2823,7 +2827,7 @@
Will print:
[[1, 2], [3, 4], [5, 6]
```
-### <a name="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.
```
result = string_replace(str, old, new[, max])
@@ -2844,7 +2848,7 @@
Will print:
Hello, GN!
```
-### <a name="template"></a>**template**: Define a template rule.
+### <a name="func_template"></a>**template**: Define a template rule.
```
A template defines a custom name that acts like a function. It provides a way
@@ -3007,7 +3011,7 @@
deps = [ ":foo_idl_files" ]
}
```
-### <a name="tool"></a>**tool**: Specify arguments to a toolchain tool.
+### <a name="func_tool"></a>**tool**: Specify arguments to a toolchain tool.
#### **Usage**
@@ -3474,7 +3478,7 @@
}
};
```
-### <a name="toolchain"></a>**toolchain**: Defines a toolchain.
+### <a name="func_toolchain"></a>**toolchain**: Defines a toolchain.
```
A toolchain is a set of commands and build flags used to compile the source
@@ -3628,7 +3632,7 @@
}
}
```
-### <a name="write_file"></a>**write_file**: Write a file to disk.
+### <a name="func_write_file"></a>**write_file**: Write a file to disk.
```
write_file(filename, data, output_conversion = "")
@@ -3659,7 +3663,7 @@
```
## <a name="predefined_variables"></a>Built-in predefined variables
-### <a name="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.
```
The build configuration usually sets this value based on the value of
@@ -3673,7 +3677,7 @@
See "gn help target_cpu" for a list of common values returned.
```
-### <a name="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.
```
The build configuration usually sets this value based on the value of
@@ -3687,7 +3691,7 @@
See "gn help target_os" for a list of common values returned.
```
-### <a name="current_toolchain"></a>**current_toolchain**: Label of the current toolchain.
+### <a name="var_current_toolchain"></a>**current_toolchain**: Label of the current toolchain.
```
A fully-qualified label representing the current toolchain. You can use this
@@ -3702,13 +3706,13 @@
executable("output_thats_64_bit_only") {
...
```
-### <a name="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.
```
A fully-qualified label representing the default toolchain, which may not
necessarily be the current one (see "current_toolchain").
```
-### <a name="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.
```
This is value is exposed so that cross-compile toolchains can access the host
@@ -3726,7 +3730,7 @@
- "x64"
- "x86"
```
-### <a name="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.
```
This value is exposed so that cross-compiles can access the host build
@@ -3743,7 +3747,7 @@
- "mac"
- "win"
```
-### <a name="invoker"></a>**invoker**: [string] The invoking scope inside a template.
+### <a name="var_invoker"></a>**invoker**: [string] The invoking scope inside a template.
```
Inside a template invocation, this variable refers to the scope of the
@@ -3774,14 +3778,14 @@
bar = 123
}
```
-### <a name="python_path"></a>**python_path**: Absolute path of Python.
+### <a name="var_python_path"></a>**python_path**: Absolute path of Python.
```
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="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.
```
This is the root build output directory which will be the current directory
@@ -3790,7 +3794,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="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.
```
Absolute path to the root of the generated output directory tree for the
@@ -3805,7 +3809,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="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.
```
Absolute path to the root of the output directory tree for the current
@@ -3831,7 +3835,7 @@
args = [ "-o", rebase_path(root_out_dir, root_build_dir) ]
}
```
-### <a name="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.
```
This value should be used to indicate the desired architecture for the
@@ -3860,7 +3864,7 @@
- "arm64"
- "mipsel"
```
-### <a name="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.
```
Absolute path to the target's generated file directory. This will be the
@@ -3884,7 +3888,7 @@
args = [ "-o", rebase_path(target_gen_dir, root_build_dir) ]"
}
```
-### <a name="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.
```
Inside a target or template invocation, this variable refers to the name
@@ -3923,7 +3927,7 @@
my_template("space_ray") {
}
```
-### <a name="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.
```
This value should be used to indicate the desired operating system for the
@@ -3964,7 +3968,7 @@
- "mac"
- "win"
```
-### <a name="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.
```
Absolute path to the target's generated file directory. If your current
@@ -3989,7 +3993,7 @@
```
## <a name="target_variables"></a>Variables you set in targets
-### <a name="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.
```
A list of config labels.
@@ -4025,7 +4029,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="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.
```
A list of target labels. Must be a subset of the target's "deps". These
@@ -4098,7 +4102,7 @@
public_deps = [ ":c" ]
}
```
-### <a name="arflags"></a>**arflags**: Arguments passed to static_library archiver.
+### <a name="var_arflags"></a>**arflags**: Arguments passed to static_library archiver.
```
A list of flags passed to the archive/lib command that creates static
@@ -4131,7 +4135,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="args"></a>**args**: Arguments passed to an action.
+### <a name="var_args"></a>**args**: (target variable) Arguments passed to an action.
```
For action and action_foreach targets, args is the list of arguments to pass
@@ -4140,7 +4144,7 @@
See also "gn help action" and "gn help action_foreach".
```
-### <a name="asmflags"></a>**asmflags**: Flags passed to the assembler.
+### <a name="var_asmflags"></a>**asmflags**: Flags passed to the assembler.
```
A list of strings.
@@ -4166,7 +4170,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="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.
```
A list of label patterns.
@@ -4206,7 +4210,7 @@
]
}
```
-### <a name="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
```
create_bundle.
@@ -4218,7 +4222,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="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.
```
A list of target labels.
@@ -4249,7 +4253,7 @@
]
}
```
-### <a name="bundle_executable_dir"></a>**bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in
+### <a name="var_bundle_executable_dir"></a>**bundle_executable_dir**: Expansion of {{bundle_executable_dir}} in
```
create_bundle.
@@ -4261,7 +4265,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="bundle_plugins_dir"></a>**bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle.
+### <a name="var_bundle_plugins_dir"></a>**bundle_plugins_dir**: Expansion of {{bundle_plugins_dir}} in create_bundle.
```
A string corresponding to a path in $root_build_dir.
@@ -4272,7 +4276,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="bundle_resources_dir"></a>**bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in
+### <a name="var_bundle_resources_dir"></a>**bundle_resources_dir**: Expansion of {{bundle_resources_dir}} in
```
create_bundle.
@@ -4284,7 +4288,7 @@
See "gn help bundle_root_dir" for examples.
```
-### <a name="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.
```
A string corresponding to a path in root_build_dir.
@@ -4311,7 +4315,7 @@
bundle_plugins_dir = "${bundle_contents_dir}/PlugIns"
}
```
-### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags"></a>**cflags***: Flags passed to the C compiler.
```
A list of strings.
@@ -4344,7 +4348,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_c"></a>**cflags***: Flags passed to the C compiler.
```
A list of strings.
@@ -4377,7 +4381,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_cc"></a>**cflags***: Flags passed to the C compiler.
```
A list of strings.
@@ -4410,7 +4414,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_objc"></a>**cflags***: Flags passed to the C compiler.
```
A list of strings.
@@ -4443,7 +4447,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="cflags*"></a>**cflags***: Flags passed to the C compiler.
+### <a name="var_cflags_objcc"></a>**cflags***: Flags passed to the C compiler.
```
A list of strings.
@@ -4476,7 +4480,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="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.
```
When true (the default), the "gn check" command (as well as "gn gen" with the
@@ -4504,7 +4508,7 @@
...
}
```
-### <a name="code_signing_args"></a>**code_signing_args**: [string list] Arguments passed to code signing script.
+### <a name="var_code_signing_args"></a>**code_signing_args**: [string list] Arguments passed to code signing script.
```
For create_bundle targets, code_signing_args is the list of arguments to pass
@@ -4513,7 +4517,7 @@
See also "gn help create_bundle".
```
-### <a name="code_signing_outputs"></a>**code_signing_outputs**: [file list] Output files for code signing step.
+### <a name="var_code_signing_outputs"></a>**code_signing_outputs**: [file list] Output files for code signing step.
```
Outputs from the code signing step of a create_bundle target. Must refer to
@@ -4521,7 +4525,7 @@
See also "gn help create_bundle".
```
-### <a name="code_signing_script"></a>**code_signing_script**: [file name] Script for code signing."
+### <a name="var_code_signing_script"></a>**code_signing_script**: [file name] Script for code signing."
```
An absolute or buildfile-relative file name of a Python script to run for a
@@ -4529,7 +4533,7 @@
See also "gn help create_bundle".
```
-### <a name="code_signing_sources"></a>**code_signing_sources**: [file list] Sources for code signing step.
+### <a name="var_code_signing_sources"></a>**code_signing_sources**: [file list] Sources for code signing step.
```
A list of files used as input for code signing script step of a create_bundle
@@ -4538,7 +4542,7 @@
See also "gn help create_bundle".
```
-### <a name="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.
```
A static library normally doesn't include code from dependencies, but instead
@@ -4573,7 +4577,7 @@
deps = [ "bar" ]
}
```
-### <a name="configs"></a>**configs**: Configs applying to this target or config.
+### <a name="var_configs"></a>**configs**: Configs applying to this target or config.
```
A list of config labels.
@@ -4666,13 +4670,13 @@
}
}
```
-### <a name="contents"></a>**contents**: Contents to write to file.
+### <a name="var_contents"></a>**contents**: Contents to write to file.
```
The contents of the file for a generated_file target.
See "gn help generated_file".
```
-### <a name="data"></a>**data**: Runtime data file dependencies.
+### <a name="var_data"></a>**data**: Runtime data file dependencies.
```
Lists files or directories required to run the given target. These are
@@ -4701,7 +4705,7 @@
See "gn help runtime_deps" for how these are used.
```
-### <a name="data_deps"></a>**data_deps**: Non-linked dependencies.
+### <a name="var_data_deps"></a>**data_deps**: Non-linked dependencies.
```
A list of target labels.
@@ -4727,7 +4731,7 @@
data_deps = [ "//plugins:my_runtime_plugin" ]
}
```
-### <a name="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.
```
These keys are used to identify metadata to collect. If a walked target
@@ -4736,7 +4740,7 @@
See "gn help generated_file".
```
-### <a name="defines"></a>**defines**: C preprocessor defines.
+### <a name="var_defines"></a>**defines**: C preprocessor defines.
```
A list of strings
@@ -4768,7 +4772,7 @@
```
defines = [ "AWESOME_FEATURE", "LOG_LEVEL=3" ]
```
-### <a name="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.
```
If nonempty, this string specifies that the current action or action_foreach
@@ -4807,7 +4811,7 @@
args = [ "{{source}}", "-o", depfile ]
}
```
-### <a name="deps"></a>**deps**: Private linked dependencies.
+### <a name="var_deps"></a>**deps**: Private linked dependencies.
```
A list of target labels.
@@ -4840,7 +4844,7 @@
See also "public_deps".
```
-### <a name="friend"></a>**friend**: Allow targets to include private headers.
+### <a name="var_friend"></a>**friend**: Allow targets to include private headers.
```
A list of label patterns (see "gn help label_pattern") that allow dependent
@@ -4901,7 +4905,7 @@
]
}
```
-### <a name="include_dirs"></a>**include_dirs**: Additional include directories.
+### <a name="var_include_dirs"></a>**include_dirs**: Additional include directories.
```
A list of source directories.
@@ -4933,7 +4937,7 @@
```
include_dirs = [ "src/include", "//third_party/foo" ]
```
-### <a name="inputs"></a>**inputs**: Additional compile-time dependencies.
+### <a name="var_inputs"></a>**inputs**: Additional compile-time dependencies.
```
Inputs are compile-time dependencies of the current target. This means that
@@ -5003,7 +5007,7 @@
inputs = [ "input.data" ]
}
```
-### <a name="ldflags"></a>**ldflags**: Flags passed to the linker.
+### <a name="var_ldflags"></a>**ldflags**: Flags passed to the linker.
```
A list of strings.
@@ -5035,7 +5039,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="lib_dirs"></a>**lib_dirs**: Additional library directories.
+### <a name="var_lib_dirs"></a>**lib_dirs**: Additional library directories.
```
A list of directories.
@@ -5078,7 +5082,7 @@
```
lib_dirs = [ "/usr/lib/foo", "lib/doom_melon" ]
```
-### <a name="libs"></a>**libs**: Additional libraries to link.
+### <a name="var_libs"></a>**libs**: Additional libraries to link.
```
A list of library names or library paths.
@@ -5151,7 +5155,7 @@
On Linux:
libs = [ "ld" ]
```
-### <a name="metadata"></a>**metadata**: Metadata of this target.
+### <a name="var_metadata"></a>**metadata**: Metadata of this target.
```
Metadata is a collection of keys and values relating to a particular target.
@@ -5173,13 +5177,13 @@
}
}
```
-### <a name=""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.
```
Controls how the "contents" of a generated_file target is formatted.
See "gn help output_conversion".
```
-### <a name="output_dir"></a>**output_dir**: [directory] Directory to put output file in.
+### <a name="var_output_dir"></a>**output_dir**: [directory] Directory to put output file in.
```
For library and executable targets, overrides the directory for the final
@@ -5206,7 +5210,7 @@
...
}
```
-### <a name="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.
```
Normally the file extension for a target is based on the target type and the
@@ -5242,7 +5246,7 @@
}
}
```
-### <a name="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.
```
Normally the output name of a target will be based on the target name, so the
@@ -5268,7 +5272,7 @@
output_name = "fluffy_bunny"
}
```
-### <a name="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.
```
A boolean that overrides the output prefix for a target. Defaults to false.
@@ -5292,7 +5296,7 @@
...
}
```
-### <a name="outputs"></a>**outputs**: Output files for actions and copy targets.
+### <a name="var_outputs"></a>**outputs**: Output files for actions and copy targets.
```
Outputs is valid for "copy", "action", and "action_foreach" target types and
@@ -5315,7 +5319,7 @@
Action targets (excluding action_foreach) must list literal output file(s)
with no source expansions. See "gn help action".
```
-### <a name="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.
```
Valid for create_bundle target, corresponds to the path for the partial
@@ -5325,7 +5329,7 @@
The file will be generated regardless of whether the asset compiler has
been invoked or not. See "gn help create_bundle".
```
-### <a name="pool"></a>**pool**: Label of the pool used by the action.
+### <a name="var_pool"></a>**pool**: Label of the pool used by the action.
```
A fully-qualified label representing the pool that will be used for the
@@ -5340,7 +5344,7 @@
...
}
```
-### <a name="precompiled_header"></a>**precompiled_header**: [string] Header file to precompile.
+### <a name="var_precompiled_header"></a>**precompiled_header**: [string] Header file to precompile.
```
Precompiled headers will be used when a target specifies this value, or a
@@ -5408,19 +5412,19 @@
configs += [ ":use_precompiled_headers" ]
...
```
-### <a name="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".
```
See "gn help precompiled_header".
```
-### <a name="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.
```
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="product_type"></a>**product_type**: Product type for Xcode projects.
+### <a name="var_product_type"></a>**product_type**: Product type for Xcode projects.
```
Correspond to the type of the product of a create_bundle target. Only
@@ -5429,7 +5433,7 @@
When generating Xcode project files, only create_bundle target with a
non-empty product_type will have a corresponding target in Xcode project.
```
-### <a name="public"></a>**public**: Declare public header files for a target.
+### <a name="var_public"></a>**public**: Declare public header files for a target.
```
A list of files that other targets can include. These permissions are checked
@@ -5482,7 +5486,7 @@
# This allows starting compilation in dependent targets earlier.
public = []
```
-### <a name="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.
```
A list of config labels.
@@ -5573,7 +5577,7 @@
"deps" list. If a dependency is public, they will be applied
recursively.
```
-### <a name="public_deps"></a>**public_deps**: Declare public dependencies.
+### <a name="var_public_deps"></a>**public_deps**: Declare public dependencies.
```
Public dependencies are like private dependencies (see "gn help deps") but
@@ -5624,7 +5628,7 @@
public_deps = [ ":c" ]
}
```
-### <a name="rebase"></a>**rebase**: Rebase collected metadata as files.
+### <a name="var_rebase"></a>**rebase**: Rebase collected metadata as files.
```
A boolean that triggers a rebase of collected metadata strings based on their
@@ -5640,7 +5644,7 @@
See also "gn help generated_file".
```
-### <a name="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.
```
Sometimes the arguments passed to a script can be too long for the system's
@@ -5678,14 +5682,14 @@
]
}
```
-### <a name="script"></a>**script**: Script file for actions.
+### <a name="var_script"></a>**script**: Script file for actions.
```
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="sources"></a>**sources**: Source files for a target
+### <a name="var_sources"></a>**sources**: Source files for a target
```
A list of files. Non-absolute paths will be resolved relative to the current
@@ -5723,7 +5727,7 @@
copy
The source are the source files to copy.
```
-### <a name="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.
```
Boolean. Defaults to false.
@@ -5744,7 +5748,7 @@
...
}
```
-### <a name="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.
```
A list of labels and label patterns that define which targets can depend on
@@ -5799,7 +5803,7 @@
any targets in "//bar/" and any subdirectory thereof.
visibility = [ "./*", "//bar/*" ]
```
-### <a name="walk_keys"></a>**walk_keys**: Key(s) for managing the metadata collection walk.
+### <a name="var_walk_keys"></a>**walk_keys**: Key(s) for managing the metadata collection walk.
```
Defaults to [].
@@ -5813,7 +5817,7 @@
See "gn help generated_file".
```
-### <a name="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.
```
Does not synchronously write the file, but rather schedules it to be written
@@ -5833,7 +5837,7 @@
same as requesting the runtime deps be written on the command line (see "gn
help --runtime-deps-list-file").
```
-### <a name="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.
```
The value defined in this scope will be copied to the EXTRA_ATTRIBUTES
@@ -5842,7 +5846,7 @@
See "gn help create_bundle" for more information.
```
-### <a name="test_application_name"></a>**test_application_name**: Test application name for unit or ui test target.
+### <a name="var_xcode_test_application_name"></a>**xcode_test_application_name**: Name for Xcode test target.
```
Each unit and ui test target must have a test application target, and this
@@ -6345,11 +6349,13 @@
within the second, and vice versa. Note that this means inherited scopes are
always unequal by definition.
```
-### <a name="input_conversion"></a>**Input and output conversions are arguments to file and process functions**
-#### **that specify how to convert data to or from external formats. The possible**
-#### **values for parameters specifying conversions are**:
+### <a name="input_conversion"></a>**Input and output conversion**
```
+ Input and output conversions are arguments to file and process functions
+ that specify how to convert data to or from external formats. The possible
+ values for parameters specifying conversions are:
+
"" (the default)
input: Discard the result and return None.
@@ -6358,21 +6364,21 @@
"list lines"
input:
Return the file contents as a list, with a string for each line. The
- newlines will not be present in the result. The last line may or may not
- end in a newline.
+ newlines will not be present in the result. The last line may or may
+ not end in a newline.
After splitting, each individual line will be trimmed of whitespace on
both ends.
output:
Renders the value contents as a list, with a string for each line. The
- newlines will not be present in the result. The last line will end in with
- a newline.
+ newlines will not be present in the result. The last line will end in
+ with a newline.
"scope"
input:
- Execute the block as GN code and return a scope with the resulting values
- in it. If the input was:
+ Execute the block as GN code and return a scope with the resulting
+ values in it. If the input was:
a = [ "hello.cc", "world.cc" ]
b = 26
and you read the result into a variable named "val", then you could
@@ -6417,8 +6423,8 @@
will produce an error if assigned to a variable.
output:
- Render the value contents as a literal rvalue. Strings render with escaped
- quotes.
+ Render the value contents as a literal rvalue. Strings render with
+ escaped quotes.
"json"
input: Parse the input as a JSON and convert it to equivalent GN rvalue.
@@ -6629,11 +6635,13 @@
advice on fixing problems. Targets can also opt-out of checking, see
"gn help check_includes".
```
-### <a name="output_conversion"></a>**Input and output conversions are arguments to file and process functions**
-#### **that specify how to convert data to or from external formats. The possible**
-#### **values for parameters specifying conversions are**:
+### <a name="output_conversion"></a>**Input and output conversion**
```
+ Input and output conversions are arguments to file and process functions
+ that specify how to convert data to or from external formats. The possible
+ values for parameters specifying conversions are:
+
"" (the default)
input: Discard the result and return None.
@@ -6642,21 +6650,21 @@
"list lines"
input:
Return the file contents as a list, with a string for each line. The
- newlines will not be present in the result. The last line may or may not
- end in a newline.
+ newlines will not be present in the result. The last line may or may
+ not end in a newline.
After splitting, each individual line will be trimmed of whitespace on
both ends.
output:
Renders the value contents as a list, with a string for each line. The
- newlines will not be present in the result. The last line will end in with
- a newline.
+ newlines will not be present in the result. The last line will end in
+ with a newline.
"scope"
input:
- Execute the block as GN code and return a scope with the resulting values
- in it. If the input was:
+ Execute the block as GN code and return a scope with the resulting
+ values in it. If the input was:
a = [ "hello.cc", "world.cc" ]
b = 26
and you read the result into a variable named "val", then you could
@@ -6701,8 +6709,8 @@
will produce an error if assigned to a variable.
output:
- Render the value contents as a literal rvalue. Strings render with escaped
- quotes.
+ Render the value contents as a literal rvalue. Strings render with
+ escaped quotes.
"json"
input: Parse the input as a JSON and convert it to equivalent GN rvalue.
@@ -6921,28 +6929,28 @@
//out/Debug/obj/mydirectory/input2.h
//out/Debug/obj/mydirectory/input2.cc
```
-## <a name="switches"></a>Command Line Switches
-
-**Available global switches
-** Do "gn help --the_switch_you_want_help_on" for more. Individual
- commands may take command-specific switches not listed here. See the
- help on your specific command for more.
+### <a name="switch_list"></a>**Available global switches**
```
- * [--args: Specifies build arguments overrides.](#--args)
- * [--color: Force colored output.](#--color)
- * [--dotfile: Override the name of the ".gn" file.](#--dotfile)
- * [--fail-on-unused-args: Treat unused build args as fatal errors.](#--fail-on-unused-args)
- * [--markdown: Write help output in the Markdown format.](#--markdown)
- * [--nocolor: Force non-colored output.](#--nocolor)
- * [-q: Quiet mode. Don't print output on success.](#-q)
- * [--root: Explicitly specify source root.](#--root)
- * [--runtime-deps-list-file: Save runtime dependencies for targets in file.](#--runtime-deps-list-file)
- * [--script-executable: Set the executable used to execute scripts.](#--script-executable)
- * [--threads: Specify number of worker threads.](#--threads)
- * [--time: Outputs a summary of how long everything took.](#--time)
- * [--tracelog: Writes a Chrome-compatible trace log to the given file.](#--tracelog)
- * [-v: Verbose logging.](#-v)
- * [--version: Prints the GN version number and exits.](#--version)
+ Do "gn help --the_switch_you_want_help_on" for more. Individual commands may
+ take command-specific switches not listed here. See the help on your specific
+ command for more.
+```
+```
+ * --args: Specifies build arguments overrides.
+ * --color: Force colored output.
+ * --dotfile: Override the name of the ".gn" file.
+ * --fail-on-unused-args: Treat unused build args as fatal errors.
+ * --markdown: Write help output in the Markdown format.
+ * --nocolor: Force non-colored output.
+ * -q: Quiet mode. Don't print output on success.
+ * --root: Explicitly specify source root.
+ * --runtime-deps-list-file: Save runtime dependencies for targets in file.
+ * --script-executable: Set the executable used to execute scripts.
+ * --threads: Specify number of worker threads.
+ * --time: Outputs a summary of how long everything took.
+ * --tracelog: Writes a Chrome-compatible trace log to the given file.
+ * -v: Verbose logging.
+ * --version: Prints the GN version number and exits.
```
diff --git a/tools/gn/command_args.cc b/tools/gn/command_args.cc
index fac8683..9957508 100644
--- a/tools/gn/command_args.cc
+++ b/tools/gn/command_args.cc
@@ -409,7 +409,11 @@
const char kArgs_HelpShort[] =
"args: Display or configure arguments declared by the build.";
const char kArgs_Help[] =
- R"(gn args <out_dir> [--list] [--short] [--args] [--overrides-only]
+ R"(gn args: (command-line tool)
+
+ Display or configure arguments declared by the build.
+
+ gn args <out_dir> [--list] [--short] [--args] [--overrides-only]
See also "gn help buildargs" for a more high-level overview of how
build arguments work.
diff --git a/tools/gn/command_help.cc b/tools/gn/command_help.cc
index 6e816ce..b7662a4 100644
--- a/tools/gn/command_help.cc
+++ b/tools/gn/command_help.cc
@@ -29,65 +29,86 @@
namespace {
+// Some names exist in multiple sections, these prefixes are used for the
+// internal links to disambiguate when writing markdown.
+const char kCommandLinkPrefix[] = "cmd_";
+const char kFunctionLinkPrefix[] = "func_";
+const char kVariableLinkPrefix[] = "var_";
+
void PrintToplevelHelp() {
PrintSectionHelp("Commands", "<command>", "commands");
for (const auto& cmd : commands::GetCommands())
- PrintShortHelp(cmd.second.help_short);
+ PrintShortHelp(cmd.second.help_short, kCommandLinkPrefix + cmd.first);
// Target declarations.
PrintSectionHelp("Target declarations", "<function>", "targets");
for (const auto& func : functions::GetFunctions()) {
if (func.second.is_target)
- PrintShortHelp(func.second.help_short);
+ PrintShortHelp(func.second.help_short, kFunctionLinkPrefix + func.first);
}
// Functions.
PrintSectionHelp("Buildfile functions", "<function>", "functions");
for (const auto& func : functions::GetFunctions()) {
if (!func.second.is_target)
- PrintShortHelp(func.second.help_short);
+ PrintShortHelp(func.second.help_short, kFunctionLinkPrefix + func.first);
}
// Built-in variables.
PrintSectionHelp("Built-in predefined variables", "<variable>",
"predefined_variables");
- for (const auto& builtin : variables::GetBuiltinVariables())
- PrintShortHelp(builtin.second.help_short);
+ for (const auto& builtin : variables::GetBuiltinVariables()) {
+ PrintShortHelp(builtin.second.help_short,
+ kVariableLinkPrefix + builtin.first);
+ }
// Target variables.
PrintSectionHelp("Variables you set in targets", "<variable>",
"target_variables");
- for (const auto& target : variables::GetTargetVariables())
- PrintShortHelp(target.second.help_short);
+ for (const auto& target : variables::GetTargetVariables()) {
+ PrintShortHelp(target.second.help_short,
+ kVariableLinkPrefix + target.first);
+ }
PrintSectionHelp("Other help topics", "", "other");
PrintShortHelp("all: Print all the help at once");
- PrintShortHelp("buildargs: How build arguments work.");
- PrintShortHelp("dotfile: Info about the toplevel .gn file.");
- PrintShortHelp("execution: Build graph and execution overview.");
- PrintShortHelp("grammar: Language and grammar for GN build files.");
+ PrintShortHelp("buildargs: How build arguments work.", "buildargs");
+ PrintShortHelp("dotfile: Info about the toplevel .gn file.", "dotfile");
+ PrintShortHelp("execution: Build graph and execution overview.", "execution");
+ PrintShortHelp("grammar: Language and grammar for GN build files.",
+ "grammar");
PrintShortHelp(
- "input_conversion: Processing input from exec_script and read_file.");
- PrintShortHelp("label_pattern: Matching more than one label.");
- PrintShortHelp("labels: About labels.");
- PrintShortHelp("ninja_rules: How Ninja build rules are named.");
- PrintShortHelp("nogncheck: Annotating includes for checking.");
+ "input_conversion: Processing input from exec_script and read_file.",
+ "input_conversion");
+ PrintShortHelp("label_pattern: Matching more than one label.",
+ "label_pattern");
+ PrintShortHelp("labels: About labels.", "labels");
+ PrintShortHelp("ninja_rules: How Ninja build rules are named.",
+ "ninja_rules");
+ PrintShortHelp("nogncheck: Annotating includes for checking.", "nogncheck");
PrintShortHelp(
- "output_conversion: Specifies how to transform a value to output.");
- PrintShortHelp("runtime_deps: How runtime dependency computation works.");
- PrintShortHelp("source_expansion: Map sources to outputs for scripts.");
- PrintShortHelp("switches: Show available command-line switches.");
+ "output_conversion: Specifies how to transform a value to output.",
+ "output_conversion");
+ PrintShortHelp("runtime_deps: How runtime dependency computation works.",
+ "runtime_deps");
+ PrintShortHelp("source_expansion: Map sources to outputs for scripts.",
+ "source_expansion");
+ PrintShortHelp("switches: Show available command-line switches.", "switch_list");
}
void PrintSwitchHelp() {
const base::CommandLine* cmdline = base::CommandLine::ForCurrentProcess();
bool is_markdown = cmdline->HasSwitch(switches::kMarkdown);
- OutputString("Available global switches\n", DECORATION_YELLOW);
- OutputString(
- " Do \"gn help --the_switch_you_want_help_on\" for more. Individual\n"
- " commands may take command-specific switches not listed here. See the\n"
- " help on your specific command for more.\n\n");
+ // This uses "switch_list" for the tag because Markdown seems to generate
+ // implicit tags for headings that match the strings, and some headings are
+ // labeled "switches".
+ PrintLongHelp(R"(Available global switches
+
+ Do "gn help --the_switch_you_want_help_on" for more. Individual commands may
+ take command-specific switches not listed here. See the help on your specific
+ command for more.
+)", "switch_list");
if (is_markdown)
OutputString("```\n", DECORATION_NONE);
@@ -125,7 +146,7 @@
NO_ESCAPING);
}
for (const auto& c : commands::GetCommands())
- PrintLongHelp(c.second.help);
+ PrintLongHelp(c.second.help, kCommandLinkPrefix + c.first);
if (is_markdown) {
OutputString("## <a name=\"targets\"></a>Target declarations\n\n",
@@ -133,7 +154,7 @@
}
for (const auto& f : functions::GetFunctions()) {
if (f.second.is_target)
- PrintLongHelp(f.second.help);
+ PrintLongHelp(f.second.help, kFunctionLinkPrefix + f.first);
}
if (is_markdown) {
@@ -142,7 +163,7 @@
}
for (const auto& f : functions::GetFunctions()) {
if (!f.second.is_target)
- PrintLongHelp(f.second.help);
+ PrintLongHelp(f.second.help, kFunctionLinkPrefix + f.first);
}
if (is_markdown) {
@@ -152,7 +173,7 @@
DECORATION_NONE, NO_ESCAPING);
}
for (const auto& v : variables::GetBuiltinVariables())
- PrintLongHelp(v.second.help);
+ PrintLongHelp(v.second.help, kVariableLinkPrefix + v.first);
if (is_markdown) {
OutputString(
@@ -161,7 +182,7 @@
DECORATION_NONE, NO_ESCAPING);
}
for (const auto& v : variables::GetTargetVariables())
- PrintLongHelp(v.second.help);
+ PrintLongHelp(v.second.help, kVariableLinkPrefix + v.first);
if (is_markdown) {
OutputString("## <a name=\"other\"></a>Other help topics\n\n",
@@ -180,10 +201,6 @@
PrintLongHelp(kRuntimeDeps_Help, "runtime_deps");
PrintLongHelp(kSourceExpansion_Help, "source_expansion");
- if (is_markdown) {
- OutputString("## <a name=\"switches\"></a>Command Line Switches\n\n",
- DECORATION_NONE, NO_ESCAPING);
- }
PrintSwitchHelp();
}
@@ -200,6 +217,18 @@
return true;
}
+// Special-case help for ambiguous "args" case.
+void PrintArgsHelp() {
+ PrintLongHelp(
+ "The string \"args\" is both a command and a variable for action "
+ "targets.\nShowing help for both...\n\n");
+ PrintLongHelp(commands::kArgs_Help);
+ PrintLongHelp(
+ "\n----------------------------------------------------------------------"
+ "---------\n\n");
+ PrintLongHelp(variables::kArgs_Help);
+}
+
} // namespace
const char kHelp[] = "help";
@@ -248,6 +277,12 @@
std::vector<base::StringPiece> all_help_topics;
+ // Special-case ambiguous topics.
+ if (what == "args") {
+ PrintArgsHelp();
+ return 0;
+ }
+
// Check commands.
const commands::CommandInfoMap& command_map = commands::GetCommands();
auto found_command = command_map.find(what);
diff --git a/tools/gn/input_conversion.cc b/tools/gn/input_conversion.cc
index df58d9d..270d437 100644
--- a/tools/gn/input_conversion.cc
+++ b/tools/gn/input_conversion.cc
@@ -241,9 +241,11 @@
} // namespace
const char kInputOutputConversion_Help[] =
- R"(Input and output conversions are arguments to file and process functions
-that specify how to convert data to or from external formats. The possible
-values for parameters specifying conversions are:
+ R"(Input and output conversion
+
+ Input and output conversions are arguments to file and process functions
+ that specify how to convert data to or from external formats. The possible
+ values for parameters specifying conversions are:
"" (the default)
input: Discard the result and return None.
@@ -253,21 +255,21 @@
"list lines"
input:
Return the file contents as a list, with a string for each line. The
- newlines will not be present in the result. The last line may or may not
- end in a newline.
+ newlines will not be present in the result. The last line may or may
+ not end in a newline.
After splitting, each individual line will be trimmed of whitespace on
both ends.
output:
Renders the value contents as a list, with a string for each line. The
- newlines will not be present in the result. The last line will end in with
- a newline.
+ newlines will not be present in the result. The last line will end in
+ with a newline.
"scope"
input:
- Execute the block as GN code and return a scope with the resulting values
- in it. If the input was:
+ Execute the block as GN code and return a scope with the resulting
+ values in it. If the input was:
a = [ "hello.cc", "world.cc" ]
b = 26
and you read the result into a variable named "val", then you could
@@ -312,8 +314,8 @@
will produce an error if assigned to a variable.
output:
- Render the value contents as a literal rvalue. Strings render with escaped
- quotes.
+ Render the value contents as a literal rvalue. Strings render with
+ escaped quotes.
"json"
input: Parse the input as a JSON and convert it to equivalent GN rvalue.
diff --git a/tools/gn/standard_out.cc b/tools/gn/standard_out.cc
index d2ff52e..f74b9ab 100644
--- a/tools/gn/standard_out.cc
+++ b/tools/gn/standard_out.cc
@@ -78,8 +78,8 @@
#endif // !defined(OS_WIN)
void OutputMarkdownDec(TextDecoration dec) {
- // The markdown rendering turns "dim" text to italics and any
- // other colored text to bold.
+// The markdown rendering turns "dim" text to italics and any
+// other colored text to bold.
#if defined(OS_WIN)
DWORD written = 0;
@@ -226,26 +226,24 @@
}
}
-void PrintShortHelp(const std::string& line) {
+void PrintShortHelp(const std::string& line, const std::string& link_tag) {
EnsureInitialized();
+ if (is_markdown) {
+ if (link_tag.empty())
+ OutputString(" * " + line + "\n");
+ else
+ OutputString(" * [" + line + "](#" + link_tag + ")\n");
+ return;
+ }
+
size_t colon_offset = line.find(':');
size_t first_normal = 0;
if (colon_offset != std::string::npos) {
- if (is_markdown) {
- OutputString(" * [" + line + "](#" + line.substr(0, colon_offset) +
- ")\n");
- } else {
- OutputString(" " + line.substr(0, colon_offset), DECORATION_YELLOW);
- first_normal = colon_offset;
- }
- } else if (is_markdown) {
- OutputString(" * [" + line + "](" + line + ")\n");
+ OutputString(" " + line.substr(0, colon_offset), DECORATION_YELLOW);
+ first_normal = colon_offset;
}
- if (is_markdown)
- return;
-
// See if the colon is followed by a " [" and if so, dim the contents of [ ].
if (first_normal > 0 && line.size() > first_normal + 2 &&
line[first_normal + 1] == ' ' && line[first_normal + 2] == '[') {
@@ -289,16 +287,8 @@
in_body = false;
}
- if (first_header) {
- std::string the_tag = tag;
- if (the_tag.size() == 0) {
- if (line.substr(0, 2) == "gn") {
- the_tag = line.substr(3, line.substr(3).find(' '));
- } else {
- the_tag = line.substr(0, line.find(':'));
- }
- }
- OutputString("### <a name=\"" + the_tag + "\"></a>", DECORATION_NONE,
+ if (first_header && !tag.empty()) {
+ OutputString("### <a name=\"" + tag + "\"></a>", DECORATION_NONE,
NO_ESCAPING);
first_header = false;
} else {
diff --git a/tools/gn/standard_out.h b/tools/gn/standard_out.h
index c793b29..5c0fcce 100644
--- a/tools/gn/standard_out.h
+++ b/tools/gn/standard_out.h
@@ -38,13 +38,24 @@
// the colon is the command (and is highlighted). After the colon if there is
// a square bracket, the contents of the bracket is dimmed.
//
+// The link_tag is set, it will be used for markdown output links. This is
+// used when generating the markdown for all help topics. If empty, no link tag
+// will be emitted. In non-markdown mode, this parameter will be ignored.
+//
// The line is indented 2 spaces.
-void PrintShortHelp(const std::string& line);
+void PrintShortHelp(const std::string& line,
+ const std::string& link_tag = std::string());
+// Prints a longer help section.
+//
// Rules:
// - Lines beginning with non-whitespace are highlighted up to the first
// colon (or the whole line if not).
// - Lines whose first non-whitespace character is a # are dimmed.
+//
+// The tag will be used as a link target for the first header. This is used
+// when generating the markdown for all help topics. If empty, no link tag will
+// be emitted. Used only in markdown mode.
void PrintLongHelp(const std::string& text, const std::string& tag = "");
#endif // TOOLS_GN_STANDARD_OUT_H_
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc
index 7723636..7d607e4 100644
--- a/tools/gn/variables.cc
+++ b/tools/gn/variables.cc
@@ -516,7 +516,7 @@
const char kArgs_HelpShort[] =
"args: [string list] Arguments passed to an action.";
const char kArgs_Help[] =
- R"(args: Arguments passed to an action.
+ R"(args: (target variable) Arguments passed to an action.
For action and action_foreach targets, args is the list of arguments to pass
to the script. Typically you would use source expansion (see "gn help
@@ -1945,10 +1945,9 @@
const char kXcodeTestApplicationName[] = "xcode_test_application_name";
const char kXcodeTestApplicationName_HelpShort[] =
- "test_application_name: [string] Test application name for unit or ui test "
- "target.";
+ "xcode_test_application_name: [string] Name for Xcode test target.";
const char kXcodeTestApplicationName_Help[] =
- R"(test_application_name: Test application name for unit or ui test target.
+ R"(xcode_test_application_name: Name for Xcode test target.
Each unit and ui test target must have a test application target, and this
value is used to specify the relationship. Only meaningful to Xcode (used as
