diff options
| -rw-r--r-- | doc/concepts/doc-strings.md | 10 | ||||
| -rw-r--r-- | src/buildtool/build_engine/target_map/built_in_rules.cpp | 1 | ||||
| -rw-r--r-- | src/buildtool/main/describe.cpp | 11 | ||||
| -rw-r--r-- | test/end-to-end/cli/TARGETS | 7 | ||||
| -rw-r--r-- | test/end-to-end/cli/describe.sh | 94 |
5 files changed, 123 insertions, 0 deletions
diff --git a/doc/concepts/doc-strings.md b/doc/concepts/doc-strings.md index ed4ee84b..22115cee 100644 --- a/doc/concepts/doc-strings.md +++ b/doc/concepts/doc-strings.md @@ -131,6 +131,16 @@ strings describing the targeted in general and `"config_doc"` is a map from (some of) the variables of the `"flexible_config"` to an array of strings describing this parameter. +Configure targets +----------------- + +As configure targets often serve as internal interface to external +export targets (e.g., in order to set a needed configuration), we +support documentation here as well. As configure targets, being +built-in, have a fixed set of fields, a `"doc"` field can be used +for this purpose without conflicts. Again, the `"doc"` field is an +array of strings describing the target in general. + Presentation of the documentation --------------------------------- diff --git a/src/buildtool/build_engine/target_map/built_in_rules.cpp b/src/buildtool/build_engine/target_map/built_in_rules.cpp index 7d858840..81f679e5 100644 --- a/src/buildtool/build_engine/target_map/built_in_rules.cpp +++ b/src/buildtool/build_engine/target_map/built_in_rules.cpp @@ -76,6 +76,7 @@ auto const kInstallRuleFields = auto const kConfigureRuleFields = std::unordered_set<std::string>{"arguments_config", "config", + "doc", "tainted", "target", "type"}; diff --git a/src/buildtool/main/describe.cpp b/src/buildtool/main/describe.cpp index 4739ba88..e3ab1223 100644 --- a/src/buildtool/main/describe.cpp +++ b/src/buildtool/main/describe.cpp @@ -431,6 +431,17 @@ auto DescribeTarget(BuildMaps::Target::ConfiguredTarget const& id, PrintFields(*flexible_config, config_doc, " - ", " | "); } } + else if (*rule_it == "configure") { + auto target = desc.find("target"); + auto doc = desc.find("doc"); + if (doc != desc.end()) { + PrintDoc(*doc, " | "); + } + if (target != desc.end()) { + std::cout << "The target to be configured is defined as " + << target->dump() << "." << std::endl; + } + } return kExitSuccess; } auto rule_name = BuildMaps::Base::ParseEntityNameFromJson( diff --git a/test/end-to-end/cli/TARGETS b/test/end-to-end/cli/TARGETS index 03f1db49..f7237f28 100644 --- a/test/end-to-end/cli/TARGETS +++ b/test/end-to-end/cli/TARGETS @@ -60,6 +60,12 @@ , "test": ["log-limit.sh"] , "deps": [["", "tool-under-test"], ["", "mr-tool-under-test"]] } +, "describe": + { "type": ["@", "rules", "shell/test", "script"] + , "name": ["describe"] + , "test": ["describe.sh"] + , "deps": [["", "tool-under-test"]] + } , "TESTS": { "type": "install" , "tainted": ["test"] @@ -75,6 +81,7 @@ , "git cas -P" , "install --archive" , "conflict report" + , "describe" ] , { "type": "if" , "cond": {"type": "var", "name": "TEST_BOOTSTRAP_JUST_MR"} diff --git a/test/end-to-end/cli/describe.sh b/test/end-to-end/cli/describe.sh new file mode 100644 index 00000000..378ee4d2 --- /dev/null +++ b/test/end-to-end/cli/describe.sh @@ -0,0 +1,94 @@ +#!/bin/sh +# Copyright 2024 Huawei Cloud Computing Technology Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -eu + +ROOT="$(pwd)" +JUST="${ROOT}/bin/tool-under-test" +LBR="${TEST_TMPDIR}/build-root" +OUT="${TEST_TMPDIR}/output" + +mkdir work +cd work +touch ROOT + +cat > TARGETS <<'EOF' +{ "payload": + { "type": "file_gen" + , "arguments_config": ["NAME"] + , "name": "greeting.txt" + , "data": + {"type": "join", "$1": ["Hello ", {"type": "var", "name": "NAME"}, "!"]} + } +, "exported-target": + { "type": "export" + , "doc": ["Here we export the canonical GREETING text"] + , "target": "payload" + , "flexible_config": ["NAME"] + , "config_doc": {"NAME": ["The RECIPIENT of the greeting"]} + } +, "": + { "type": "configure" + , "doc": ["Configure the canonical greeting to set a DEFAULT name"] + , "arguments_config": ["NAME"] + , "target": "exported-target" + , "config": + { "type": "singleton_map" + , "key": "NAME" + , "value": {"type": "var", "name": "NAME", "default": "world"} + } + } +} +EOF + +# Sanity check: the target description actually works +"${JUST}" install --local-build-root "${LBR}" -o "${OUT}" 2>&1 +grep 'Hello world' "${OUT}/greeting.txt" + +# Verify the description of the export target +"${JUST}" describe --local-build-root "${LBR}" exported-target \ + > "${OUT}/export.doc" 2> "${OUT}/log" +echo +cat "${OUT}/log" +echo +cat "${OUT}/export.doc" +echo +echo +# - rule name +grep '"export"' "${OUT}/export.doc" +# - top-level description +grep GREETING "${OUT}/export.doc" +# - flexible config +grep NAME "${OUT}/export.doc" +# - documentation of variable +grep RECIPIENT "${OUT}/export.doc" + +# Verify the description of the configure target +"${JUST}" describe --local-build-root "${LBR}" \ + > "${OUT}/configure.doc" 2> "${OUT}/log" +echo +cat "${OUT}/log" +echo +cat "${OUT}/configure.doc" +echo +echo +# - rule name +grep '"configure"' "${OUT}/configure.doc" +# - top-level description +grep DEFAULT "${OUT}/configure.doc" +# - the expression defining what to configure +grep '"exported-target"' "${OUT}/configure.doc" + +echo OK |