Extending Building Native Cpp Plugins

Building Native C++ Plugins

Prev: Building rqp Packages and Repositories | Up: Extending ReqPack | Next: Architecture

ReqPack supports native plugins through the IPlugin interface. This is the most powerful extension path, but also the most expensive one to build and maintain. In this architecture, native plugin work means editing ReqPack source and rebuilding binary. There is no external shared-library native plugin loader.

That also means wiring plugin into core registry/bootstrap path, not dropping a compiled file into plugin directory.

When to Use This Path

Use a native plugin when:

• Lua wrappers are not enough,
• you need tight integration with internal C++ services,
• you need richer local runtime behavior than shelling out can provide,
• you want behavior similar to the built-in rqp package manager,
• you are willing to ship a rebuilt rqp binary.

If you only want to wrap another CLI, prefer a Lua plugin.

Core Interface

Native plugins implement IPlugin from src/main/include/plugins/iplugin.h. For current repo, rqp is reference implementation and built-in native plugin.

Key methods:

• lifecycle: init(), shutdown()
• metadata: getName(), getVersion(), getPluginId()
• requirements and categories: getRequirements(), getCategories()
• actions: install(), installLocal(), remove(), update()
• queries: list(), search(), info(), outdated()
• optional helpers: resolvePackage(), resolveProxyRequest(), getSecurityMetadata()

Runtime Host

Native plugins receive a PluginCallContext. From that context they can:

• log messages,
• emit progress and transaction events,
• execute commands,
• create temp directories,
• download files,
• inspect proxy config,
• inspect repositories,
• inspect host information.

This is the same conceptual runtime that Lua plugins see, but through C++ types.

Minimal Skeleton

class MyPlugin final : public IPlugin {
public:
    bool init() override { return true; }
    bool shutdown() override { return true; }

    std::string getName() const override { return "My Plugin"; }
    std::string getVersion() const override { return "1.0.0"; }
    std::string getPluginId() const override { return "myplugin"; }
    std::string getPluginDirectory() const override { return {}; }
    std::string getScriptPath() const override { return {}; }
    std::string getBootstrapPath() const override { return {}; }
    IPluginRuntimeHost* getRuntimeHost() override { return runtimeHost_; }

    std::vector<Package> getRequirements() override { return {}; }
    std::vector<std::string> getCategories() override { return {"Native"}; }
    std::vector<Package> getMissingPackages(const std::vector<Package>& packages) override { return packages; }

    bool install(const PluginCallContext& context, const std::vector<Package>& packages) override;
    bool installLocal(const PluginCallContext& context, const std::string& path) override;
    bool remove(const PluginCallContext& context, const std::vector<Package>& packages) override;
    bool update(const PluginCallContext& context, const std::vector<Package>& packages) override;

    std::vector<PackageInfo> list(const PluginCallContext& context) override;
    std::vector<PackageInfo> outdated(const PluginCallContext& context) override;
    std::vector<PackageInfo> search(const PluginCallContext& context, const std::string& prompt) override;
    PackageInfo info(const PluginCallContext& context, const std::string& packageName) override;

private:
    IPluginRuntimeHost* runtimeHost_{nullptr};
};

Best Existing Reference

Use the built-in rqp plugin as the main example:

• implementation: src/main/cpp/plugins/rq_plugin.cpp
• header: src/main/include/plugins/rq_plugin.h

It shows:

• a full native IPlugin implementation,
• package resolution,
• installed-state tracking,
• repository index parsing,
• custom hook runtime,
• event and artifact reporting.

Recommended Strategy

If you think you need a C++ plugin, do this first:

1. prototype the ecosystem as a Lua plugin,
2. document what Lua cannot do well enough,
3. move only the hard parts to C++.

That keeps the design honest.

Related Pages

• Writing Lua Plugins
• Architecture Overview
• Execution Flow

Prev: Building rqp Packages and Repositories | Up: Extending ReqPack | Next: Architecture