From 8c257da85cde2df8f459f0c7610445971fffb2a8 Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Tue, 8 Mar 2022 21:12:57 +0300 Subject: Add JSON format support for --structured-result option and info meta operation --- build2/b.cxx | 207 +++++++++++--- libbuild2/b-options.cxx | 443 ++++++++++++++++++----------- libbuild2/b-options.hxx | 10 +- libbuild2/b-options.ixx | 8 +- libbuild2/b.cli | 228 ++++++++++++++- libbuild2/build/script/builtin-options.hxx | 2 - libbuild2/build/script/builtin.cli | 2 - libbuild2/buildfile | 2 +- libbuild2/common-options.hxx | 4 + libbuild2/common.cli | 3 + libbuild2/operation.cxx | 217 +++++++++++++- libbuild2/options-types.hxx | 16 ++ libbuild2/scope.cxx | 2 +- libbuild2/scope.hxx | 6 +- libbuild2/script/builtin-options.hxx | 2 - libbuild2/script/builtin.cli | 2 - libbuild2/target-state.hxx | 10 +- libbuild2/target.cxx | 6 +- libbuild2/types-parsers.cxx | 20 +- libbuild2/types-parsers.hxx | 16 +- 20 files changed, 964 insertions(+), 242 deletions(-) create mode 100644 libbuild2/options-types.hxx diff --git a/build2/b.cxx b/build2/b.cxx index e636a9d..556cf36 100644 --- a/build2/b.cxx +++ b/build2/b.cxx @@ -10,6 +10,10 @@ #include // stderr_fd(), fdterm() #include // backtrace() +#ifndef BUILD2_BOOTSTRAP +# include +#endif + #include #include @@ -62,73 +66,170 @@ namespace build2 int main (int argc, char* argv[]); +#ifndef BUILD2_BOOTSTRAP // Structured result printer (--structured-result mode). // class result_printer { public: - result_printer (const options& ops, const action_targets& tgs) - : ops_ (ops), tgs_ (tgs) {} + result_printer (const options& ops, + const action_targets& tgs, + json::stream_serializer& js) + : ops_ (ops), tgs_ (tgs), json_serializer_ (js) {} ~result_printer (); private: + void + print_lines (); + + void + print_json (); + + private: const options ops_; const action_targets& tgs_; + json::stream_serializer& json_serializer_; }; + void result_printer:: + print_lines () + { + for (const action_target& at: tgs_) + { + if (at.state == target_state::unknown) + continue; // Not a target/no result. + + const target& t (at.as ()); + context& ctx (t.ctx); + + cout << at.state + << ' ' << ctx.current_mif->name + << ' ' << ctx.current_inner_oif->name; + + if (ctx.current_outer_oif != nullptr) + cout << '(' << ctx.current_outer_oif->name << ')'; + + // There are two ways one may wish to identify the target of the + // operation: as something specific but inherently non-portable (say, a + // filesystem path, for example c:\tmp\foo.exe) or as something regular + // that can be used to refer to a target in a portable way (for example, + // c:\tmp\exe{foo}; note that the directory part is still not portable). + // Which one should we use is a good question. Let's go with the + // portable one for now and see how it goes (we can always add a format + // variant, e.g., --structured-result=lines-path). Note also that the + // json format includes both. + + // Set the stream extension verbosity to 0 to suppress extension + // printing by default (this can still be overriden by the target type's + // print function as is the case for file{}, for example). And set the + // path verbosity to 1 to always print absolute. + // + stream_verbosity sv (stream_verb (cout)); + stream_verb (cout, stream_verbosity (1, 0)); + + cout << ' ' << t << endl; + + stream_verb (cout, sv); + } + } + + void result_printer:: + print_json () + { + json::stream_serializer& s (json_serializer_); + + for (const action_target& at: tgs_) + { + if (at.state == target_state::unknown) + continue; // Not a target/no result. + + const target& t (at.as ()); + context& ctx (t.ctx); + + s.begin_object (); + + // Target. + // + { + // Change the stream verbosity (see print_lines() for details). + // + ostringstream os; + stream_verb (os, stream_verbosity (1, 0)); + os << t; + s.member ("target", os.str ()); + } + + // Quoted target. + // + { + names ns (t.as_name ()); // Note: potentially adds an extension. + + ostringstream os; + stream_verb (os, stream_verbosity (1, 0)); + to_stream (os, ns, quote_mode::effective, '@'); + s.member ("quoted_target", os.str ()); + } + + s.member ("target_type", t.key ().type->name, false /* check */); + + if (t.is_a ()) + s.member ("target_path", t.key ().dir->string ()); + else if (const auto* pt = t.is_a ()) + s.member ("target_path", pt->path ().string ()); + + s.member ("meta_operation", ctx.current_mif->name, false /* check */); + s.member ("operation", ctx.current_inner_oif->name, false /* check */); + + if (ctx.current_outer_oif != nullptr) + s.member ("outer_operation", + ctx.current_outer_oif->name, + false /* check */); + + s.member ("state", to_string (at.state), false /* check */); + + s.end_object (); + } + } + result_printer:: ~result_printer () { // Let's do some sanity checking even when we are not in the structred // output mode. // +#ifndef NDEBUG for (const action_target& at: tgs_) { switch (at.state) { - case target_state::unknown: continue; // Not a target/no result. + case target_state::unknown: case target_state::unchanged: case target_state::changed: case target_state::failed: break; // Valid states. default: assert (false); } + } +#endif - if (ops_.structured_result ()) + if (ops_.structured_result_specified ()) + { + switch (ops_.structured_result ()) { - const target& t (at.as ()); - context& ctx (t.ctx); - - cout << at.state - << ' ' << ctx.current_mif->name - << ' ' << ctx.current_inner_oif->name; - - if (ctx.current_outer_oif != nullptr) - cout << '(' << ctx.current_outer_oif->name << ')'; - - // There are two ways one may wish to identify the target of the - // operation: as something specific but inherently non-portable (say, - // a filesystem path, for example c:\tmp\foo.exe) or as something - // regular that can be used to refer to a target in a portable way - // (for example, c:\tmp\exe{foo}; note that the directory part is - // still not portable). Which one should we use is a good question. - // Let's go with the portable one for now and see how it goes (we - // can always add a format version, e.g., --structured-result=2). - - // Set the stream extension verbosity to 0 to suppress extension - // printing by default (this can still be overriden by the target - // type's print function as is the case for file{}, for example). - // And set the path verbosity to 1 to always print absolute. - // - stream_verbosity sv (stream_verb (cout)); - stream_verb (cout, stream_verbosity (1, 0)); - - cout << ' ' << t << endl; - - stream_verb (cout, sv); + case structured_result_format::lines: + { + print_lines (); + break; + } + case structured_result_format::json: + { + print_json (); + break; + } } } } +#endif } // Print backtrace if terminating due to an unhandled exception. Note that @@ -371,6 +472,17 @@ main (int argc, char* argv[]) // bool dirty (false); // Already (re)set for the first run. +#ifndef BUILD2_BOOTSTRAP + // Note that this constructor is cheap and so we rather call it always + // instead of resorting to dynamic allocations. + // + json::stream_serializer js (cout); + + if (ops.structured_result_specified () && + ops.structured_result () == structured_result_format::json) + js.begin_array (); +#endif + for (auto mit (bspec.begin ()); mit != bspec.end (); ) { vector_view opspecs; @@ -1168,8 +1280,10 @@ main (int argc, char* argv[]) action a (mid, pre_oid, oid); { - result_printer p (ops, tgs); - uint16_t diag (ops.structured_result () ? 0 : 1); +#ifndef BUILD2_BOOTSTRAP + result_printer p (ops, tgs, js); +#endif + uint16_t diag (ops.structured_result_specified () ? 0 : 1); if (mif->match != nullptr) mif->match (mparams, a, tgs, diag, true /* progress */); @@ -1195,8 +1309,10 @@ main (int argc, char* argv[]) action a (mid, oid, oif->outer_id); { - result_printer p (ops, tgs); - uint16_t diag (ops.structured_result () ? 0 : 2); +#ifndef BUILD2_BOOTSTRAP + result_printer p (ops, tgs, js); +#endif + uint16_t diag (ops.structured_result_specified () ? 0 : 2); if (mif->match != nullptr) mif->match (mparams, a, tgs, diag, true /* progress */); @@ -1223,8 +1339,10 @@ main (int argc, char* argv[]) action a (mid, post_oid, oid); { - result_printer p (ops, tgs); - uint16_t diag (ops.structured_result () ? 0 : 1); +#ifndef BUILD2_BOOTSTRAP + result_printer p (ops, tgs, js); +#endif + uint16_t diag (ops.structured_result_specified () ? 0 : 1); if (mif->match != nullptr) mif->match (mparams, a, tgs, diag, true /* progress */); @@ -1262,6 +1380,15 @@ main (int argc, char* argv[]) if (lifted == nullptr && skip == 0) ++mit; } // meta-operation + +#ifndef BUILD2_BOOTSTRAP + if (ops.structured_result_specified () && + ops.structured_result () == structured_result_format::json) + { + js.end_array (); + cout << endl; + } +#endif } catch (const failed&) { diff --git a/libbuild2/b-options.cxx b/libbuild2/b-options.cxx index ae832ef..b3a330c 100644 --- a/libbuild2/b-options.cxx +++ b/libbuild2/b-options.cxx @@ -266,6 +266,7 @@ namespace build2 match_only_ (), no_external_modules_ (), structured_result_ (), + structured_result_specified_ (false), mtime_check_ (), no_mtime_check_ (), no_column_ (), @@ -480,10 +481,11 @@ namespace build2 this->no_external_modules_, a.no_external_modules_); } - if (a.structured_result_) + if (a.structured_result_specified_) { - ::build2::build::cli::parser< bool>::merge ( + ::build2::build::cli::parser< structured_result_format>::merge ( this->structured_result_, a.structured_result_); + this->structured_result_specified_ = true; } if (a.mtime_check_) @@ -589,237 +591,296 @@ namespace build2 os << "\033[1mOPTIONS\033[0m" << ::std::endl; os << std::endl - << "\033[1m-v\033[0m Print actual commands being executed. This options is" << ::std::endl - << " equivalent to \033[1m--verbose 2\033[0m." << ::std::endl; + << "\033[1m-v\033[0m Print actual commands being executed. This options is" << ::std::endl + << " equivalent to \033[1m--verbose 2\033[0m." << ::std::endl; os << std::endl - << "\033[1m-V\033[0m Print all underlying commands being executed. This" << ::std::endl - << " options is equivalent to \033[1m--verbose 3\033[0m." << ::std::endl; + << "\033[1m-V\033[0m Print all underlying commands being executed. This" << ::std::endl + << " options is equivalent to \033[1m--verbose 3\033[0m." << ::std::endl; os << std::endl - << "\033[1m--quiet\033[0m|\033[1m-q\033[0m Run quietly, only printing error messages in most" << ::std::endl - << " contexts. In certain contexts (for example, while" << ::std::endl - << " updating build system modules) this verbosity level may" << ::std::endl - << " be ignored. Use \033[1m--silent\033[0m to run quietly in all contexts." << ::std::endl - << " This option is equivalent to \033[1m--verbose 0\033[0m." << ::std::endl; + << "\033[1m--quiet\033[0m|\033[1m-q\033[0m Run quietly, only printing error messages in most" << ::std::endl + << " contexts. In certain contexts (for example, while" << ::std::endl + << " updating build system modules) this verbosity level may" << ::std::endl + << " be ignored. Use \033[1m--silent\033[0m to run quietly in all" << ::std::endl + << " contexts. This option is equivalent to \033[1m--verbose 0\033[0m." << ::std::endl; os << std::endl - << "\033[1m--silent\033[0m Run quietly, only printing error messages in all" << ::std::endl - << " contexts." << ::std::endl; + << "\033[1m--silent\033[0m Run quietly, only printing error messages in all" << ::std::endl + << " contexts." << ::std::endl; os << std::endl - << "\033[1m--verbose\033[0m \033[4mlevel\033[0m Set the diagnostics verbosity to \033[4mlevel\033[0m between 0 and 6." << ::std::endl - << " Level 0 disables any non-error messages (but see the" << ::std::endl - << " difference between \033[1m--quiet\033[0m and \033[1m--silent\033[0m) while level 6" << ::std::endl - << " produces lots of information, with level 1 being the" << ::std::endl - << " default. The following additional types of diagnostics" << ::std::endl - << " are produced at each level:" << ::std::endl + << "\033[1m--verbose\033[0m \033[4mlevel\033[0m Set the diagnostics verbosity to \033[4mlevel\033[0m between 0 and 6." << ::std::endl + << " Level 0 disables any non-error messages (but see the" << ::std::endl + << " difference between \033[1m--quiet\033[0m and \033[1m--silent\033[0m) while level 6" << ::std::endl + << " produces lots of information, with level 1 being the" << ::std::endl + << " default. The following additional types of diagnostics" << ::std::endl + << " are produced at each level:" << ::std::endl << ::std::endl - << " 1. High-level information messages." << ::std::endl - << " 2. Essential underlying commands being executed." << ::std::endl - << " 3. All underlying commands being executed." << ::std::endl - << " 4. Information that could be helpful to the user." << ::std::endl - << " 5. Information that could be helpful to the developer." << ::std::endl - << " 6. Even more detailed information." << ::std::endl; + << " 1. High-level information messages." << ::std::endl + << " 2. Essential underlying commands being executed." << ::std::endl + << " 3. All underlying commands being executed." << ::std::endl + << " 4. Information that could be helpful to the user." << ::std::endl + << " 5. Information that could be helpful to the developer." << ::std::endl + << " 6. Even more detailed information." << ::std::endl; os << std::endl - << "\033[1m--stat\033[0m Display build statistics." << ::std::endl; + << "\033[1m--stat\033[0m Display build statistics." << ::std::endl; os << std::endl - << "\033[1m--dump\033[0m \033[4mphase\033[0m Dump the build system state after the specified phase." << ::std::endl - << " Valid \033[4mphase\033[0m values are \033[1mload\033[0m (after loading \033[1mbuildfiles\033[0m)" << ::std::endl - << " and \033[1mmatch\033[0m (after matching rules to targets). Repeat this" << ::std::endl - << " option to dump the state after multiple phases." << ::std::endl; + << "\033[1m--dump\033[0m \033[4mphase\033[0m Dump the build system state after the specified phase." << ::std::endl + << " Valid \033[4mphase\033[0m values are \033[1mload\033[0m (after loading \033[1mbuildfiles\033[0m)" << ::std::endl + << " and \033[1mmatch\033[0m (after matching rules to targets). Repeat" << ::std::endl + << " this option to dump the state after multiple phases." << ::std::endl; os << std::endl - << "\033[1m--progress\033[0m Display build progress. If printing to a terminal the" << ::std::endl - << " progress is displayed by default for low verbosity" << ::std::endl - << " levels. Use \033[1m--no-progress\033[0m to suppress." << ::std::endl; + << "\033[1m--progress\033[0m Display build progress. If printing to a terminal the" << ::std::endl + << " progress is displayed by default for low verbosity" << ::std::endl + << " levels. Use \033[1m--no-progress\033[0m to suppress." << ::std::endl; os << std::endl - << "\033[1m--no-progress\033[0m Don't display build progress." << ::std::endl; + << "\033[1m--no-progress\033[0m Don't display build progress." << ::std::endl; os << std::endl - << "\033[1m--jobs\033[0m|\033[1m-j\033[0m \033[4mnum\033[0m Number of active jobs to perform in parallel. This" << ::std::endl - << " includes both the number of active threads inside the" << ::std::endl - << " build system as well as the number of external commands" << ::std::endl - << " (compilers, linkers, etc) started but not yet finished." << ::std::endl - << " If this option is not specified or specified with the \033[1m0\033[0m" << ::std::endl - << " value, then the number of available hardware threads is" << ::std::endl - << " used." << ::std::endl; + << "\033[1m--jobs\033[0m|\033[1m-j\033[0m \033[4mnum\033[0m Number of active jobs to perform in parallel. This" << ::std::endl + << " includes both the number of active threads inside the" << ::std::endl + << " build system as well as the number of external commands" << ::std::endl + << " (compilers, linkers, etc) started but not yet finished." << ::std::endl + << " If this option is not specified or specified with the" << ::std::endl + << " \033[1m0\033[0m value, then the number of available hardware threads" << ::std::endl + << " is used." << ::std::endl; os << std::endl - << "\033[1m--max-jobs\033[0m|\033[1m-J\033[0m \033[4mnum\033[0m Maximum number of jobs (threads) to create. The default" << ::std::endl - << " is 8x the number of active jobs (\033[1m--jobs|j\033[0m) on 32-bit" << ::std::endl - << " architectures and 32x on 64-bit. See the build system" << ::std::endl - << " scheduler implementation for details." << ::std::endl; + << "\033[1m--max-jobs\033[0m|\033[1m-J\033[0m \033[4mnum\033[0m Maximum number of jobs (threads) to create. The default" << ::std::endl + << " is 8x the number of active jobs (\033[1m--jobs|j\033[0m) on 32-bit" << ::std::endl + << " architectures and 32x on 64-bit. See the build system" << ::std::endl + << " scheduler implementation for details." << ::std::endl; os << std::endl - << "\033[1m--queue-depth\033[0m|\033[1m-Q\033[0m \033[4mnum\033[0m The queue depth as a multiplier over the number of active" << ::std::endl - << " jobs. Normally we want a deeper queue if the jobs take" << ::std::endl - << " long (for example, compilation) and shorter if they are" << ::std::endl - << " quick (for example, simple tests). The default is 4. See" << ::std::endl - << " the build system scheduler implementation for details." << ::std::endl; + << "\033[1m--queue-depth\033[0m|\033[1m-Q\033[0m \033[4mnum\033[0m The queue depth as a multiplier over the number of" << ::std::endl + << " active jobs. Normally we want a deeper queue if the" << ::std::endl + << " jobs take long (for example, compilation) and shorter" << ::std::endl + << " if they are quick (for example, simple tests). The" << ::std::endl + << " default is 4. See the build system scheduler" << ::std::endl + << " implementation for details." << ::std::endl; os << std::endl - << "\033[1m--file-cache\033[0m \033[4mimpl\033[0m File cache implementation to use for intermediate build" << ::std::endl - << " results. Valid values are \033[1mnoop\033[0m (no caching or" << ::std::endl - << " compression) and \033[1msync-lz4\033[0m (no caching with synchronous" << ::std::endl - << " LZ4 on-disk compression). If this option is not" << ::std::endl - << " specified, then a suitable default implementation is used" << ::std::endl - << " (currently \033[1msync-lz4\033[0m)." << ::std::endl; + << "\033[1m--file-cache\033[0m \033[4mimpl\033[0m File cache implementation to use for intermediate build" << ::std::endl + << " results. Valid values are \033[1mnoop\033[0m (no caching or" << ::std::endl + << " compression) and \033[1msync-lz4\033[0m (no caching with synchronous" << ::std::endl + << " LZ4 on-disk compression). If this option is not" << ::std::endl + << " specified, then a suitable default implementation is" << ::std::endl + << " used (currently \033[1msync-lz4\033[0m)." << ::std::endl; os << std::endl - << "\033[1m--max-stack\033[0m \033[4mnum\033[0m The maximum stack size in KBytes to allow for newly" << ::std::endl - << " created threads. For \033[4mpthreads\033[0m-based systems the driver" << ::std::endl - << " queries the stack size of the main thread and uses the" << ::std::endl - << " same size for creating additional threads. This allows" << ::std::endl - << " adjusting the stack size using familiar mechanisms, such" << ::std::endl - << " as \033[1mulimit\033[0m. Sometimes, however, the stack size of the main" << ::std::endl - << " thread is excessively large. As a result, the driver" << ::std::endl - << " checks if it is greater than a predefined limit (64MB on" << ::std::endl - << " 64-bit systems and 32MB on 32-bit ones) and caps it to a" << ::std::endl - << " more sensible value (8MB) if that's the case. This option" << ::std::endl - << " allows you to override this check with the special zero" << ::std::endl - << " value indicating that the main thread stack size should" << ::std::endl - << " be used as is." << ::std::endl; + << "\033[1m--max-stack\033[0m \033[4mnum\033[0m The maximum stack size in KBytes to allow for newly" << ::std::endl + << " created threads. For \033[4mpthreads\033[0m-based systems the driver" << ::std::endl + << " queries the stack size of the main thread and uses the" << ::std::endl + << " same size for creating additional threads. This allows" << ::std::endl + << " adjusting the stack size using familiar mechanisms," << ::std::endl + << " such as \033[1mulimit\033[0m. Sometimes, however, the stack size of" << ::std::endl + << " the main thread is excessively large. As a result, the" << ::std::endl + << " driver checks if it is greater than a predefined limit" << ::std::endl + << " (64MB on 64-bit systems and 32MB on 32-bit ones) and" << ::std::endl + << " caps it to a more sensible value (8MB) if that's the" << ::std::endl + << " case. This option allows you to override this check" << ::std::endl + << " with the special zero value indicating that the main" << ::std::endl + << " thread stack size should be used as is." << ::std::endl; os << std::endl - << "\033[1m--serial-stop\033[0m|\033[1m-s\033[0m Run serially and stop at the first error. This mode is" << ::std::endl - << " useful to investigate build failures that are caused by" << ::std::endl - << " build system errors rather than compilation errors. Note" << ::std::endl - << " that if you don't want to keep going but still want" << ::std::endl - << " parallel execution, add \033[1m--jobs|-j\033[0m (for example \033[1m-j 0\033[0m for" << ::std::endl - << " default concurrency)." << ::std::endl; + << "\033[1m--serial-stop\033[0m|\033[1m-s\033[0m Run serially and stop at the first error. This mode is" << ::std::endl + << " useful to investigate build failures that are caused by" << ::std::endl + << " build system errors rather than compilation errors." << ::std::endl + << " Note that if you don't want to keep going but still" << ::std::endl + << " want parallel execution, add \033[1m--jobs|-j\033[0m (for example \033[1m-j" << ::std::endl + << " 0\033[0m for default concurrency)." << ::std::endl; os << std::endl - << "\033[1m--dry-run\033[0m|\033[1m-n\033[0m Print commands without actually executing them. Note that" << ::std::endl - << " commands that are required to create an accurate build" << ::std::endl - << " state will still be executed and the extracted auxiliary" << ::std::endl - << " dependency information saved. In other words, this is not" << ::std::endl - << " the \033[4m\"don't touch the filesystem\"\033[0m mode but rather \033[4m\"do" << ::std::endl - << " minimum amount of work to show what needs to be done\"\033[0m." << ::std::endl - << " Note also that only the \033[1mperform\033[0m meta-operation supports" << ::std::endl - << " this mode." << ::std::endl; + << "\033[1m--dry-run\033[0m|\033[1m-n\033[0m Print commands without actually executing them. Note" << ::std::endl + << " that commands that are required to create an accurate" << ::std::endl + << " build state will still be executed and the extracted" << ::std::endl + << " auxiliary dependency information saved. In other words," << ::std::endl + << " this is not the \033[4m\"don't touch the filesystem\"\033[0m mode but" << ::std::endl + << " rather \033[4m\"do minimum amount of work to show what needs to" << ::std::endl + << " be done\"\033[0m. Note also that only the \033[1mperform\033[0m" << ::std::endl + << " meta-operation supports this mode." << ::std::endl; os << std::endl - << "\033[1m--match-only\033[0m Match the rules but do not execute the operation. This" << ::std::endl - << " mode is primarily useful for profiling." << ::std::endl; + << "\033[1m--match-only\033[0m Match the rules but do not execute the operation. This" << ::std::endl + << " mode is primarily useful for profiling." << ::std::endl; os << std::endl - << "\033[1m--no-external-modules\033[0m Don't load external modules during project bootstrap." << ::std::endl - << " Note that this option can only be used with" << ::std::endl - << " meta-operations that do not load the project's" << ::std::endl - << " \033[1mbuildfiles\033[0m, such as \033[1minfo\033[0m." << ::std::endl; + << "\033[1m--no-external-modules\033[0m Don't load external modules during project bootstrap." << ::std::endl + << " Note that this option can only be used with" << ::std::endl + << " meta-operations that do not load the project's" << ::std::endl + << " \033[1mbuildfiles\033[0m, such as \033[1minfo\033[0m." << ::std::endl; os << std::endl - << "\033[1m--structured-result\033[0m Write the result of execution in a structured form. In" << ::std::endl - << " this mode, instead of printing to \033[1mstderr\033[0m diagnostics" << ::std::endl - << " messages about the outcome of executing actions on" << ::std::endl - << " targets, the driver writes to \033[1mstdout\033[0m a structured result" << ::std::endl - << " description one line per the buildspec action/target" << ::std::endl - << " pair. Each line has the following format:" << ::std::endl + << "\033[1m--structured-result\033[0m \033[4mfmt\033[0m Write the result of execution in a structured form. In" << ::std::endl + << " this mode, instead of printing to \033[1mstderr\033[0m diagnostics" << ::std::endl + << " messages about the outcome of executing actions on" << ::std::endl + << " targets, the driver writes to \033[1mstdout\033[0m a machine-readable" << ::std::endl + << " result description in the specified format. Valid" << ::std::endl + << " values for this option are \033[1mlines\033[0m and \033[1mjson\033[0m. Note that" << ::std::endl + << " currently only the \033[1mperform\033[0m meta-operation supports the" << ::std::endl + << " structured result output." << ::std::endl + << ::std::endl + << " If the output format is \033[1mlines\033[0m, then the result is" << ::std::endl + << " written one line per the buildspec action/target pair." << ::std::endl + << " Each line has the following form:" << ::std::endl + << ::std::endl + << " \033[4mstate\033[0m \033[4mmeta-operation\033[0m \033[4moperation\033[0m \033[4mtarget\033[0m\033[0m" << ::std::endl + << ::std::endl + << " Where \033[4mstate\033[0m can be one of \033[1munchanged\033[0m, \033[1mchanged\033[0m, or" << ::std::endl + << " \033[1mfailed\033[0m. If the action is a pre or post operation, then" << ::std::endl + << " the outer operation is specified in parenthesis. For" << ::std::endl + << " example:" << ::std::endl + << ::std::endl + << " unchanged perform update(test) /tmp/dir{hello/}" << ::std::endl + << " changed perform test /tmp/hello/exe{test}" << ::std::endl << ::std::endl - << " \033[4mstate\033[0m \033[4mmeta-operation\033[0m \033[4moperation\033[0m \033[4mtarget\033[0m\033[0m" << ::std::endl + << " If the output format is \033[1mjson\033[0m, then the output is a JSON" << ::std::endl + << " array of objects which are the serialized" << ::std::endl + << " representation of the following C++ \033[1mstruct\033[0m" << ::std::endl + << " \033[1mtarget_action_result\033[0m:" << ::std::endl << ::std::endl - << " Where \033[4mstate\033[0m can be one of \033[1munchanged\033[0m, \033[1mchanged\033[0m, or \033[1mfailed\033[0m." << ::std::endl - << " If the action is a pre or post operation, then the outer" << ::std::endl - << " operation is specified in parenthesis. For example:" << ::std::endl + << " struct target_action_result" << ::std::endl + << " {" << ::std::endl + << " string target;" << ::std::endl + << " string quoted_target;" << ::std::endl + << " string target_type;" << ::std::endl + << " optional target_path;" << ::std::endl + << " string meta_operation;" << ::std::endl + << " string operation;" << ::std::endl + << " optional outer_operation;" << ::std::endl + << " string state;" << ::std::endl + << " };" << ::std::endl << ::std::endl - << " unchanged perform update(test) /tmp/dir{hello/}" << ::std::endl - << " changed perform test /tmp/dir{hello/}" << ::std::endl + << " For example:" << ::std::endl << ::std::endl - << " Note that only the \033[1mperform\033[0m meta-operation supports the" << ::std::endl - << " structured result output." << ::std::endl; + << " [" << ::std::endl + << " {" << ::std::endl + << " \"target\": \"/tmp/dir{hello/}\"," << ::std::endl + << " \"quoted_target\": \"/tmp/dir{hello/}\"," << ::std::endl + << " \"target_type\": \"dir\"," << ::std::endl + << " \"target_path\": \"/tmp/hello\"," << ::std::endl + << " \"meta_operation\": \"perform\"," << ::std::endl + << " \"operation\": \"update\"," << ::std::endl + << " \"outer_operation\": \"test\"," << ::std::endl + << " \"state\": \"unchanged\"" << ::std::endl + << " }," << ::std::endl + << " {" << ::std::endl + << " \"target\": \"/tmp/dir{hello/}\"," << ::std::endl + << " \"quoted_target\": \"/tmp/dir{hello/}\"," << ::std::endl + << " \"target_type\": \"dir\"," << ::std::endl + << " \"target_path\": \"/tmp/hello\"," << ::std::endl + << " \"meta_operation\": \"perform\"," << ::std::endl + << " \"operation\": \"test\"," << ::std::endl + << " \"state\": \"changed\"" << ::std::endl + << " }" << ::std::endl + << " ]" << ::std::endl + << ::std::endl + << " See the JSON OUTPUT section below for details on the" << ::std::endl + << " overall properties of this format and the semantics of" << ::std::endl + << " the \033[1mstruct\033[0m serialization." << ::std::endl + << ::std::endl + << " The \033[1mtarget\033[0m member is a \"display\" target name, the same" << ::std::endl + << " as in the \033[1mlines\033[0m format. The \033[1mquoted_target\033[0m member is a" << ::std::endl + << " target name that, if required, is quoted so that it can" << ::std::endl + << " be passed back to the driver on the command line. The" << ::std::endl + << " \033[1mtarget_type\033[0m member is the type of target. The" << ::std::endl + << " \033[1mtarget_path\033[0m member is an absolute path to the target if" << ::std::endl + << " the target type is path-based or \033[1mdir\033[0m." << ::std::endl; os << std::endl - << "\033[1m--mtime-check\033[0m Perform file modification time sanity checks. These" << ::std::endl - << " checks can be helpful in diagnosing spurious rebuilds and" << ::std::endl - << " are enabled by default on Windows (which is known not to" << ::std::endl - << " guarantee monotonically increasing mtimes) and for the" << ::std::endl - << " staged version of the build system on other platforms." << ::std::endl - << " Use \033[1m--no-mtime-check\033[0m to disable." << ::std::endl; + << "\033[1m--mtime-check\033[0m Perform file modification time sanity checks. These" << ::std::endl + << " checks can be helpful in diagnosing spurious rebuilds" << ::std::endl + << " and are enabled by default on Windows (which is known" << ::std::endl + << " not to guarantee monotonically increasing mtimes) and" << ::std::endl + << " for the staged version of the build system on other" << ::std::endl + << " platforms. Use \033[1m--no-mtime-check\033[0m to disable." << ::std::endl; os << std::endl - << "\033[1m--no-mtime-check\033[0m Don't perform file modification time sanity checks. See" << ::std::endl - << " \033[1m--mtime-check\033[0m for details." << ::std::endl; + << "\033[1m--no-mtime-check\033[0m Don't perform file modification time sanity checks. See" << ::std::endl + << " \033[1m--mtime-check\033[0m for details." << ::std::endl; os << std::endl - << "\033[1m--no-column\033[0m Don't print column numbers in diagnostics." << ::std::endl; + << "\033[1m--no-column\033[0m Don't print column numbers in diagnostics." << ::std::endl; os << std::endl - << "\033[1m--no-line\033[0m Don't print line and column numbers in diagnostics." << ::std::endl; + << "\033[1m--no-line\033[0m Don't print line and column numbers in diagnostics." << ::std::endl; os << std::endl - << "\033[1m--buildfile\033[0m \033[4mpath\033[0m The alternative file to read build information from. The" << ::std::endl - << " default is \033[1mbuildfile\033[0m or \033[1mbuild2file\033[0m, depending on the" << ::std::endl - << " project's build file/directory naming scheme. If \033[4mpath\033[0m is" << ::std::endl - << " '\033[1m-\033[0m', then read from \033[1mstdin\033[0m. Note that this option only" << ::std::endl - << " affects the files read as part of the buildspec" << ::std::endl - << " processing. Specifically, it has no effect on the \033[1msource\033[0m" << ::std::endl - << " and \033[1minclude\033[0m directives. As a result, this option is" << ::std::endl - << " primarily intended for testing rather than changing the" << ::std::endl - << " build file names in real projects." << ::std::endl; + << "\033[1m--buildfile\033[0m \033[4mpath\033[0m The alternative file to read build information from." << ::std::endl + << " The default is \033[1mbuildfile\033[0m or \033[1mbuild2file\033[0m, depending on" << ::std::endl + << " the project's build file/directory naming scheme. If" << ::std::endl + << " \033[4mpath\033[0m is '\033[1m-\033[0m', then read from \033[1mstdin\033[0m. Note that this" << ::std::endl + << " option only affects the files read as part of the" << ::std::endl + << " buildspec processing. Specifically, it has no effect on" << ::std::endl + << " the \033[1msource\033[0m and \033[1minclude\033[0m directives. As a result, this" << ::std::endl + << " option is primarily intended for testing rather than" << ::std::endl + << " changing the build file names in real projects." << ::std::endl; os << std::endl - << "\033[1m--config-guess\033[0m \033[4mpath\033[0m The path to the \033[1mconfig.guess(1)\033[0m script that should be" << ::std::endl - << " used to guess the host machine triplet. If this option is" << ::std::endl - << " not specified, then \033[1mb\033[0m will fall back on to using the" << ::std::endl - << " target it was built for as host." << ::std::endl; + << "\033[1m--config-guess\033[0m \033[4mpath\033[0m The path to the \033[1mconfig.guess(1)\033[0m script that should be" << ::std::endl + << " used to guess the host machine triplet. If this option" << ::std::endl + << " is not specified, then \033[1mb\033[0m will fall back on to using the" << ::std::endl + << " target it was built for as host." << ::std::endl; os << std::endl - << "\033[1m--config-sub\033[0m \033[4mpath\033[0m The path to the \033[1mconfig.sub(1)\033[0m script that should be used" << ::std::endl - << " to canonicalize machine triplets. If this option is not" << ::std::endl - << " specified, then \033[1mb\033[0m will use its built-in canonicalization" << ::std::endl - << " support which should be sufficient for commonly-used" << ::std::endl - << " platforms." << ::std::endl; + << "\033[1m--config-sub\033[0m \033[4mpath\033[0m The path to the \033[1mconfig.sub(1)\033[0m script that should be" << ::std::endl + << " used to canonicalize machine triplets. If this option" << ::std::endl + << " is not specified, then \033[1mb\033[0m will use its built-in" << ::std::endl + << " canonicalization support which should be sufficient for" << ::std::endl + << " commonly-used platforms." << ::std::endl; os << std::endl - << "\033[1m--pager\033[0m \033[4mpath\033[0m The pager program to be used to show long text. Commonly" << ::std::endl - << " used pager programs are \033[1mless\033[0m and \033[1mmore\033[0m. You can also" << ::std::endl - << " specify additional options that should be passed to the" << ::std::endl - << " pager program with \033[1m--pager-option\033[0m. If an empty string is" << ::std::endl - << " specified as the pager program, then no pager will be" << ::std::endl - << " used. If the pager program is not explicitly specified," << ::std::endl - << " then \033[1mb\033[0m will try to use \033[1mless\033[0m. If it is not available, then" << ::std::endl - << " no pager will be used." << ::std::endl; + << "\033[1m--pager\033[0m \033[4mpath\033[0m The pager program to be used to show long text." << ::std::endl + << " Commonly used pager programs are \033[1mless\033[0m and \033[1mmore\033[0m. You can" << ::std::endl + << " also specify additional options that should be passed" << ::std::endl + << " to the pager program with \033[1m--pager-option\033[0m. If an empty" << ::std::endl + << " string is specified as the pager program, then no pager" << ::std::endl + << " will be used. If the pager program is not explicitly" << ::std::endl + << " specified, then \033[1mb\033[0m will try to use \033[1mless\033[0m. If it is not" << ::std::endl + << " available, then no pager will be used." << ::std::endl; os << std::endl - << "\033[1m--pager-option\033[0m \033[4mopt\033[0m Additional option to be passed to the pager program. See" << ::std::endl - << " \033[1m--pager\033[0m for more information on the pager program. Repeat" << ::std::endl - << " this option to specify multiple pager options." << ::std::endl; + << "\033[1m--pager-option\033[0m \033[4mopt\033[0m Additional option to be passed to the pager program." << ::std::endl + << " See \033[1m--pager\033[0m for more information on the pager program." << ::std::endl + << " Repeat this option to specify multiple pager options." << ::std::endl; os << std::endl - << "\033[1m--options-file\033[0m \033[4mfile\033[0m Read additional options from \033[4mfile\033[0m. Each option should" << ::std::endl - << " appear on a separate line optionally followed by space or" << ::std::endl - << " equal sign (\033[1m=\033[0m) and an option value. Empty lines and lines" << ::std::endl - << " starting with \033[1m#\033[0m are ignored. Option values can be" << ::std::endl - << " enclosed in double (\033[1m\"\033[0m) or single (\033[1m'\033[0m) quotes to preserve" << ::std::endl - << " leading and trailing whitespaces as well as to specify" << ::std::endl - << " empty values. If the value itself contains trailing or" << ::std::endl - << " leading quotes, enclose it with an extra pair of quotes," << ::std::endl - << " for example \033[1m'\"x\"'\033[0m. Non-leading and non-trailing quotes" << ::std::endl - << " are interpreted as being part of the option value." << ::std::endl + << "\033[1m--options-file\033[0m \033[4mfile\033[0m Read additional options from \033[4mfile\033[0m. Each option should" << ::std::endl + << " appear on a separate line optionally followed by space" << ::std::endl + << " or equal sign (\033[1m=\033[0m) and an option value. Empty lines and" << ::std::endl + << " lines starting with \033[1m#\033[0m are ignored. Option values can be" << ::std::endl + << " enclosed in double (\033[1m\"\033[0m) or single (\033[1m'\033[0m) quotes to preserve" << ::std::endl + << " leading and trailing whitespaces as well as to specify" << ::std::endl + << " empty values. If the value itself contains trailing or" << ::std::endl + << " leading quotes, enclose it with an extra pair of" << ::std::endl + << " quotes, for example \033[1m'\"x\"'\033[0m. Non-leading and non-trailing" << ::std::endl + << " quotes are interpreted as being part of the option" << ::std::endl + << " value." << ::std::endl << ::std::endl - << " The semantics of providing options in a file is" << ::std::endl - << " equivalent to providing the same set of options in the" << ::std::endl - << " same order on the command line at the point where the" << ::std::endl - << " \033[1m--options-file\033[0m option is specified except that the shell" << ::std::endl - << " escaping and quoting is not required. Repeat this option" << ::std::endl - << " to specify more than one options file." << ::std::endl; + << " The semantics of providing options in a file is" << ::std::endl + << " equivalent to providing the same set of options in the" << ::std::endl + << " same order on the command line at the point where the" << ::std::endl + << " \033[1m--options-file\033[0m option is specified except that the" << ::std::endl + << " shell escaping and quoting is not required. Repeat this" << ::std::endl + << " option to specify more than one options file." << ::std::endl; os << std::endl - << "\033[1m--default-options\033[0m \033[4mdir\033[0m The directory to load additional default options files" << ::std::endl - << " from." << ::std::endl; + << "\033[1m--default-options\033[0m \033[4mdir\033[0m The directory to load additional default options files" << ::std::endl + << " from." << ::std::endl; os << std::endl - << "\033[1m--no-default-options\033[0m Don't load default options files." << ::std::endl; + << "\033[1m--no-default-options\033[0m Don't load default options files." << ::std::endl; os << std::endl - << "\033[1m--help\033[0m Print usage information and exit." << ::std::endl; + << "\033[1m--help\033[0m Print usage information and exit." << ::std::endl; os << std::endl - << "\033[1m--version\033[0m Print version and exit." << ::std::endl; + << "\033[1m--version\033[0m Print version and exit." << ::std::endl; p = ::build2::build::cli::usage_para::option; @@ -898,7 +959,8 @@ namespace build2 _cli_options_map_["--no-external-modules"] = &::build2::build::cli::thunk< options, bool, &options::no_external_modules_ >; _cli_options_map_["--structured-result"] = - &::build2::build::cli::thunk< options, bool, &options::structured_result_ >; + &::build2::build::cli::thunk< options, structured_result_format, &options::structured_result_, + &options::structured_result_specified_ >; _cli_options_map_["--mtime-check"] = &::build2::build::cli::thunk< options, bool, &options::mtime_check_ >; _cli_options_map_["--no-mtime-check"] = @@ -1183,6 +1245,59 @@ namespace build2 << "The order in which default options files are loaded is traced at the verbosity" << ::std::endl << "level 3 (\033[1m-V\033[0m option) or higher." << ::std::endl << ::std::endl + << "\033[1mJSON OUTPUT\033[0m" << ::std::endl + << ::std::endl + << "Commands that support the JSON output specify their formats as a serialized" << ::std::endl + << "representation of a C++ \033[1mstruct\033[0m or an array thereof. For example:" << ::std::endl + << ::std::endl + << "struct package" << ::std::endl + << "{" << ::std::endl + << " string name;" << ::std::endl + << "};" << ::std::endl + << ::std::endl + << "struct configuration" << ::std::endl + << "{" << ::std::endl + << " uint64_t id;" << ::std::endl + << " string path;" << ::std::endl + << " optional name;" << ::std::endl + << " bool default;" << ::std::endl + << " vector packages;" << ::std::endl + << "};" << ::std::endl + << ::std::endl + << "An example of the serialized JSON representation of \033[1mstruct\033[0m \033[1mconfiguration\033[0m:" << ::std::endl + << ::std::endl + << "{" << ::std::endl + << " \"id\": 1," << ::std::endl + << " \"path\": \"/tmp/hello-gcc\"," << ::std::endl + << " \"name\": \"gcc\"," << ::std::endl + << " \"default\": true," << ::std::endl + << " \"packages\": [" << ::std::endl + << " {" << ::std::endl + << " \"name\": \"hello\"" << ::std::endl + << " }" << ::std::endl + << " ]" << ::std::endl + << "}" << ::std::endl + << ::std::endl + << "This sections provides details on the overall properties of such formats and" << ::std::endl + << "the semantics of the \033[1mstruct\033[0m serialization." << ::std::endl + << ::std::endl + << "The order of members in a JSON object is fixed as specified in the" << ::std::endl + << "corresponding \033[1mstruct\033[0m. While new members may be added in the future (and should" << ::std::endl + << "be ignored by older consumers), the semantics of the existing members" << ::std::endl + << "(including whether the top-level entry is an object or array) may not change." << ::std::endl + << ::std::endl + << "An object member is required unless its type is \033[1moptional<>\033[0m, \033[1mbool\033[0m, or \033[1mvector<>\033[0m" << ::std::endl + << "(array). For \033[1mbool\033[0m members absent means \033[1mfalse\033[0m. For \033[1mvector<>\033[0m members absent means" << ::std::endl + << "empty. An empty top-level array is always present." << ::std::endl + << ::std::endl + << "For example, the following JSON text is a possible serialization of the above" << ::std::endl + << "\033[1mstruct\033[0m \033[1mconfiguration\033[0m:" << ::std::endl + << ::std::endl + << "{" << ::std::endl + << " \"id\": 1," << ::std::endl + << " \"path\": \"/tmp/hello-gcc\"" << ::std::endl + << "}" << ::std::endl + << ::std::endl << "\033[1mEXIT STATUS\033[0m" << ::std::endl << ::std::endl << "Non-zero exit status is returned in case of an error." << ::std::endl; diff --git a/libbuild2/b-options.hxx b/libbuild2/b-options.hxx index 3f8fed7..ffdecf5 100644 --- a/libbuild2/b-options.hxx +++ b/libbuild2/b-options.hxx @@ -15,8 +15,6 @@ #include -#include - #include namespace build2 @@ -154,9 +152,12 @@ namespace build2 const bool& no_external_modules () const; - const bool& + const structured_result_format& structured_result () const; + bool + structured_result_specified () const; + const bool& mtime_check () const; @@ -266,7 +267,8 @@ namespace build2 bool dry_run_; bool match_only_; bool no_external_modules_; - bool structured_result_; + structured_result_format structured_result_; + bool structured_result_specified_; bool mtime_check_; bool no_mtime_check_; bool no_column_; diff --git a/libbuild2/b-options.ixx b/libbuild2/b-options.ixx index 0875dbd..8030ef3 100644 --- a/libbuild2/b-options.ixx +++ b/libbuild2/b-options.ixx @@ -176,12 +176,18 @@ namespace build2 return this->no_external_modules_; } - inline const bool& options:: + inline const structured_result_format& options:: structured_result () const { return this->structured_result_; } + inline bool options:: + structured_result_specified () const + { + return this->structured_result_specified_; + } + inline const bool& options:: mtime_check () const { 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 ; -include ; include ; @@ -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 name; + }; + + struct project_info + { + optional project; + optional version; + optional summary; + optional url; + string src_root; + string out_root; + optional amalgamation; + vector subprojects; + vector operations; + vector meta_operations; + vector 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 { + "", + "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 target_path; + string meta_operation; + string operation; + optional 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 name; + bool default; + vector 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. diff --git a/libbuild2/build/script/builtin-options.hxx b/libbuild2/build/script/builtin-options.hxx index 544daca..590d3b2 100644 --- a/libbuild2/build/script/builtin-options.hxx +++ b/libbuild2/build/script/builtin-options.hxx @@ -12,8 +12,6 @@ // // End prologue. -#include - #include namespace build2 diff --git a/libbuild2/build/script/builtin.cli b/libbuild2/build/script/builtin.cli index 4e2df4b..7d0936f 100644 --- a/libbuild2/build/script/builtin.cli +++ b/libbuild2/build/script/builtin.cli @@ -1,8 +1,6 @@ // file : libbuild2/build/script/builtin.cli // license : MIT; see accompanying LICENSE file -include ; - include ; // Note that options in this file are undocumented because we generate neither diff --git a/libbuild2/buildfile b/libbuild2/buildfile index 2fb4bde..52252d6 100644 --- a/libbuild2/buildfile +++ b/libbuild2/buildfile @@ -273,7 +273,7 @@ if $cli.configured # Usage options. # cli.options += --suppress-undocumented --long-usage --ansi-color \ ---ascii-tree --page-usage 'build2::print_$name$_' --option-length 21 +--ascii-tree --page-usage 'build2::print_$name$_' --option-length 23 } script/cli.cxx{builtin-options}: script/cli{builtin} diff --git a/libbuild2/common-options.hxx b/libbuild2/common-options.hxx index 13f72d2..f52fc3c 100644 --- a/libbuild2/common-options.hxx +++ b/libbuild2/common-options.hxx @@ -466,6 +466,10 @@ namespace build2 } } +#include + +#include + namespace build2 { } diff --git a/libbuild2/common.cli b/libbuild2/common.cli index 2c49ace..86c2ad1 100644 --- a/libbuild2/common.cli +++ b/libbuild2/common.cli @@ -1,6 +1,9 @@ // file : libbuild2/common.cli // license : MIT; see accompanying LICENSE file +include ; +include ; + namespace build2 { } diff --git a/libbuild2/operation.cxx b/libbuild2/operation.cxx index 68666cb..72b73f9 100644 --- a/libbuild2/operation.cxx +++ b/libbuild2/operation.cxx @@ -6,6 +6,10 @@ #include // cout #include +#ifndef BUILD2_BOOTSTRAP +# include +#endif + #include #include #include @@ -594,6 +598,36 @@ namespace build2 // info // + + // Note: similar approach to forward() in configure. + // + static bool + info_json (const values& params, + const char* mo = nullptr, + const location& l = location ()) + { + if (params.size () == 1) + { + const names& ns (cast (params[0])); + + if (ns.size () == 1 && ns[0].simple () && ns[0].value == "json") + return true; + else if (!ns.empty ()) + fail (l) << "unexpected parameter '" << ns << "' for " + << "meta-operation " << mo; + } + else if (!params.empty ()) + fail (l) << "unexpected parameters for meta-operation " << mo; + + return false; + } + + static void + info_pre (context&, const values& params, const location& l) + { + info_json (params, "info", l); // Validate. + } + static operation_id info_operation_pre (context&, const values&, operation_id o) { @@ -644,7 +678,7 @@ namespace build2 } static void - info_execute (const values&, action, action_targets& ts, uint16_t, bool) + info_execute_lines (action_targets& ts) { for (size_t i (0); i != ts.size (); ++i) { @@ -695,6 +729,20 @@ namespace build2 cout << ' ' << *p; }; + // Print a potentially null/empty directory path without trailing slash. + // + auto print_dir = [] (const dir_path& d) + { + if (!d.empty ()) + cout << ' ' << d.string (); + }; + + auto print_pdir = [&print_dir] (const dir_path* d) + { + if (d != nullptr) + print_dir (*d); + }; + // This could be a simple project that doesn't set project name. // cout @@ -702,9 +750,9 @@ namespace build2 << "version:" ; print_empty (cast_empty (rs[ctx.var_version])); cout << endl << "summary:" ; print_empty (cast_empty (rs[ctx.var_project_summary])); cout << endl << "url:" ; print_empty (cast_empty (rs[ctx.var_project_url])); cout << endl - << "src_root: " << cast (rs[ctx.var_src_root]) << endl - << "out_root: " << cast (rs[ctx.var_out_root]) << endl - << "amalgamation:" ; print_null (*rs.root_extra->amalgamation); cout << endl + << "src_root:" ; print_dir (cast (rs[ctx.var_src_root])); cout << endl + << "out_root:" ; print_dir (cast (rs[ctx.var_out_root])); cout << endl + << "amalgamation:" ; print_pdir (*rs.root_extra->amalgamation); cout << endl << "subprojects:" ; print_null (*rs.root_extra->subprojects); cout << endl << "operations:" ; print_ops (rs.root_extra->operations, ctx.operation_table); cout << endl << "meta-operations:"; print_ops (rs.root_extra->meta_operations, ctx.meta_operation_table); cout << endl @@ -712,6 +760,163 @@ namespace build2 } } +#ifndef BUILD2_BOOTSTRAP + static void + info_execute_json (action_targets& ts) + { + json::stream_serializer s (cout); + s.begin_array (); + + for (size_t i (0); i != ts.size (); ++i) + { + const scope& rs (ts[i].as ()); + + context& ctx (rs.ctx); + + s.begin_object (); + + // Print a potentially empty string. + // + auto print_string = [&s] (const char* n, + const string& v, + bool check = false) + { + if (!v.empty ()) + s.member (n, v, check); + }; + + // Print a potentially null/empty directory path without trailing slash. + // + auto print_dir = [&s] (const char* n, const dir_path& v) + { + if (!v.empty ()) + s.member (n, v.string ()); + }; + + auto print_pdir = [&print_dir] (const char* n, const dir_path* v) + { + if (v != nullptr) + print_dir (n, *v); + }; + + // Print [meta_]operation names (see info_lines() for details). + // + auto print_ops = [&s] (const char* name, + const auto& ov, + const auto& ot, + const auto& printer) + { + s.member_name (name, false /* check */); + + s.begin_array (); + + for (uint8_t id (2); id < ov.size (); ++id) + { + if (ov[id] != nullptr) + printer (ot[id]); + } + + s.end_array (); + }; + + // Note that we won't check some values for being valid UTF-8, since + // their characters belong to even stricter character sets and/or are + // read from buildfile which is already verified to be valid UTF-8. + // + print_string ("project", project (rs).string ()); + print_string ("version", cast_empty (rs[ctx.var_version])); + print_string ("summary", cast_empty (rs[ctx.var_project_summary])); + print_string ("url", cast_empty (rs[ctx.var_project_url])); + print_dir ("src_root", cast (rs[ctx.var_src_root])); + print_dir ("out_root", cast (rs[ctx.var_out_root])); + print_pdir ("amalgamation", *rs.root_extra->amalgamation); + + // Print subprojects. + // + { + const subprojects* sps (*rs.root_extra->subprojects); + + if (sps != nullptr && !sps->empty ()) + { + s.member_name ("subprojects", false /* check */); + s.begin_array (); + + for (const auto& sp: *sps) + { + s.begin_object (); + + print_dir ("path", sp.second); + + // See find_subprojects() for details. + // + const string& n (sp.first.string ()); + + if (!path::traits_type::is_separator (n.back ())) + print_string ("name", n); + + s.end_object (); + } + + s.end_array (); + } + } + + print_ops ("operations", + rs.root_extra->operations, + ctx.operation_table, + [&s] (const string& v) {s.value (v, false /* check */);}); + + print_ops ("meta-operations", + rs.root_extra->meta_operations, + ctx.meta_operation_table, + [&s] (const meta_operation_data& v) + { + s.value (v.name, false /* check */); + }); + + // Print modules. + // + if (!rs.root_extra->modules.empty ()) + { + s.member_name ("modules", false /* check */); + s.begin_array (); + + for (const module_state& ms: rs.root_extra->modules) + s.value (ms.name, false /* check */); + + s.end_array (); + } + + s.end_object (); + } + + s.end_array (); + cout << endl; + } +#else + static void + info_execute_json (action_targets&) + { + } +#endif //BUILD2_BOOTSTRAP + + static void + info_execute (const values& params, + action, + action_targets& ts, + uint16_t, + bool) + { + // Note that both outputs will not be "ideal" if the user does something + // like `b info(foo/) info(bar/)` instead of `b info(foo/ bar/)`. Oh, + // well. + // + if (info_json (params)) + info_execute_json (ts); + else + info_execute_lines (ts); + } + const meta_operation_info mo_info { info_id, "info", @@ -719,8 +924,8 @@ namespace build2 "", "", "", - false, // bootstrap_outer - nullptr, // meta-operation pre + false, // bootstrap_outer + &info_pre, // meta-operation pre &info_operation_pre, &info_load, &info_search, diff --git a/libbuild2/options-types.hxx b/libbuild2/options-types.hxx new file mode 100644 index 0000000..5c224a7 --- /dev/null +++ b/libbuild2/options-types.hxx @@ -0,0 +1,16 @@ +// file : libbuild2/options-types.hxx -*- C++ -*- +// license : MIT; see accompanying LICENSE file + +#ifndef LIBBUILD2_OPTIONS_TYPES_HXX +#define LIBBUILD2_OPTIONS_TYPES_HXX + +namespace build2 +{ + enum class structured_result_format + { + lines, + json + }; +} + +#endif // LIBBUILD2_OPTIONS_TYPES_HXX diff --git a/libbuild2/scope.cxx b/libbuild2/scope.cxx index 93f21db..91aee12 100644 --- a/libbuild2/scope.cxx +++ b/libbuild2/scope.cxx @@ -23,7 +23,7 @@ namespace build2 ? empty_project_name : i->first); - os << (i != b ? " " : "") << n << '@' << i->second; + os << (i != b ? " " : "") << n << '@' << i->second.string (); } return os; diff --git a/libbuild2/scope.hxx b/libbuild2/scope.hxx index 75c0711..12fd22c 100644 --- a/libbuild2/scope.hxx +++ b/libbuild2/scope.hxx @@ -28,8 +28,12 @@ namespace build2 using subprojects = map; + // Print as name@dir sequence. + // + // Note: trailing slash is not printed for the directory path. + // LIBBUILD2_SYMEXPORT ostream& - operator<< (ostream&, const subprojects&); // Print as name@dir sequence. + operator<< (ostream&, const subprojects&); class LIBBUILD2_SYMEXPORT scope { diff --git a/libbuild2/script/builtin-options.hxx b/libbuild2/script/builtin-options.hxx index 9089d46..c7cebbc 100644 --- a/libbuild2/script/builtin-options.hxx +++ b/libbuild2/script/builtin-options.hxx @@ -12,8 +12,6 @@ // // End prologue. -#include - #include namespace build2 diff --git a/libbuild2/script/builtin.cli b/libbuild2/script/builtin.cli index 6f2143a..50dd3a0 100644 --- a/libbuild2/script/builtin.cli +++ b/libbuild2/script/builtin.cli @@ -1,8 +1,6 @@ // file : libbuild2/script/builtin.cli // license : MIT; see accompanying LICENSE file -include ; - include ; // Note that options in this file are undocumented because we generate neither diff --git a/libbuild2/target-state.hxx b/libbuild2/target-state.hxx index ea7015c..a6106f7 100644 --- a/libbuild2/target-state.hxx +++ b/libbuild2/target-state.hxx @@ -43,8 +43,14 @@ namespace build2 return l; } - LIBBUILD2_SYMEXPORT ostream& - operator<< (ostream&, target_state); // target.cxx + LIBBUILD2_SYMEXPORT string + to_string (target_state); // target.cxx + + inline ostream& + operator<< (ostream& o, target_state ts) + { + return o << to_string (ts); + } } #endif // LIBBUILD2_TARGET_STATE_HXX diff --git a/libbuild2/target.cxx b/libbuild2/target.cxx index c3c03d7..5fa3c37 100644 --- a/libbuild2/target.cxx +++ b/libbuild2/target.cxx @@ -79,10 +79,10 @@ namespace build2 "group" }; - ostream& - operator<< (ostream& os, target_state ts) + string + to_string (target_state ts) { - return os << target_state_[static_cast (ts)]; + return target_state_[static_cast (ts)]; } // target diff --git a/libbuild2/types-parsers.cxx b/libbuild2/types-parsers.cxx index 86ce219..7b4a65d 100644 --- a/libbuild2/types-parsers.cxx +++ b/libbuild2/types-parsers.cxx @@ -3,8 +3,6 @@ #include -#include // build2::build::cli namespace - namespace build2 { namespace build @@ -48,6 +46,24 @@ namespace build2 xs = true; parse_path (x, s); } + + void parser:: + parse (structured_result_format& x, bool& xs, scanner& s) + { + xs = true; + const char* o (s.next ()); + + if (!s.more ()) + throw missing_value (o); + + const string v (s.next ()); + if (v == "lines") + x = structured_result_format::lines; + else if (v == "json") + x = structured_result_format::json; + else + throw invalid_value (o, v); + } } } } diff --git a/libbuild2/types-parsers.hxx b/libbuild2/types-parsers.hxx index c64e0f6..aef00ca 100644 --- a/libbuild2/types-parsers.hxx +++ b/libbuild2/types-parsers.hxx @@ -9,7 +9,8 @@ #include -#include +#include // build2::build::cli namespace +#include namespace build2 { @@ -41,6 +42,19 @@ namespace build2 static void merge (dir_path& b, const dir_path& a) {b = a;} }; + + template <> + struct parser + { + static void + parse (structured_result_format&, bool&, scanner&); + + static void + merge (structured_result_format& b, const structured_result_format& a) + { + b = a; + } + }; } } } -- cgit v1.1