[projmgr] Add list examples command

Author: grasci-arm

test/packs/ARM/RteTest/0.1.0/ARM.RteTest.pdsc

@@ -418,6 +418,8 @@
       </project>
       <attributes>
         <component Cclass="RteTest" Cgroup="GlobalLevel"/>
+        <category>Example Project</category>
+        <keyword>Getting Started</keyword>
       </attributes>
     </example>
   </examples>

tools/projmgr/include/ProjMgr.h

@@ -192,6 +192,7 @@ class ProjMgr {
   bool RunListComponents();
   bool RunListConfigs();
   bool RunListDependencies();
+  bool RunListExamples();
   bool RunListContexts();
   bool RunListTargetSets();
   bool RunListGenerators();

tools/projmgr/include/ProjMgrWorker.h

@@ -279,6 +279,42 @@ struct GdbServerItem {
   std::string pname;
 };
 
+/**
+ * @brief example environment item containing
+ *        project file with extension
+ *        subdirectory to be copied
+*/
+struct EnvironmentItem {
+  std::string load;
+  std::string folder;
+};
+
+/**
+ * @brief example item containing
+ *        name of example
+ *        description
+ *        documentation
+ *        version
+ *        archive
+ *        map of environments
+ *        list of compatible boards
+ *        list of components
+ *        list of categories
+ *        list of keywords
+*/
+struct ExampleItem {
+  std::string name;
+  std::string description;
+  std::string doc;
+  std::string version;
+  std::string archive;
+  std::map<std::string, EnvironmentItem> environments;
+  std::vector<BoardItem> boards;
+  std::vector<std::string> components;
+  std::vector<std::string> categories;
+  std::vector<std::string> keywords;
+};
+
 /**
  * @brief debugger type
  *        name of debug configuration
@@ -545,6 +581,14 @@ class ProjMgrWorker {
   */
   bool ListDependencies(std::vector<std::string>& dependencies, const std::string& filter = RteUtils::EMPTY_STRING);
 
+  /**
+   * @brief list available examples
+   * @param reference to list of examples
+   * @param filter words to filter results
+   * @return true if executed successfully
+  */
+  bool ListExamples(std::vector<std::string>& examples, const std::string& filter = RteUtils::EMPTY_STRING);
+
   /**
    * @brief list contexts
    * @param reference to list of contexts
@@ -1099,6 +1143,9 @@ class ProjMgrWorker {
   bool IsCreatedByExecute(const std::string file, const std::string dir);
   bool CollectAllRequiredPdscFiles();
   bool ParseTargetSetContextSelection();
+  std::vector<ExampleItem> CollectExamples(ContextItem& context);
+  std::vector<RteBoard*> GetCompatibleBoards(ContextItem& context);
+  bool IsBoardListCompatible(const std::vector<RteBoard*> compatibleBoards, const Collection<RteItem*>& boards);
 };
 
 #endif  // PROJMGRWORKER_H

tools/projmgr/src/ProjMgr.cpp

@@ -30,6 +30,7 @@ Commands:\n\
   list dependencies             Print list of unresolved project dependencies\n\
   list devices                  Print list of available device names\n\
   list environment              Print list of environment configurations\n\
+  list examples                 Print list of examples\n\
   list generators               Print list of code generators of a given context\n\
   list layers                   Print list of available, referenced and compatible layers\n\
   list packs                    Print list of used packs from the pack repository\n\
@@ -181,6 +182,7 @@ int ProjMgr::ParseCommandLine(int argc, char** argv) {
     {"list configs",      { false, {context, contextSet, activeTargetSet, debug, filter, load, quiet, schemaCheck, toolchain, verbose}}},
     {"list components",   { true,  {context, contextSet, activeTargetSet, debug, filter, load, quiet, schemaCheck, toolchain, verbose}}},
     {"list dependencies", { false, {context, contextSet, activeTargetSet, debug, filter, load, quiet, schemaCheck, toolchain, verbose}}},
+    {"list examples",     { false, {context, contextSet, activeTargetSet, debug, filter, load, quiet, schemaCheck, toolchain, verbose}}},
     {"list contexts",     { false, {debug, filter, quiet, schemaCheck, verbose, ymlOrder}}},
     {"list target-sets",  { false, {debug, filter, quiet, schemaCheck, verbose}}},
     {"list generators",   { false, {context, contextSet, activeTargetSet, debug, load, quiet, schemaCheck, toolchain, verbose}}},
@@ -370,6 +372,10 @@ int ProjMgr::ProcessCommands() {
       if (!RunListDependencies()) {
         return ErrorCode::ERROR;
       }
+    } else if (m_args == "examples") {
+      if (!RunListExamples()) {
+        return ErrorCode::ERROR;
+      }
     } else if (m_args == "contexts") {
       if (!RunListContexts()) {
         return ErrorCode::ERROR;
@@ -907,6 +913,31 @@ bool ProjMgr::RunListDependencies(void) {
   return true;
 }
 
+bool ProjMgr::RunListExamples(void) {
+  if (!m_csolutionFile.empty()) {
+    // Parse all input files and create contexts
+    if (!PopulateContexts()) {
+      return false;
+    }
+  }
+
+  // Parse context selection
+  if (!ParseAndValidateContexts()) {
+    return false;
+  }
+
+  vector<string> examples;
+  if (!m_worker.ListExamples(examples, m_filter)) {
+    ProjMgrLogger::Get().Error("processing examples list failed");
+    return false;
+  }
+
+  for (const auto& example : examples) {
+    ProjMgrLogger::out() << example << endl;
+  }
+  return true;
+}
+
 bool ProjMgr::RunListContexts(void) {
   // Parse all input files and create contexts
   if (!PopulateContexts()) {

tools/projmgr/src/ProjMgrWorker.cpp

@@ -4187,6 +4187,167 @@ bool ProjMgrWorker::ListDependencies(vector<string>& dependencies, const string&
   return true;
 }
 
+vector<RteBoard*> ProjMgrWorker::GetCompatibleBoards(ContextItem& context) {
+  vector<RteBoard*> compatibleBoards;
+  if (!context.board.empty()) {
+    compatibleBoards.push_back(context.rteBoard);
+  } else if (!context.device.empty()) {
+    context.rteFilteredModel->GetCompatibleBoards(compatibleBoards, context.rteDevice);
+  }
+  return compatibleBoards;
+}
+
+bool ProjMgrWorker::IsBoardListCompatible(const vector<RteBoard*> compatibleBoards, const Collection<RteItem*>& boards) {
+  if (boards.empty() || compatibleBoards.empty()) {
+    return true;
+  }
+  for (const auto& board : boards) {
+    for (const auto& compatibleBoard : compatibleBoards) {
+      if ((compatibleBoard->GetVendorString() == board->GetVendorString()) &&
+        (compatibleBoard->GetName() == board->GetName())) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+std::vector<ExampleItem> ProjMgrWorker::CollectExamples(ContextItem& context) {
+  std::vector<ExampleItem> examples;
+  vector<const RteItem*> rteExamples;
+  const auto& packs = context.rteFilteredModel->GetPackages();
+  for (const auto& [_, pack] : packs) {
+    const RteItem* packExamples = pack->GetExamples();
+    if (packExamples) {
+      const Collection<RteItem*> items = packExamples->GetChildren();
+      for (const RteItem* item : items) {
+        if (item->GetTag() == "example") {
+          rteExamples.push_back(item);
+        }
+      }
+    }
+  }
+  const auto& compatibleBoards = GetCompatibleBoards(context);
+  for (const auto& rteExample : rteExamples) {
+    Collection<RteItem*> boards;
+    boards = rteExample->GetChildrenByTag("board", boards);
+    if (!IsBoardListCompatible(compatibleBoards, boards)) {
+      continue;
+    }
+    ExampleItem example;
+    example.name = rteExample->GetName();
+    example.description = rteExample->GetChildText("description");    
+    string folder = rteExample->GetFolderString();
+    RteFsUtils::NormalizePath(folder, rteExample->GetAbsolutePackagePath());
+    example.doc = rteExample->GetDocValue();
+    RteFsUtils::NormalizePath(example.doc, folder);
+    string archive = rteExample->GetAttribute("archive");
+    if (!archive.empty()) {
+      RteFsUtils::NormalizePath(archive, folder);
+      example.archive = archive;
+    }
+    for (const auto& board : boards) {
+      example.boards.push_back(BoardItem{ board->GetVendorString(), board->GetName() });
+    }
+    const auto& version = rteExample->GetVersionString();
+    if (!version.empty()) {
+      example.version = version;
+    }
+
+    Collection<RteItem*> environments;
+    environments = rteExample->GetChildrenByTag("environment", environments);
+    for (const auto& item : environments) {
+      string load = item->GetAttribute("load");
+      RteFsUtils::NormalizePath(load, folder);
+      const auto& name = item->GetName();
+      example.environments[name].load = load;
+      example.environments[name].folder = item->GetFolderString();
+      RteFsUtils::NormalizePath(example.environments[name].folder, folder);
+    }
+
+    Collection<RteItem*> components;
+    components = rteExample->GetChildrenByTag("component", components);
+    for (const auto& item : components) {
+      example.components.push_back(item->GetComponentID(true));
+    }
+
+    Collection<RteItem*> categories;
+    categories = rteExample->GetChildrenByTag("category", categories);
+    for (const auto& item : categories) {
+      example.categories.push_back(item->GetText());
+    }
+
+    Collection<RteItem*> keywords;
+    components = rteExample->GetChildrenByTag("keyword", keywords);
+    for (const auto& item : keywords) {
+      example.keywords.push_back(item->GetText());
+    }
+
+    examples.push_back(example);
+  } 
+  return examples;
+}
+
+bool ProjMgrWorker::ListExamples(vector<string>& examples, const string& filter) {
+  const auto& selectedContext = m_selectedContexts.front();
+  ContextItem& context = m_contexts[selectedContext];
+  if (!LoadPacks(context)) {
+    return false;
+  }
+  if (!selectedContext.empty()) {
+    if (!ProcessPrecedences(context, BoardOrDevice::Both)) {
+      return false;
+    }
+  }
+  if (!SetTargetAttributes(context, context.targetAttributes)) {
+    return false;
+  }
+
+  const auto& collectedExamples = CollectExamples(context);
+
+  for (const auto& exampleItem : collectedExamples) {
+    string example = exampleItem.name;
+    example += exampleItem.version.empty() ? "" : "@" + exampleItem.version;
+    example += "\n  description: " + exampleItem.description;
+    example += "\n  doc: " + exampleItem.doc;
+    if (!exampleItem.archive.empty()) {
+      example += "\n  archive: " + exampleItem.archive;
+    }
+    for (const auto& [name, environment] : exampleItem.environments) {
+      example += "\n  environment: " + name + "\n    load: " + environment.load;
+      example += "\n    folder: " + environment.folder;
+    }
+    if (!exampleItem.boards.empty()) {
+      example += "\n  boards:";
+      for (const auto& board : exampleItem.boards) {
+        example += "\n    " + board.vendor + "::" + board.name;
+      }
+    }
+    if (!exampleItem.components.empty()) {
+      example += "\n  components:";
+      for (const auto& component : exampleItem.components) {
+        example += "\n    " + component;
+      }
+    }
+    if (!exampleItem.categories.empty()) {
+      example += "\n  categories:";
+      for (const auto& category : exampleItem.categories) {
+        example += "\n    " + category;
+      }
+    }
+    if (!exampleItem.keywords.empty()) {
+      example += "\n  keywords:";
+      for (const auto& keyword : exampleItem.keywords) {
+        example += "\n    " + keyword;
+      }
+    }
+    if (filter.empty() || example.find(filter) != string::npos) {
+      examples.push_back(example);
+    }
+  }
+  return true;
+}
+
 bool ProjMgrWorker::FormatValidationResults(set<string>& results, const ContextItem& context) {
   for (const auto& validation : context.validationResults) {
     string resultStr = RteItem::ConditionResultToString(validation.result) + " " + validation.id;

tools/projmgr/test/data/Examples/project.cproject.yml

@@ -0,0 +1,7 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Open-CMSIS-Pack/devtools/main/tools/projmgr/schemas/cproject.schema.json
+
+project:
+
+  components:
+    - component: Startup
+    - component: CORE

tools/projmgr/test/data/Examples/solution.csolution.yml

@@ -0,0 +1,33 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/Open-CMSIS-Pack/devtools/main/tools/projmgr/schemas/csolution.schema.json
+
+solution:
+
+  packs:
+    - pack: ARM::RteTest_DFP
+    - pack: ARM::RteTest
+
+  compiler: AC6
+
+  target-types:
+    - type: TestBoard
+      board: RteTest Dummy board
+      device: :cm0_core0
+      target-set:
+        - set:
+          images:
+            - project-context: project
+    - type: CM0_Dual
+      device: RteTest_ARMCM0_Dual:cm0_core0
+      target-set:
+        - set:
+          images:
+            - project-context: project
+    - type: CM0
+      device: RteTest_ARMCM0
+      target-set:
+        - set:
+          images:
+            - project-context: project
+
+  projects:
+    - project: project.cproject.yml