diff options
| -rw-r--r-- | doc/concepts/doc-strings.org | 34 | ||||
| -rw-r--r-- | src/buildtool/build_engine/base_maps/rule_map.cpp | 3 | ||||
| -rw-r--r-- | src/buildtool/main/main.cpp | 20 |
3 files changed, 54 insertions, 3 deletions
diff --git a/doc/concepts/doc-strings.org b/doc/concepts/doc-strings.org index 387749df..00ecea27 100644 --- a/doc/concepts/doc-strings.org +++ b/doc/concepts/doc-strings.org @@ -30,13 +30,21 @@ the empy array or the empty map is taken as default, respectively. Each rule is described as a JSON object with a fixed set of keys. So having fixed keys for documentation does not cause conflicts. -More precisely, the keys ~doc~, ~field doc~, and ~config_doc~ +More precisely, the keys ~doc~, ~field doc~, ~config_doc~, +~artifacts_doc~, ~runfiles_doc~, and ~provides_doc~ are reserved for documentation. Here, ~doc~ has to be a list of strings describing the rule in general. ~field doc~ has to be a map from (some of) the field names to an array of strings, containing additional information on that particular field. ~config_doc~ has to be a map from (some of) the config variables to an array of -strings describing the respective variable. +strings describing the respective variable. ~artifacts_doc~ is +an array of strings describing the artifacts produced by the rule. +~runfiles_doc~ is an array of strings describing the runfiles produced +by this rule. Finally, ~provides_doc~ is a map describing (some +of) the providers by that rule; as opposed to fields or config +variables there is no authoritative list of providers given elsewhere +in the rule, so it is up to the rule author to give an accurate +documentation on the provided data. *** Example @@ -78,6 +86,23 @@ strings describing the respective variable. , "to be used. The compiler is also used to launch the preprocessor." ] } + , "artifacts_doc": + ["The actual library (libname.a) staged in the specified directory"] + , "runfiles_doc": ["The public headers of this library"] + , "provides_doc": + { "compile-deps": + [ "Map of artifacts specifying any additional files that, besides the runfiles," + , "have to be present in compile actions of targets depending on this library" + ] + , "link-deps": + [ "Map of artifacts specifying any additional files that, besides the artifacts," + , "have to be present in a link actions of targets depending on this library" + ] + , "link-args": + [ "List of strings that have to be added to the command line for linking actions" + , "in targets depending on on this library" + ] + } , "expression": { ... } } } @@ -114,4 +139,7 @@ it fully, i.e., prints in human-readable form - the documentation for the rule - all the fields available for that rule together with - their type (~string_field~, ~target_field~, etc), and - - their documentation. + - their documentation, +- all the configuration variables of the rule with their + documentation (if given), and +- the documented providers. diff --git a/src/buildtool/build_engine/base_maps/rule_map.cpp b/src/buildtool/build_engine/base_maps/rule_map.cpp index 93924941..ad242550 100644 --- a/src/buildtool/build_engine/base_maps/rule_map.cpp +++ b/src/buildtool/build_engine/base_maps/rule_map.cpp @@ -13,6 +13,7 @@ namespace BuildMaps::Base { namespace { auto const kRuleFields = std::unordered_set<std::string>{"anonymous", + "artifacts_doc", "config_doc", "config_fields", "config_transitions", @@ -22,6 +23,8 @@ auto const kRuleFields = std::unordered_set<std::string>{"anonymous", "field_doc", "implicit", "imports", + "provides_doc", + "runfiles_doc", "string_fields", "tainted", "target_fields"}; diff --git a/src/buildtool/main/main.cpp b/src/buildtool/main/main.cpp index 7c0d69c0..687cc888 100644 --- a/src/buildtool/main/main.cpp +++ b/src/buildtool/main/main.cpp @@ -1163,6 +1163,26 @@ auto DescribeTarget(std::string const& main_repo, std::cout << " Variables taken from the configuration\n"; PrintFields(*config_vars, config_doc, " - ", " | "); } + std::cout << " Result\n"; + std::cout << " - Artifacts\n"; + auto artifacts_doc = rdesc.find("artifacts_doc"); + if (artifacts_doc != rdesc.end()) { + PrintDoc(*artifacts_doc, " | "); + } + std::cout << " - Runfiles\n"; + auto runfiles_doc = rdesc.find("runfiles_doc"); + if (runfiles_doc != rdesc.end()) { + PrintDoc(*runfiles_doc, " | "); + } + auto provides_doc = rdesc.find("provides_doc"); + if (provides_doc != rdesc.end()) { + std::cout << " - Documented providers\n"; + for (auto& el : provides_doc->items()) { + std::cout << " - " << el.key() << "\n"; + PrintDoc(el.value(), " | "); + } + } + std::cout << std::endl; return kExitSuccess; } |