diff options
Diffstat (limited to 'libbuild2/b.cli')
| -rw-r--r-- | libbuild2/b.cli | 228 |
1 files changed, 220 insertions, 8 deletions
diff --git a/libbuild2/b.cli b/libbuild2/b.cli index ec2c8e7..b1f8a5f 100644 --- a/libbuild2/b.cli +++ b/libbuild2/b.cli @@ -2,7 +2,6 @@ // license : MIT; see accompanying LICENSE file include <set>; -include <libbuild2/types.hxx>; include <libbuild2/common.cli>; @@ -320,12 +319,103 @@ namespace build2 Print basic information (name, version, source and output directories, etc) about one or more projects to \cb{stdout}, separating multiple projects with a blank line. Each project is - identified by its root directory target. For example: + identified by its root directory target. For example (some output + is omitted): \ $ b info: libfoo/ libbar/ + project: libfoo + version: 1.0.0 + src_root: /tmp/libfoo + out_root: /tmp/libfoo + + project: libbar + version: 2.0.0 + src_root: /tmp/libbar + out_root: /tmp/libbar-out \ + To instead print this information in the JSON format, use the + \cb{json} parameter, for example: + + \ + $ b info: libfoo/,json + \ + + In this case the output is a JSON array of objects which are the + serialized representation of the following C++ \cb{struct} + \cb{project_info}: + + \ + struct subproject + { + string path; + optional<string> name; + }; + + struct project_info + { + optional<string> project; + optional<string> version; + optional<string> summary; + optional<string> url; + string src_root; + string out_root; + optional<string> amalgamation; + vector<subproject> subprojects; + vector<string> operations; + vector<string> meta_operations; + vector<string> modules; + }; + \ + + For example: + + \ + [ + { + \"project\": \"libfoo\", + \"version\": \"1.0.0\", + \"summary\": \"libfoo C++ library\", + \"src_root\": \"/tmp/libfoo\", + \"out_root\": \"/tmp/gcc-debug/libfoo\", + \"amalgamation\": \"..\", + \"subprojects\": [ + { + \"path\": \"tests\" + } + ], + \"operations\": [ + \"update\", + \"clean\", + \"test\", + \"update-for-test\", + \"install\", + \"uninstall\", + \"update-for-install\" + ], + \"meta-operations\": [ + \"perform\", + \"configure\", + \"disfigure\", + \"dist\", + \"info\" + ], + \"modules\": [ + \"version\", + \"config\", + \"test\", + \"install\", + \"dist\" + ] + } + ] + \ + + See the JSON OUTPUT section below for details on the overall + properties of this format and the semantics of the \cb{struct} + serialization. + || The build system has the following built-in and pre-defined operations: @@ -554,13 +644,20 @@ namespace build2 project's \cb{buildfiles}, such as \cb{info}." } - bool --structured-result + structured_result_format --structured-result { + "<fmt>", + "Write the result of execution in a structured form. In this mode, instead of printing to \cb{stderr} diagnostics messages about the outcome of executing actions on targets, the driver writes to - \cb{stdout} a structured result description one line per the - buildspec action/target pair. Each line has the following format: + \cb{stdout} a machine-readable result description in the specified + format. Valid values for this option are \cb{lines} and \cb{json}. + Note that currently only the \cb{perform} meta-operation supports + the structured result output. + + If the output format is \cb{lines}, then the result is written one line + per the buildspec action/target pair. Each line has the following form: \c{\i{state} \i{meta-operation} \i{operation} \i{target}} @@ -570,11 +667,63 @@ namespace build2 \ unchanged perform update(test) /tmp/dir{hello/} - changed perform test /tmp/dir{hello/} + changed perform test /tmp/hello/exe{test} \ - Note that only the \cb{perform} meta-operation supports the structured - result output. + If the output format is \cb{json}, then the output is a JSON array of + objects which are the serialized representation of the following C++ + \cb{struct} \cb{target_action_result}: + + \ + struct target_action_result + { + string target; + string quoted_target; + string target_type; + optional<string> target_path; + string meta_operation; + string operation; + optional<string> outer_operation; + string state; + }; + \ + + For example: + + \ + [ + { + \"target\": \"/tmp/dir{hello/}\", + \"quoted_target\": \"/tmp/dir{hello/}\", + \"target_type\": \"dir\", + \"target_path\": \"/tmp/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\", + \"meta_operation\": \"perform\", + \"operation\": \"test\", + \"state\": \"changed\" + } + ] + \ + + See the JSON OUTPUT section below for details on the overall + 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}. " } @@ -725,6 +874,69 @@ 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| + + Commands that support the JSON output specify their formats as a + serialized representation of a C++ \cb{struct} or an array thereof. For + example: + + \ + struct package + { + string name; + }; + + struct configuration + { + uint64_t id; + string path; + optional<string> name; + bool default; + vector<package> packages; + }; + \ + + An example of the serialized JSON representation of \cb{struct} + \cb{configuration}: + + \ + { + \"id\": 1, + \"path\": \"/tmp/hello-gcc\", + \"name\": \"gcc\", + \"default\": true, + \"packages\": [ + { + \"name\": \"hello\" + } + ] + } + \ + + This sections provides details on the overall properties of such formats + and the semantics of the \cb{struct} serialization. + + The order of members in a JSON object is fixed as specified in the + corresponding \cb{struct}. While new members may be added in the + future (and should be ignored by older consumers), the semantics of the + existing members (including whether the top-level entry is an object or + array) may not change. + + An object member is required unless its type is \cb{optional<>}, + \cb{bool}, or \cb{vector<>} (array). For \cb{bool} members absent means + \cb{false}. For \cb{vector<>} members absent means empty. An empty + top-level array is always present. + + For example, the following JSON text is a possible serialization of + the above \cb{struct} \cb{configuration}: + + \ + { + \"id\": 1, + \"path\": \"/tmp/hello-gcc\" + } + \ + \h|EXIT STATUS| Non-zero exit status is returned in case of an error. |