From 23b54f3f6401d5b52bd903485985ad38e0c3fba7 Mon Sep 17 00:00:00 2001 From: Klaus Aehlig Date: Tue, 25 Jun 2024 11:11:17 +0200 Subject: describe: also describe "configure" targets in more detail Most built-in rules are just described by their name, assuming they are known to the user anyway. One exception, however, are "export" targets, as those serve as interfaces to (logical) repositories and hence is supposed to have a documentation of the target itself. Over time, however, "configure" targets have evolved to become internal interfaces (maybe even for an external target), e.g., to provide default values and hence make better use of the actual export target. Therefore it is desirable to provide a bit more information when asked to describe a "configure" target. - As "configure" targets have a fixed set of keys, adding a "doc" field is a conservative extension; this can be useful to give an overview what the target is about. - An important information of a "configure" target is the target that is configured. While this, in general, is an expression, in the typical cases, the description is very short (a literal target name, or a variable). So we can afford to show the definition. --- doc/concepts/doc-strings.md | 10 +++ .../build_engine/target_map/built_in_rules.cpp | 1 + src/buildtool/main/describe.cpp | 11 +++ test/end-to-end/cli/TARGETS | 7 ++ test/end-to-end/cli/describe.sh | 94 ++++++++++++++++++++++ 5 files changed, 123 insertions(+) create mode 100644 test/end-to-end/cli/describe.sh 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{"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 -- cgit v1.2.3