Prepare CaGe to be extensible via plugins (tudasc#129)

* Prepare CaGe to be extensible via plugins
* Move Plugin interface to dedicated interface include directory
* add interface library for client tools to link against
* Fix bug when creating unique pointer from loaded plugin

Author: TimHeldmann

tools/cage/include/cage/Plugin.h tools/cage/include/cage/CaGe.htools/cage/include/cage/Plugin.h renamed to tools/cage/include/cage/CaGe.h

@@ -3,7 +3,7 @@
  * License: Part of the MetaCG project. Licensed under BSD 3 clause license. See LICENSE.txt file at
  * https://github.com/tudasc/metacg/LICENSE.txt
  */
-#include "cage/generator/CallGraphConsumer.h"
+#include "../interface/CaGePlugin.h"
 
 #include "io/MCGWriter.h"
 
@@ -18,13 +18,13 @@ class Generator {
  public:
   explicit Generator(PTAType ptaType) : ptaType(ptaType) {};
 
-  void addConsumer(std::unique_ptr<CallGraphConsumer> consumer) { consumers.push_back(std::move(consumer)); }
+  void addPlugin(std::unique_ptr<Plugin> consumer) { plugins.push_back(std::move(consumer)); }
 
   bool run(llvm::Module& M, llvm::ModuleAnalysisManager* MA);
 
  private:
   PTAType ptaType;
-  std::vector<std::unique_ptr<CallGraphConsumer>> consumers;
+  std::vector<std::unique_ptr<Plugin>> plugins;
 };
 
 }  // namespace cage

tools/cage/include/cage/generator/CallGraphConsumer.h

@@ -6,16 +6,16 @@
 #ifndef METACG_FILEEXPORTER_H
 #define METACG_FILEEXPORTER_H
 
