diff options
Diffstat (limited to 'libbuild2/b.cli')
| -rw-r--r-- | libbuild2/b.cli | 175 |
1 files changed, 142 insertions, 33 deletions
diff --git a/libbuild2/b.cli b/libbuild2/b.cli index 3ae6e0b..f58b869 100644 --- a/libbuild2/b.cli +++ b/libbuild2/b.cli @@ -1,8 +1,6 @@ // file : libbuild2/b.cli // license : MIT; see accompanying LICENSE file -include <set>; - include <libbuild2/common.cli>; "\section=1" @@ -328,11 +326,20 @@ namespace build2 version: 1.0.0 src_root: /tmp/libfoo out_root: /tmp/libfoo + subprojects: @tests project: libbar version: 2.0.0 src_root: /tmp/libbar out_root: /tmp/libbar-out + subprojects: @tests + \ + + To omit discovering and printing subprojects information, use the + \cb{no_subprojects} parameter, for example: + + \ + $ b info: libfoo/,no_subprojects \ To instead print this information in the JSON format, use the @@ -471,7 +478,7 @@ namespace build2 \ $ b config.install.root=c:\projects\install - $ b \"config.install.root='c:\Program Files (x86)\test\'\" + $ b \"config.install.root='c:\Program Files\test\'\" $ b 'config.cxx.poptions=-DFOO_STR=\"foo\"' \ " @@ -537,15 +544,6 @@ namespace build2 "Display build statistics." } - std::set<string> --dump - { - "<phase>", - "Dump the build system state after the specified phase. Valid <phase> - values are \cb{load} (after loading \cb{buildfiles}) and \cb{match} - (after matching rules to targets). Repeat this option to dump the - state after multiple phases." - } - bool --progress { "Display build progress. If printing to a terminal the progress is @@ -558,6 +556,22 @@ namespace build2 "Don't display build progress." } + bool --diag-color + { + "Use color in diagnostics. If printing to a terminal the color is used + by default provided the terminal is not dumb. Use \cb{--no-diag-color} + to suppress. + + This option affects the diagnostics printed by the build system itself. + Some rules may also choose to propagate its value to tools (such as + compilers) that they invoke." + } + + bool --no-diag-color + { + "Don't use color in diagnostics." + } + size_t --jobs|-j { "<num>", @@ -617,7 +631,10 @@ namespace build2 investigate build failures that are caused by build system errors rather than compilation errors. Note that if you don't want to keep going but still want parallel execution, add \cb{--jobs|-j} (for - example \cb{-j\ 0} for default concurrency)." + example \cb{-j\ 0} for default concurrency). Note also that during + serial execution there is no diagnostics buffering and child + process' \cb{stderr} is a terminal (unless redirected; see + \cb{--no-diag-buffer} for details)." } bool --dry-run|-n @@ -631,10 +648,33 @@ namespace build2 this mode." } + bool --no-diag-buffer + { + "Do not buffer diagnostics from child processes. By default, unless + running serially, such diagnostics is buffered and printed all at + once after each child exits in order to prevent interleaving. + However, this can have side-effects since the child process' + \cb{stderr} is no longer a terminal. Most notably, the use of + color in diagnostics may be disabled by some programs. On the + other hand, depending on the platform and programs invoked, the + interleaving diagnostics may not break lines and thus could be + tolerable." + } + bool --match-only { - "Match the rules but do not execute the operation. This mode is primarily - useful for profiling." + "Match the rules without executing the operation. This mode is primarily + useful for profiling and dumping the build system state." + } + + bool --load-only + { + "Match the rules only to \cb{alias{\}} targets ignoring other targets + and without executing the operation. In particular, this has the + effect of loading all the subdirectory \cb{buildfiles} that are not + explicitly included. Note that this option can only be used with the + \cb{perform(update)} action on an \cb{alias{\}} target, usually + \cb{dir{\}}." } bool --no-external-modules @@ -666,8 +706,8 @@ namespace build2 outer operation is specified in parenthesis. For example: \ - unchanged perform update(test) /tmp/dir{hello/} - changed perform test /tmp/hello/exe{test} + unchanged perform update(test) /tmp/hello/hello/exe{hello} + changed perform test /tmp/hello/hello/exe{hello} \ If the output format is \cb{json}, then the output is a JSON array of @@ -678,7 +718,7 @@ namespace build2 struct target_action_result { string target; - string quoted_target; + string display_target; string target_type; optional<string> target_path; string meta_operation; @@ -693,20 +733,20 @@ namespace build2 \ [ { - \"target\": \"/tmp/dir{hello/}\", - \"quoted_target\": \"/tmp/dir{hello/}\", - \"target_type\": \"dir\", - \"target_path\": \"/tmp/hello\", + \"target\": \"/tmp/hello/hello/exe{hello.}\", + \"display_target\": \"/tmp/hello/hello/exe{hello}\", + \"target_type\": \"exe\", + \"target_path\": \"/tmp/hello/hello/hello\", \"meta_operation\": \"perform\", \"operation\": \"update\", \"outer_operation\": \"test\", \"state\": \"unchanged\" }, { - \"target\": \"/tmp/dir{hello/}\", - \"quoted_target\": \"/tmp/dir{hello/}\", - \"target_type\": \"dir\", - \"target_path\": \"/tmp/hello\", + \"target\": \"/tmp/hello/hello/exe{hello.}\", + \"display_target\": \"/tmp/hello/hello/exe{hello}\", + \"target_type\": \"exe\", + \"target_path\": \"/tmp/hello/hello/hello\", \"meta_operation\": \"perform\", \"operation\": \"test\", \"state\": \"changed\" @@ -718,12 +758,14 @@ namespace build2 properties of this format and the semantics of the \cb{struct} serialization. - The \cb{target} member is a \"display\" target name, the same as in the - \cb{lines} format. The \cb{quoted_target} member is a target name that, - if required, is quoted so that it can be passed back to the driver on - the command line. The \cb{target_type} member is the type of target. - The \cb{target_path} member is an absolute path to the target if the - target type is path-based or \cb{dir}. + The \cb{target} member is the target name that is qualified with the + extension (if applicable) and, if required, is quoted so that it can be + passed back to the build system driver on the command line. The + \cb{display_target} member is the unqualified and unquoted \"display\" + target name, the same as in the \cb{lines} format. The \cb{target_type} + member is the type of target. The \cb{target_path} member is an + absolute path to the target if the target type is path-based or + \cb{dir}. " } @@ -742,6 +784,73 @@ namespace build2 \cb{--mtime-check} for details." } + strings --dump + { + "<phase>", + "Dump the build system state after the specified phase. Valid <phase> + values are \cb{load} (after loading \cb{buildfiles}) and \cb{match} + (after matching rules to targets). The \cb{match} value also has the + \cb{match-pre} and \cb{match-post} variants to dump the state for the + pre/post-operations (\cb{match} dumps the main operation only). Repeat + this option to dump the state after multiple phases/variants. By + default the entire build state is dumped but this behavior can be + altered with the \cb{--dump-scope} and \cb{--dump-target} options. + See also the \cb{--match-only} and \cb{--load-only} options." + } + + string --dump-format + { + // NOTE: fix all references to json-v0.1, including the manual. + // + "<format>", + "Representation format and output stream to use when dumping the build + system state. Valid values for this option are \cb{buildfile} (a + human-readable, Buildfile-like format written to \cb{stderr}; this is + the default), and \cb{json-v0.1} (machine-readable, JSON-based format + written to \cb{stdout}). For details on the \cb{buildfile} format, see + \l{b#intro-diag-debug Diagnostics and Debugging}. For details on the + \cb{json-v0.1} format, see the JSON OUTPUT section below (overall + properties) and \l{b#json-dump JSON Dump Format} (format specifics). + Note that the JSON format is currently unstable (thus the temporary + \cb{-v0.1} suffix). + + Note that because it's possible to end up with multiple dumps (for + example, by specifying the \cb{--dump-scope} and/or \cb{--dump-target} + options multiple times), the JSON output is in the \"JSON Lines\" form, + that is, without pretty-printing and with the top-level JSON objects + delimited by newlines. Note also that if the JSON dump output is + combined with \cb{--structured-result=json}, then the structured + result is the last line." + } + + dir_paths --dump-scope + { + "<dir>", + "Dump the build system state for the specified scope only. Repeat this + option to dump the state of multiple scopes." + } + + vector<pair<name, optional<name>>> --dump-target + { + "<target>", + "Dump the build system state for the specified target only. Repeat this + option to dump the state of multiple targets." + } + + vector<name> --trace-match + { + "<target>", + "Trace rule matching for the specified target. This is primarily useful + during troubleshooting. Repeat this option to trace multiple targets." + } + + vector<name> --trace-execute + { + "<target>", + "Trace rule execution for the specified target. This is primarily useful + during troubleshooting. Repeat this option to trace multiple targets." + } + bool --no-column { "Don't print column numbers in diagnostics." @@ -874,7 +983,7 @@ namespace build2 The order in which default options files are loaded is traced at the verbosity level 3 (\cb{-V} option) or higher. - \h|JSON OUTPUT| + \h#json-output|JSON OUTPUT| Commands that support the JSON output specify their formats as a serialized representation of a C++ \cb{struct} or an array thereof. For |