Extending Choosing an Extension Model

Choosing an Extension Model

Prev: Extending ReqPack | Up: Extending ReqPack | Next: Writing Lua Plugins

Before writing code, decide what kind of extension you actually need.

Choose a Lua Wrapper Plugin When

Use a Lua wrapper plugin if:

• a real package manager already exists,
• you want ReqPack to normalize CLI behavior,
• shelling out to the real tool is acceptable,
• you want the smallest and fastest path to integration.

Examples from this repository:

• plugins/dnf/run.lua
• plugins/maven/run.lua
• plugins/sys/run.lua

This is the default recommendation for most ecosystems.

Choose a Proxy Plugin When

Use a proxy plugin if:

• users should target one logical system,
• actual execution should go to one of several backends,
• backend choice depends on config, platform, or package shape.

Example:

• plugins/java/run.lua

The Java proxy does not install packages by itself. It resolves requests to a real target such as maven or gradle.

Add a Registry Entry When

Use a registry entry if:

• plugin implementation already exists,
• you want teams to refresh or distribute that plugin from a central registry,
• you need hashes, aliases, or trust metadata around that plugin.

Registry entry is metadata and distribution layer. It points to implementation. It does not replace implementation.

Choose Native rqp Packages When

Use rqp packages if:

• you want a ReqPack-native install format,
• you want package lifecycle hooks inside the package,
• you need an internal package repository controlled by your team,
• you are distributing tools or artifacts that do not map well to another package manager.

This is not a thin wrapper. It is ReqPack acting as the package manager.

Choose a Native C++ Plugin When

Use a native C++ plugin if:

• Lua runtime or shell calls are not enough,
• you need deep process, network, or filesystem integration,
• you care about performance or stronger type-level control,
• you want behavior equivalent to the built-in rqp plugin,
• you are willing to modify and rebuild ReqPack itself.

This is the highest-effort option. Current codebase does not load external native plugins from shared libraries. Do it only when a Lua wrapper is clearly not enough.

Decision Guide

Question	Best fit
Does an ecosystem already have its own package manager?	Lua wrapper plugin
Is one logical system selecting among multiple backends?	Proxy plugin
Do you already have plugin code and only need central distribution or trust metadata?	Registry entry
Do you want ReqPack-native packages and repos?	rqp package + repository
Do you need custom runtime behavior inside core process?	Native C++ plugin

Anti-patterns

• Do not build a native C++ plugin only to shell out to another package manager. Lua is enough for that.
• Do not build an rqp package ecosystem if a normal wrapper plugin is the real need.
• Do not use aliases when a proxy plugin is required. Aliases only rename systems; they do not transform requests.
• Do not stop at a registry entry when actual plugin implementation still does not exist.

Related Pages

• Writing Lua Plugins
• Building rqp Packages and Repositories
• Building Native C++ Plugins

Prev: Extending ReqPack | Up: Extending ReqPack | Next: Writing Lua Plugins