instrumentation: Rename queries field to options

Fixes: #26728

Help/command/cmake_instrumentation.rst

@@ -19,7 +19,7 @@ This allows for configuring instrumentation at the project-level.
     API_VERSION <version>
     DATA_VERSION <version>
     [HOOKS <hooks>...]
-    [QUERIES <queries>...]
+    [OPTIONS <options>...]
     [CALLBACK <callback>]
   )
 
@@ -28,7 +28,7 @@ only supported value for both fields is 1.  See :ref:`cmake-instrumentation API
 for details of the ``API_VERSION`` and :ref:`cmake-instrumentation Data v1` for details
 of the ``DATA_VERSION``.
 
-Each of the optional keywords ``HOOKS``, ``QUERIES``, and ``CALLBACK``
+Each of the optional keywords ``HOOKS``, ``OPTIONS``, and ``CALLBACK``
 correspond to one of the parameters to the :ref:`cmake-instrumentation v1 Query Files`.
 The ``CALLBACK`` keyword can be provided multiple times to create multiple callbacks.
 
@@ -48,7 +48,7 @@ equivalent JSON query file.
     API_VERSION 1
     DATA_VERSION 1
     HOOKS postGenerate preCMakeBuild postCMakeBuild
-    QUERIES staticSystemInformation dynamicSystemInformation
+    OPTIONS staticSystemInformation dynamicSystemInformation
     CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data.cmake
     CALLBACK ${CMAKE_COMMAND} -P /path/to/handle_data_2.cmake
   )
@@ -60,7 +60,7 @@ equivalent JSON query file.
     "hooks": [
       "postGenerate", "preCMakeBuild", "postCMakeBuild"
     ],
-    "queries": [
+    "options": [
       "staticSystemInformation", "dynamicSystemInformation"
     ],
     "callbacks": [

Help/manual/cmake-instrumentation.7.rst

@@ -192,7 +192,7 @@ key is required, but all other fields are optional.
   * ``postInstall``
   * ``postTest``
 
-``queries``
+``options``
   A list of strings specifying additional optional data to collect during
   instrumentation. Elements in this list should be one of the following:
 
@@ -209,10 +209,10 @@ key is required, but all other fields are optional.
 
 The ``callbacks`` listed will be invoked during the specified hooks
 *at a minimum*. When there are multiple query files, the ``callbacks``,
-``hooks`` and ``queries`` between them will be merged. Therefore, if any query
+``hooks`` and ``options`` between them will be merged. Therefore, if any query
 file includes any ``hooks``, every ``callback`` across all query files will be
 executed at every ``hook`` across all query files. Additionally, if any query
-file includes any optional ``queries``, the optional query data will be present
+file includes any optional ``options``, the optional query data will be present
 in all data files.
 
 Example:
@@ -229,7 +229,7 @@ Example:
       "postCMakeBuild",
       "postInstall"
     ],
-    "queries": [
+    "options": [
       "staticSystemInformation",
       "dynamicSystemInformation"
     ]

Source/cmInstrumentation.cxx

@@ -70,8 +70,8 @@ void cmInstrumentation::LoadQueries()
                                  .Uuid;
       if (envVal == uuid) {
         this->AddHook(cmInstrumentationQuery::Hook::PrepareForCDash);
-        this->AddQuery(
-          cmInstrumentationQuery::Query::DynamicSystemInformation);
+        this->AddOption(
+          cmInstrumentationQuery::Option::DynamicSystemInformation);
         this->cdashDir = cmStrCat(this->timingDirv1, "/cdash");
         cmSystemTools::MakeDirectory(this->cdashDir);
         cmSystemTools::MakeDirectory(cmStrCat(this->cdashDir, "/configure"));
@@ -159,7 +159,7 @@ bool cmInstrumentation::ReadJSONQueries(std::string const& directory)
 void cmInstrumentation::ReadJSONQuery(std::string const& file)
 {
   auto query = cmInstrumentationQuery();
-  query.ReadJSON(file, this->errorMsg, this->queries, this->hooks,
+  query.ReadJSON(file, this->errorMsg, this->options, this->hooks,
                  this->callbacks);
   if (!this->errorMsg.empty()) {
     cmSystemTools::Error(cmStrCat(
@@ -174,15 +174,15 @@ bool cmInstrumentation::HasErrors() const
 }
 
 void cmInstrumentation::WriteJSONQuery(
-  std::set<cmInstrumentationQuery::Query> const& queries_,
+  std::set<cmInstrumentationQuery::Option> const& options_,
   std::set<cmInstrumentationQuery::Hook> const& hooks_,
   std::vector<std::vector<std::string>> const& callbacks_)
 {
   Json::Value root;
   root["version"] = 1;
-  root["queries"] = Json::arrayValue;
-  for (auto const& query : queries_) {
-    root["queries"].append(cmInstrumentationQuery::QueryString[query]);
+  root["options"] = Json::arrayValue;
+  for (auto const& option : options_) {
+    root["options"].append(cmInstrumentationQuery::OptionString[option]);
   }
   root["hooks"] = Json::arrayValue;
   for (auto const& hook : hooks_) {
@@ -214,9 +214,9 @@ bool cmInstrumentation::HasQuery() const
   return this->hasQuery;
 }
 
-bool cmInstrumentation::HasQuery(cmInstrumentationQuery::Query query) const
+bool cmInstrumentation::HasOption(cmInstrumentationQuery::Option option) const
 {
-  return (this->queries.find(query) != this->queries.end());
+  return (this->options.find(option) != this->options.end());
 }
 
 bool cmInstrumentation::HasHook(cmInstrumentationQuery::Hook hook) const
@@ -281,7 +281,8 @@ int cmInstrumentation::CollectTimingData(cmInstrumentationQuery::Hook hook)
   index["dataDir"] = directory;
   index["buildDir"] = this->binaryDir;
   index["version"] = 1;
-  if (this->HasQuery(cmInstrumentationQuery::Query::StaticSystemInformation)) {
+  if (this->HasOption(
+        cmInstrumentationQuery::Option::StaticSystemInformation)) {
     this->InsertStaticSystemInformation(index);
   }
   for (auto const& file : files) {
@@ -427,8 +428,8 @@ std::string cmInstrumentation::InstrumentTest(
 
   // Post-Command
   this->InsertTimingData(root, steadyStart, systemStart);
-  if (this->HasQuery(
-        cmInstrumentationQuery::Query::DynamicSystemInformation)) {
+  if (this->HasOption(
+        cmInstrumentationQuery::Option::DynamicSystemInformation)) {
     this->InsertDynamicSystemInformation(root, "after");
   }
 
@@ -443,8 +444,8 @@ std::string cmInstrumentation::InstrumentTest(
 
 void cmInstrumentation::GetPreTestStats()
 {
-  if (this->HasQuery(
-        cmInstrumentationQuery::Query::DynamicSystemInformation)) {
+  if (this->HasOption(
+        cmInstrumentationQuery::Option::DynamicSystemInformation)) {
     this->InsertDynamicSystemInformation(this->preTestStats, "before");
   }
 }
@@ -452,8 +453,8 @@ void cmInstrumentation::GetPreTestStats()
 int cmInstrumentation::InstrumentCommand(
   std::string command_type, std::vector<std::string> const& command,
   std::function<int()> const& callback,
-  cm::optional<std::map<std::string, std::string>> options,
-  cm::optional<std::map<std::string, std::string>> arrayOptions,
+  cm::optional<std::map<std::string, std::string>> data,
+  cm::optional<std::map<std::string, std::string>> arrayData,
   LoadQueriesAfter reloadQueriesAfterCommand)
 {
 
@@ -478,8 +479,8 @@ int cmInstrumentation::InstrumentCommand(
   auto system_start = std::chrono::system_clock::now();
   double preConfigureMemory = 0;
   double preConfigureLoad = 0;
-  if (this->HasQuery(
-        cmInstrumentationQuery::Query::DynamicSystemInformation)) {
+  if (this->HasOption(
+        cmInstrumentationQuery::Option::DynamicSystemInformation)) {
     this->InsertDynamicSystemInformation(root, "before");
   } else if (reloadQueriesAfterCommand == LoadQueriesAfter::Yes) {
     this->GetDynamicSystemInformation(preConfigureMemory, preConfigureLoad);
@@ -495,8 +496,8 @@ int cmInstrumentation::InstrumentCommand(
     if (!this->HasQuery()) {
       return ret;
     }
-    if (this->HasQuery(
-          cmInstrumentationQuery::Query::DynamicSystemInformation)) {
+    if (this->HasOption(
+          cmInstrumentationQuery::Option::DynamicSystemInformation)) {
       root["dynamicSystemInformation"] = Json::objectValue;
       root["dynamicSystemInformation"]["beforeHostMemoryUsed"] =
         preConfigureMemory;
@@ -507,14 +508,14 @@ int cmInstrumentation::InstrumentCommand(
 
   // Post-Command
   this->InsertTimingData(root, steady_start, system_start);
-  if (this->HasQuery(
-        cmInstrumentationQuery::Query::DynamicSystemInformation)) {
+  if (this->HasOption(
+        cmInstrumentationQuery::Option::DynamicSystemInformation)) {
     this->InsertDynamicSystemInformation(root, "after");
   }
 
   // Gather additional data
-  if (options.has_value()) {
-    for (auto const& item : options.value()) {
+  if (data.has_value()) {
+    for (auto const& item : data.value()) {
       if (item.first == "role" && !item.second.empty()) {
         command_type = item.second;
       } else if (!item.second.empty()) {
@@ -529,8 +530,8 @@ int cmInstrumentation::InstrumentCommand(
     root["config"] = "";
   }
 
-  if (arrayOptions.has_value()) {
-    for (auto const& item : arrayOptions.value()) {
+  if (arrayData.has_value()) {
+    for (auto const& item : arrayData.value()) {
       if (item.first == "targetLabels" && command_type != "link") {
         continue;
       }
@@ -659,9 +660,9 @@ void cmInstrumentation::AddHook(cmInstrumentationQuery::Hook hook)
   this->hooks.insert(hook);
 }
 
-void cmInstrumentation::AddQuery(cmInstrumentationQuery::Query query)
+void cmInstrumentation::AddOption(cmInstrumentationQuery::Option option)
 {
-  this->queries.insert(query);
+  this->options.insert(option);
 }
 
 std::string const& cmInstrumentation::GetCDashDir()

Source/cmInstrumentation.h

@@ -49,12 +49,12 @@ public:
                              std::string config);
   void GetPreTestStats();
   bool HasQuery() const;
-  bool HasQuery(cmInstrumentationQuery::Query) const;
-  bool HasHook(cmInstrumentationQuery::Hook) const;
+  bool HasOption(cmInstrumentationQuery::Option option) const;
+  bool HasHook(cmInstrumentationQuery::Hook hook) const;
   bool HasPreOrPostBuildHook() const;
   bool ReadJSONQueries(std::string const& directory);
   void ReadJSONQuery(std::string const& file);
-  void WriteJSONQuery(std::set<cmInstrumentationQuery::Query> const& queries,
+  void WriteJSONQuery(std::set<cmInstrumentationQuery::Option> const& options,
                       std::set<cmInstrumentationQuery::Hook> const& hooks,
                       std::vector<std::vector<std::string>> const& callback);
   void ClearGeneratedQueries();
@@ -62,7 +62,7 @@ public:
   int SpawnBuildDaemon();
   int CollectTimingAfterBuild(int ppid);
   void AddHook(cmInstrumentationQuery::Hook hook);
-  void AddQuery(cmInstrumentationQuery::Query query);
+  void AddOption(cmInstrumentationQuery::Option option);
   bool HasErrors() const;
   std::string const& GetCDashDir();
 
@@ -87,7 +87,7 @@ private:
   std::string timingDirv1;
   std::string userTimingDirv1;
   std::string cdashDir;
-  std::set<cmInstrumentationQuery::Query> queries;
+  std::set<cmInstrumentationQuery::Option> options;
   std::set<cmInstrumentationQuery::Hook> hooks;
   std::vector<std::string> callbacks;
   std::vector<std::string> queryFiles;

Source/cmInstrumentationCommand.cxx

@@ -35,9 +35,9 @@ bool validateVersion(std::string const& key, std::string const& versionString,
   }
   version = std::atoi(versionString.c_str());
   if (version != 1) {
-    status.SetError(cmStrCat(
-      "QUERY subcommand given an unsupported ", key, " \"", versionString,
-      "\" (the only currently supported version is 1)."));
+    status.SetError(
+      cmStrCat("given an unsupported ", key, " \"", versionString,
+               "\" (the only currently supported version is 1)."));
     return false;
   }
   return true;
@@ -79,7 +79,7 @@ bool cmInstrumentationCommand(std::vector<std::string> const& args,
   {
     ArgumentParser::NonEmpty<std::string> ApiVersion;
     ArgumentParser::NonEmpty<std::string> DataVersion;
-    ArgumentParser::NonEmpty<std::vector<std::string>> Queries;
+    ArgumentParser::NonEmpty<std::vector<std::string>> Options;
     ArgumentParser::NonEmpty<std::vector<std::string>> Hooks;
     ArgumentParser::NonEmpty<std::vector<std::vector<std::string>>> Callbacks;
   };
@@ -87,7 +87,7 @@ bool cmInstrumentationCommand(std::vector<std::string> const& args,
   static auto const parser = cmArgumentParser<Arguments>{}
                                .Bind("API_VERSION"_s, &Arguments::ApiVersion)
                                .Bind("DATA_VERSION"_s, &Arguments::DataVersion)
-                               .Bind("QUERIES"_s, &Arguments::Queries)
+                               .Bind("OPTIONS"_s, &Arguments::Options)
                                .Bind("HOOKS"_s, &Arguments::Hooks)
                                .Bind("CALLBACK"_s, &Arguments::Callbacks);
 
@@ -111,17 +111,17 @@ bool cmInstrumentationCommand(std::vector<std::string> const& args,
     return false;
   }
 
-  std::set<cmInstrumentationQuery::Query> queries;
-  auto queryParser = EnumParser<cmInstrumentationQuery::Query>(
-    cmInstrumentationQuery::QueryString);
-  for (auto const& arg : arguments.Queries) {
-    cmInstrumentationQuery::Query query;
-    if (!queryParser(arg, query)) {
+  std::set<cmInstrumentationQuery::Option> options;
+  auto optionParser = EnumParser<cmInstrumentationQuery::Option>(
+    cmInstrumentationQuery::OptionString);
+  for (auto const& arg : arguments.Options) {
+    cmInstrumentationQuery::Option option;
+    if (!optionParser(arg, option)) {
       status.SetError(
-        cmStrCat("given invalid argument to QUERIES \"", arg, '"'));
+        cmStrCat("given invalid argument to OPTIONS \"", arg, '"'));
       return false;
     }
-    queries.insert(query);
+    options.insert(option);
   }
 
   std::set<cmInstrumentationQuery::Hook> hooks;
@@ -140,7 +140,7 @@ bool cmInstrumentationCommand(std::vector<std::string> const& args,
   status.GetMakefile()
     .GetCMakeInstance()
     ->GetInstrumentation()
-    ->WriteJSONQuery(queries, hooks, arguments.Callbacks);
+    ->WriteJSONQuery(options, hooks, arguments.Callbacks);
 
   return true;
 }

Source/cmInstrumentationQuery.cxx

@@ -15,7 +15,7 @@
 #include "cmJSONHelpers.h"
 #include "cmStringAlgorithms.h"
 
-std::vector<std::string> const cmInstrumentationQuery::QueryString{
+std::vector<std::string> const cmInstrumentationQuery::OptionString{
   "staticSystemInformation", "dynamicSystemInformation"
 };
 std::vector<std::string> const cmInstrumentationQuery::HookString{
@@ -64,11 +64,11 @@ static std::function<bool(E&, Json::Value const*, cmJSONState*)> EnumHelper(
     return false;
   };
 }
-static auto const QueryHelper = EnumHelper<cmInstrumentationQuery::Query>(
-  cmInstrumentationQuery::QueryString, "query");
+static auto const OptionHelper = EnumHelper<cmInstrumentationQuery::Option>(
+  cmInstrumentationQuery::OptionString, "option");
 static auto const QueryListHelper =
-  JSONHelperBuilder::Vector<cmInstrumentationQuery::Query>(
-    ErrorMessages::InvalidArray, QueryHelper);
+  JSONHelperBuilder::Vector<cmInstrumentationQuery::Option>(
+    ErrorMessages::InvalidArray, OptionHelper);
 static auto const HookHelper = EnumHelper<cmInstrumentationQuery::Hook>(
   cmInstrumentationQuery::HookString, "hook");
 static auto const HookListHelper =
@@ -85,13 +85,13 @@ static auto const QueryRootHelper =
   JSONHelperBuilder::Object<QueryRoot>(ErrorMessages::InvalidRootQueryObject,
                                        false)
     .Bind("version"_s, &QueryRoot::version, VersionHelper, true)
-    .Bind("queries"_s, &QueryRoot::queries, QueryListHelper, false)
+    .Bind("options"_s, &QueryRoot::options, QueryListHelper, false)
     .Bind("hooks"_s, &QueryRoot::hooks, HookListHelper, false)
     .Bind("callbacks"_s, &QueryRoot::callbacks, CallbackListHelper, false);
 
 bool cmInstrumentationQuery::ReadJSON(std::string const& filename,
                                       std::string& errorMessage,
-                                      std::set<Query>& queries,
+                                      std::set<Option>& options,
                                       std::set<Hook>& hooks,
                                       std::vector<std::string>& callbacks)
 {
@@ -105,8 +105,8 @@ bool cmInstrumentationQuery::ReadJSON(std::string const& filename,
     errorMessage = this->parseState.GetErrorMessage(true);
     return false;
   }
-  std::move(this->queryRoot.queries.begin(), this->queryRoot.queries.end(),
-            std::inserter(queries, queries.end()));
+  std::move(this->queryRoot.options.begin(), this->queryRoot.options.end(),
+            std::inserter(options, options.end()));
   std::move(this->queryRoot.hooks.begin(), this->queryRoot.hooks.end(),
             std::inserter(hooks, hooks.end()));
   std::move(this->queryRoot.callbacks.begin(), this->queryRoot.callbacks.end(),

Source/cmInstrumentationQuery.h

@@ -12,12 +12,12 @@ class cmInstrumentationQuery
 {
 
 public:
-  enum Query
+  enum Option
   {
     StaticSystemInformation,
     DynamicSystemInformation
   };
-  static std::vector<std::string> const QueryString;
+  static std::vector<std::string> const OptionString;
 
   enum Hook
   {
@@ -35,7 +35,7 @@ public:
 
   struct QueryJSONRoot
   {
-    std::vector<cmInstrumentationQuery::Query> queries;
+    std::vector<cmInstrumentationQuery::Option> options;
     std::vector<cmInstrumentationQuery::Hook> hooks;
     std::vector<std::string> callbacks;
     int version;
@@ -43,7 +43,7 @@ public:
 
   cmInstrumentationQuery() = default;
   bool ReadJSON(std::string const& file, std::string& errorMessage,
-                std::set<Query>& queries, std::set<Hook>& hooks,
+                std::set<Option>& options, std::set<Hook>& hooks,
                 std::vector<std::string>& callbacks);
   QueryJSONRoot queryRoot;
   cmJSONState parseState;

Tests/RunCMake/Instrumentation/RunCMakeTest.cmake

@@ -90,7 +90,7 @@ function(instrument test)
 endfunction()
 
 # Bad Queries
-instrument(bad-query)
+instrument(bad-option)
 instrument(bad-hook)
 instrument(empty)
 instrument(bad-version)
@@ -100,7 +100,7 @@ instrument(hooks-1 BUILD INSTALL TEST STATIC_QUERY)
 instrument(hooks-2 BUILD INSTALL TEST)
 instrument(hooks-no-callbacks MANUAL_HOOK)
 
-# Check data file contents
+# Check data file contents for optional query data
 instrument(no-query BUILD INSTALL TEST
   CHECK_SCRIPT check-data-dir.cmake)
 instrument(dynamic-query BUILD INSTALL TEST DYNAMIC_QUERY

Tests/RunCMake/Instrumentation/bad-option-stderr.txt

@@ -0,0 +1,5 @@
+^CMake Error: Could not load instrumentation queries from [^
+]+:
+bad-option.json:[0-9]+: Not a valid option: "bad option"
+  "options": \["staticSystemInformation", "bad option"\]
+                                         \^$

Tests/RunCMake/Instrumentation/bad-query-stderr.txt

@@ -1,5 +0,0 @@
-^CMake Error: Could not load instrumentation queries from [^
-]+:
-bad-query.json:[0-9]+: Not a valid query: "bad query"
-  "queries": \["staticSystemInformation", "bad query"\]
-                                         \^$

Tests/RunCMake/Instrumentation/cmake-command-bad-api-version-stderr.txt

@@ -1,6 +1,6 @@
 CMake Error at [^
 ]*\(cmake_instrumentation\):
-  cmake_instrumentation QUERY subcommand given an unsupported API_VERSION "0"
-  \(the only currently supported version is 1\).
+  cmake_instrumentation given an unsupported API_VERSION "0" \(the only
+  currently supported version is 1\).
 Call Stack \(most recent call first\):
   CMakeLists.txt:6 \(include\)

Tests/RunCMake/Instrumentation/cmake-command-missing-version-stderr.txt

@@ -1,6 +1,6 @@
 CMake Error at [^
 ]*\(cmake_instrumentation\):
-  cmake_instrumentation QUERY subcommand given an unsupported DATA_VERSION ""
-  \(the only currently supported version is 1\).
+  cmake_instrumentation given an unsupported DATA_VERSION "" \(the only
+  currently supported version is 1\).
 Call Stack \(most recent call first\):
   CMakeLists.txt:6 \(include\)

Tests/RunCMake/Instrumentation/query/bad-option.json.in

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "options": ["staticSystemInformation", "bad option"]
+}

Tests/RunCMake/Instrumentation/query/bad-query.json.in

@@ -1,4 +0,0 @@
-{
-  "version": 1,
-  "queries": ["staticSystemInformation", "bad query"]
-}

Tests/RunCMake/Instrumentation/query/both-query.json.in

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "queries": [
+  "options": [
     "staticSystemInformation",
     "dynamicSystemInformation"
   ]

Tests/RunCMake/Instrumentation/query/cmake-command-data.cmake

@@ -1,5 +1,5 @@
 cmake_instrumentation(
   API_VERSION 1
   DATA_VERSION 1
-  QUERIES dynamicSystemInformation
+  OPTIONS dynamicSystemInformation
 )

Tests/RunCMake/Instrumentation/query/cmake-command-parallel-install.cmake

@@ -2,5 +2,5 @@ set_property(GLOBAL PROPERTY INSTALL_PARALLEL ON)
 cmake_instrumentation(
   API_VERSION 1
   DATA_VERSION 1
-  QUERIES dynamicSystemInformation
+  OPTIONS dynamicSystemInformation
 )

Tests/RunCMake/Instrumentation/query/cmake-command.cmake

@@ -15,7 +15,7 @@
     API_VERSION 1
     DATA_VERSION 1
     HOOKS postCMakeBuild
-    QUERIES staticSystemInformation dynamicSystemInformation
+    OPTIONS staticSystemInformation dynamicSystemInformation
     CALLBACK ${CMAKE_COMMAND} -E echo callback2
     CALLBACK ${CMAKE_COMMAND} -E echo callback3
   )

Tests/RunCMake/Instrumentation/query/dynamic-query.json.in

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "queries": [
+  "options": [
     "staticSystemInformation",
     "dynamicSystemInformation"
   ]

Tests/RunCMake/Instrumentation/query/generated/query-0.json.in

@@ -1,6 +1,6 @@
 {
   "callbacks" : [],
   "hooks" : [],
-  "queries" : [],
+  "options" : [],
   "version": 1
 }

Tests/RunCMake/Instrumentation/query/generated/query-1.json.in

@@ -7,6 +7,6 @@
   [
     "postGenerate"
   ],
-  "queries" : [],
+  "options" : [],
   "version" : 1
 }

Tests/RunCMake/Instrumentation/query/generated/query-2.json.in

@@ -8,7 +8,7 @@
   [
     "postCMakeBuild"
   ],
-  "queries" :
+  "options" :
   [
     "staticSystemInformation",
     "dynamicSystemInformation"

Tests/RunCMake/Instrumentation/query/hooks-1.json.in

@@ -2,5 +2,5 @@
   "version": 1,
   "hooks": ["preCMakeBuild", "postInstall"],
   "callbacks": ["@GET_HOOK@"],
-  "queries": ["staticSystemInformation"]
+  "options": ["staticSystemInformation"]
 }