[help] Fixing help issues. Change-Id: I605f014edeb63e0ece079a4d399ab205c0c6ac8f Reviewed-on: https://gn-review.googlesource.com/c/3800 Commit-Queue: Julie Hockett <juliehockett@google.com> Reviewed-by: Brett Wilson <brettw@chromium.org>
diff --git a/docs/reference.md b/docs/reference.md index 11e8212..0156b4a 100644 --- a/docs/reference.md +++ b/docs/reference.md
@@ -10,7 +10,7 @@ * [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) + * [format: Format .gn files.](#cmd_format) * [gen: Generate ninja files.](#cmd_gen) * [help: Does what you think.](#cmd_help) * [ls: List matching targets.](#cmd_ls) @@ -602,7 +602,7 @@ Shows defines set for the //base:base target, annotated by where each one was set from. ``` -### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <build_file>)** +### <a name="cmd_format"></a>**gn format [\--dump-tree] (\--stdin | <list of build_files...>)** ``` Formats .gn file to a standard format. @@ -629,9 +629,9 @@ - Exit code 1: general failure (parse error, etc.) - Exit code 2: successful format, but differs from on disk. - --dump-tree - For debugging, dumps the parse tree to stdout and does not update the - file or print formatted output. + --dump-tree[=( text | json )] + Dumps the parse tree to stdout and does not update the file or print + formatted output. If no format is specified, text format will be used. --stdin Read input from stdin and write to stdout rather than update a file @@ -640,7 +640,7 @@ #### **Examples** ``` - gn format //some/BUILD.gn + gn format //some/BUILD.gn //some/other/BUILD.gn //and/another/BUILD.gn gn format some\\BUILD.gn gn format /abspath/some/BUILD.gn gn format --stdin @@ -1573,7 +1573,7 @@ deps = [ ":b" ] } - group("c") { + group("b") { metadata = { my_files = [ "bar.cpp" ] my_barrier = [ ":c" ] @@ -1655,6 +1655,7 @@ #### **Variables** ``` + contents data_keys rebase walk_keys @@ -5159,15 +5160,18 @@ ``` Metadata is a collection of keys and values relating to a particular target. - Generally, these keys will include three categories of strings: ordinary - strings, filenames intended to be rebased according to their particular - source directory, and target labels intended to be used as barriers to the - walk. Verfication of these categories occurs at walk time, not creation - time (since it is not clear until the walk which values are intended for - which purpose). + Values must be lists, allowing for sane and predictable collection behavior. + Generally, these keys will include three types of lists: lists of ordinary + strings, lists of filenames intended to be rebased according to their + particular source directory, and lists of target labels intended to be used + as barriers to the walk. Verfication of these categories occurs at walk time, + not creation time (since it is not clear until the walk which values are + intended for which purpose). +``` - Example +#### **Example** +``` group("doom_melon") { metadata = { # These keys are not built in to GN but are interpreted when consuming @@ -6349,7 +6353,7 @@ 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 conversion** +### <a name="io_conversion"></a>**Input and output conversion** ``` Input and output conversions are arguments to file and process functions @@ -6635,110 +6639,6 @@ advice on fixing problems. Targets can also opt-out of checking, see "gn help check_includes". ``` -### <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. - - output: If value is a list, then "list lines"; otherwise "value". - - "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. - - 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. - - "scope" - input: - 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 - access contents the "." operator on "val": - sources = val.a - some_count = val.b - - output: - Renders the value contents as a GN code block, reversing the input - result above. - - "string" - input: Return the file contents into a single string. - - output: - Render the value contents into a single string. The output is: - a string renders with quotes, e.g. "str" - an integer renders as a stringified integer, e.g. "6" - a boolean renders as the associated string, e.g. "true" - a list renders as a representation of its contents, e.g. "[\"str\", 6]" - a scope renders as a GN code block of its values. If the Value was: - Value val; - val.a = [ "hello.cc", "world.cc" ]; - val.b = 26 - the resulting output would be: - "{ - a = [ \"hello.cc\", \"world.cc\" ] - b = 26 - }" - - "value" - input: - Parse the input as if it was a literal rvalue in a buildfile. Examples of - typical program output using this mode: - [ "foo", "bar" ] (result will be a list) - or - "foo bar" (result will be a string) - or - 5 (result will be an integer) - - Note that if the input is empty, the result will be a null value which - will produce an error if assigned to a variable. - - output: - 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. - - output: Convert the Value to equivalent JSON value. - - The data type mapping is: - a string in JSON maps to string in GN - an integer in JSON maps to integer in GN - a float in JSON is unsupported and will result in an error - an object in JSON maps to scope in GN - an array in JSON maps to list in GN - a boolean in JSON maps to boolean in GN - a null in JSON is unsupported and will result in an error - - Nota that the input dictionary keys have to be valid GN identifiers - otherwise they will produce an error. - - "trim ..." (input only) - Prefixing any of the other transformations with the word "trim" will - result in whitespace being trimmed from the beginning and end of the - result before processing. - - Examples: "trim string" or "trim list lines" - - Note that "trim value" is useless because the value parser skips - whitespace anyway. -``` ### <a name="runtime_deps"></a>**Runtime dependencies** ```
diff --git a/tools/gn/command_help.cc b/tools/gn/command_help.cc index b7662a4..543f5d1 100644 --- a/tools/gn/command_help.cc +++ b/tools/gn/command_help.cc
@@ -192,12 +192,11 @@ PrintLongHelp(kDotfile_Help, "dotfile"); PrintLongHelp(kExecution_Help, "execution"); PrintLongHelp(kGrammar_Help, "grammar"); - PrintLongHelp(kInputOutputConversion_Help, "input_conversion"); + PrintLongHelp(kInputOutputConversion_Help, "io_conversion"); PrintLongHelp(kLabelPattern_Help, "label_pattern"); PrintLongHelp(kLabels_Help, "labels"); PrintLongHelp(kNinjaRules_Help, "ninja_rules"); PrintLongHelp(kNoGnCheck_Help, "nogncheck"); - PrintLongHelp(kInputOutputConversion_Help, "output_conversion"); PrintLongHelp(kRuntimeDeps_Help, "runtime_deps"); PrintLongHelp(kSourceExpansion_Help, "source_expansion"); @@ -331,16 +330,13 @@ random_topics["buildargs"] = []() { PrintLongHelp(kBuildArgs_Help); }; random_topics["dotfile"] = []() { PrintLongHelp(kDotfile_Help); }; random_topics["grammar"] = []() { PrintLongHelp(kGrammar_Help); }; - random_topics["input_conversion"] = []() { + random_topics["io_conversion"] = []() { PrintLongHelp(kInputOutputConversion_Help); }; random_topics["label_pattern"] = []() { PrintLongHelp(kLabelPattern_Help); }; random_topics["labels"] = []() { PrintLongHelp(kLabels_Help); }; random_topics["ninja_rules"] = []() { PrintLongHelp(kNinjaRules_Help); }; random_topics["nogncheck"] = []() { PrintLongHelp(kNoGnCheck_Help); }; - random_topics["output_conversion"] = []() { - PrintLongHelp(kInputOutputConversion_Help); - }; random_topics["runtime_deps"] = []() { PrintLongHelp(kRuntimeDeps_Help); }; random_topics["source_expansion"] = []() { PrintLongHelp(kSourceExpansion_Help);
diff --git a/tools/gn/functions_target.cc b/tools/gn/functions_target.cc index 6cbab00..24fc248 100644 --- a/tools/gn/functions_target.cc +++ b/tools/gn/functions_target.cc
@@ -816,7 +816,7 @@ deps = [ ":b" ] } - group("c") { + group("b") { metadata = { my_files = [ "bar.cpp" ] my_barrier = [ ":c" ] @@ -897,6 +897,7 @@ Variables + contents data_keys rebase walk_keys
diff --git a/tools/gn/variables.cc b/tools/gn/variables.cc index 7d607e4..25f18a5 100644 --- a/tools/gn/variables.cc +++ b/tools/gn/variables.cc
@@ -1356,14 +1356,15 @@ R"(metadata: Metadata of this target. Metadata is a collection of keys and values relating to a particular target. - Generally, these keys will include three categories of strings: ordinary - strings, filenames intended to be rebased according to their particular - source directory, and target labels intended to be used as barriers to the - walk. Verfication of these categories occurs at walk time, not creation - time (since it is not clear until the walk which values are intended for - which purpose). + Values must be lists, allowing for sane and predictable collection behavior. + Generally, these keys will include three types of lists: lists of ordinary + strings, lists of filenames intended to be rebased according to their + particular source directory, and lists of target labels intended to be used + as barriers to the walk. Verfication of these categories occurs at walk time, + not creation time (since it is not clear until the walk which values are + intended for which purpose). - Example +Example group("doom_melon") { metadata = {