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