-#include "cage/generator/CallGraphConsumer.h"
+#include "cage/interface/CaGePlugin.h"
 
 #include <string>
 
 namespace cage {
 
-class FileExporter : public CallGraphConsumer {
+class FileExporter : public Plugin {
  public:
-  FileExporter(std::string outfile) : outfile(outfile) {}
-  void consumeCallGraph(metacg::Callgraph&) override;
+  FileExporter(const std::string& outfile) : outfile(outfile) {}
+  void consumeCallGraph(const metacg::Callgraph&) override;
 
  private:
   std::string outfile;

tools/cage/include/cage/generator/CallgraphGenerator.h

@@ -0,0 +1,51 @@
+/**
+ * File: CallGraphConsumer.h
+ * License: Part of the MetaCG project. Licensed under BSD 3 clause license. See LICENSE.txt file at
+ * https://github.com/tudasc/metacg/LICENSE.txt
+ */
+#ifndef METACG_CAGEPLUGIN_H
+#define METACG_CAGEPLUGIN_H
+
+#include <string> //can not predeclare std::string
+
+namespace metacg {
+class Callgraph;
+class Metadata;
+}
+
+namespace llvm {
+class Module;
+}
+
+namespace cage {
+
+struct Plugin {
+  virtual ~Plugin() = default;
+  /**
+   * Overwrite if you need to modify the graph, e.g. adding nodes, edges or metadata, based on the LLVM Module
+   * This will be called before any consumers can consume the graph
+   * For multiple plugins, invocations of this function are executed in the order the plugins were registered
+   * @param m the full LLVM::Module as available to the pass
+   * @param cg the metacg callgraph to be modified
+   * @return void
+   */
+  virtual void augmentCallGraph(const llvm::Module& m, metacg::Callgraph& cg) {}
+
+  /**
+   * Overwrite this if you only need to read from the graph, e.g. converting to different formats, or graph analysis
+   * @param cg the metacg callgraph to be read from
+   */
+  virtual void consumeCallGraph(const metacg::Callgraph& cg){};
+
+  /**
+   * Overwrite this if you want your Plugin to be listed with a name in the debug logs
+   * @return the logging name of your plugin
+   */
+  [[nodiscard]] virtual std::string getPluginName() const { return "unnamed Plugin"; }
+};
+
+}  // namespace cage
+
+
+
+#endif  // METACG_CAGEPLUGIN_H

tools/cage/include/cage/generator/FileExporter.h

@@ -1,7 +1,13 @@
 include(AddLLVM)
 
-add_llvm_pass_plugin(cage-plugin Plugin.cpp)
+add_llvm_pass_plugin(cage-plugin CaGe.cpp)
 target_include_directories(cage-plugin PRIVATE $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/tools/cage/include>)
 target_link_libraries(cage-plugin PRIVATE cage)
 
+add_library(cage-plugin-interface INTERFACE)
+target_include_directories(
+  cage-plugin-interface INTERFACE $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/tools/cage/include/cage/interface>
+)
+target_link_libraries(cage-plugin-interface INTERFACE metacg::metacg)
+
 add_subdirectory(generator)

tools/cage/include/cage/interface/CaGePlugin.h

@@ -3,11 +3,12 @@
  * License: Part of the MetaCG project. Licensed under BSD 3 clause license. See LICENSE.txt file at
  * https://github.com/tudasc/metacg/LICENSE.txt
  */
-#include "cage/Plugin.h"
+#include "cage/CaGe.h"
+#include "cage/interface/CaGePlugin.h"
 
-#include "llvm/IR/LegacyPassManager.h"
 #include "llvm/Passes/PassBuilder.h"
 #include "llvm/Passes/PassPlugin.h"
+#include "llvm/Support/DynamicLibrary.h"
 
 #include "cage/generator/CallgraphGenerator.h"
 #include "cage/generator/FileExporter.h"
@@ -30,7 +31,32 @@ static opt<cage::PTAType> pta(
 
 static opt<std::string> cgout("cg-file", desc("Output file for the generated call graph"), cat(cageOpts), init(""));
 
+static list<std::string> pluginPaths("plugin-paths", desc("option list"), cat(cageOpts), CommaSeparated);
+
 namespace cage {
+
+Plugin* loadPlugin(const std::string& pluginPath) {
+  metacg::MCGLogger::instance().getConsole()->debug("Loading plugin");
+  std::string err;
+  auto lib = sys::DynamicLibrary::getPermanentLibrary(pluginPath.c_str(), &err);
+  if (!lib.isValid()) {
+    metacg::MCGLogger::instance().getErrConsole()->error("cannot locate the library at {}!", pluginPath);
+    metacg::MCGLogger::instance().getErrConsole()->error("Reason: {}", err);
+    return nullptr;
+  }
+  metacg::MCGLogger::instance().getConsole()->trace("Getting collection object from plugin {}", pluginPath);
+  void* sym = lib.getAddressOfSymbol("getPlugin");
+  if (!sym) {
+    metacg::MCGLogger::instance().getErrConsole()->error(
+        "Could not load collectors from plugin, no Function \"getPlugin()\"!");
+    return nullptr;
+  }
+  auto getPlugin = reinterpret_cast<Plugin* (*)()>(sym);
+  Plugin* loadedPlugin = getPlugin();
+  metacg::MCGLogger::logInfo("Successfully loaded Plugin: {}", loadedPlugin->getPluginName());
+  return loadedPlugin;
+}
+
 PreservedAnalyses CaGe::run(Module& M, ModuleAnalysisManager& MA) {
   if (cageVerbose) {
     outs() << "Running CaGe in verbose mode\n";
@@ -40,8 +66,7 @@ PreservedAnalyses CaGe::run(Module& M, ModuleAnalysisManager& MA) {
   std::string outfile = cgout.getValue();
   if (outfile.empty()) {
     // If empty, check environment variable
-    const auto* cgNameEnv = std::getenv("CAGE_CG");
-    if (cgNameEnv) {
+    if (const auto* cgNameEnv = std::getenv("CAGE_CG")) {
       outfile = cgNameEnv;
     } else {
       // Default output file
@@ -50,7 +75,15 @@ PreservedAnalyses CaGe::run(Module& M, ModuleAnalysisManager& MA) {
   }
 
   Generator gen(pta);
-  gen.addConsumer(std::make_unique<FileExporter>(outfile));
+  gen.addPlugin(std::make_unique<FileExporter>(outfile));
+
+  // Load external plugins
+  for (const auto& pluginPath : pluginPaths) {
+    SPDLOG_INFO("Loading external plugin from: {}", pluginPath);
+    if (auto p = std::unique_ptr<Plugin>(loadPlugin(pluginPath))) {
+      gen.addPlugin(std::move(p));
+    }
+  }
 
   if (!gen.run(M, &MA))
     return PreservedAnalyses::all();
@@ -84,6 +117,7 @@ llvm::PassPluginLibraryInfo getPluginInfo() {
             if (Name == "CaGe") {
               outs() << "Registering CaGe to run as pipeline described\n";
               MPM.addPass(cage::CaGe());
+
               return true;
             } else {
               outs() << "Did not register CaGe\n";

tools/cage/src/CMakeLists.txt

@@ -138,6 +138,7 @@ struct CallBaseVisitor : public llvm::InstVisitor<CallBaseVisitor> {
       }
       origin = functionInfoMap[F]->getFilename().str();
     }
+
     return mcg->getOrInsertNode(nameToUse.str(), std::move(origin), false, hasBody);
   }
 
@@ -166,9 +167,16 @@ bool Generator::run(Module& M, ModuleAnalysisManager* MA) {
     // Take resulting metacg call graph
     auto mcg = cbv.takeResult();
 
-    // Run registered consumers
-    for (auto& consumer : consumers) {
-      consumer->consumeCallGraph(*mcg);
+    // Run registered plugin's augmentation
+    for (auto& plugin : plugins) {
+      metacg::MCGLogger::instance().debug("Running {} augment",plugin->getPluginName());
+      plugin->augmentCallGraph(M,*mcg);
+    }
+
+    // Run registered plugins consumption
+    for (auto& plugin : plugins) {
+      metacg::MCGLogger::instance().debug("Running {} consume", plugin->getPluginName());
+      plugin->consumeCallGraph(*mcg);
     }
   }
   return false;

tools/cage/src/Plugin.cpp tools/cage/src/CaGe.cpptools/cage/src/Plugin.cpp renamed to tools/cage/src/CaGe.cpp

@@ -13,7 +13,7 @@
 
 namespace cage {
 
-void FileExporter::consumeCallGraph(metacg::Callgraph& graph) {
+void FileExporter::consumeCallGraph(const metacg::Callgraph& graph) {
   metacg::io::JsonSink jsSink;
   metacg::io::VersionFourMCGWriter mcgw({{4, 0}, {"CaGe", 0, 1, MetaCG_GIT_SHA}}, true, true);
   mcgw.write(&graph, jsSink);