Christopher M. Punches
267529bee3
Module APIs and the library's exported ABI are versioned and retired deliberately: a break ships as a new table version or a new symbol version node, and consumers judge the versions they are handed. Document src/libdpm-core.map — what it pins, what belongs in it, and how a generation is retired — and declare DPM_CORE_0.1 as the shape the next retired node takes.
91 lines
5.5 KiB
Markdown
91 lines
5.5 KiB
Markdown
# Developing DPM Modules
|
|
|
|
A DPM module is one shared object in the module directory. libdpm-core loads it, validates it completely, routes commands to it, and serves its functions to other modules and to programs linked against libdpm-core. This document covers writing, building, testing, and installing a module.
|
|
|
|
## The module contract
|
|
|
|
Every module exports the following symbols as extern "C". All returned strings must be non-NULL, static or module-owned, and valid for the lifetime of the loaded module; callers never free them.
|
|
|
|
**`int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)`**
|
|
The generic command entry point. `ctx` is the host context that dispatched the call; the module reaches every libdpm-core service (`dpm_log`, `dpm_config_get`, `dpm_module_path`, ...) through it. `command` is the subcommand name, equal to argv[0] when argc > 0. NULL or empty `command` must behave as the module's help command. Returns 0 on success, nonzero on failure. It must be callable immediately after load with no other setup.
|
|
|
|
**`const char* dpm_module_version(void)`**
|
|
The module's own version as an X.Y.Z string. libdpm-core reports this value to consumers, and each consumer decides for itself whether the version suits it.
|
|
|
|
**`const char* dpm_module_description(void)`**
|
|
A one-line human-readable description, shown in module listings.
|
|
|
|
**`const char* dpm_module_core_min(void)`**
|
|
The minimum libdpm-core version (X.Y.Z) the module supports — the oldest one whose contract and services it was written against. A libdpm-core older than that refuses to load the module, and the refusal message says so.
|
|
|
|
**`const dpm_manifest* dpm_module_manifest(void)`**
|
|
A static table declaring the module's entire functional surface: an entry count and, per entry, the API name, its table version, and the exact exported symbol carrying the table — for example { "mymodule", 1, "mymodule_api_v1" }. Only manifest-declared tables are ever handed to consumers; an API absent from the manifest does not exist, even if its symbol does. A module providing no API tables returns a manifest with a count of zero.
|
|
|
|
The `dpm_manifest` and `dpm_manifest_entry` types, the table header, and the service declarations all come from the installed public header:
|
|
|
|
```
|
|
#include <dpm/core.h>
|
|
```
|
|
|
|
## API tables
|
|
|
|
A module's functions are published to consumers as API tables: one exported symbol per API version (`mymodule_api_v1`), pointing to a plain C struct of function pointers. Every table opens with a `dpm_api_table_header` — the `DPM_API_TABLE_MAGIC` constant, then the table struct's size in bytes as the module compiled it. A consumer compares that size against the layout it was built against to see what it has been handed.
|
|
|
|
All parameters and return values crossing a table are C types only. State passes through opaque handles; errors are int codes.
|
|
|
|
**Symbol naming**: every functional export is prefixed with the module's name (mymodule_\*). The dpm_ prefix is reserved for the contract symbols and libdpm-core.
|
|
|
|
## Validation at load
|
|
|
|
libdpm-core is the sole authority on module validity, and validation is all-or-nothing. Before a module is offered to anyone, it verifies, in order: every reserved contract symbol resolves; the minimum-version handshake passes; the version and description probes return well-formed values; every manifest-declared symbol resolves; and every declared table carries the correct magic and a sane size. A module failing any step is refused with an itemized reason, visible in the load-failure output. A module that loads is fully valid — consumers never defend against partial states.
|
|
|
|
## Building
|
|
|
|
A module repository builds with CMake:
|
|
|
|
```
|
|
cmake_minimum_required(VERSION 3.22)
|
|
project(mymodule)
|
|
|
|
set(CMAKE_CXX_STANDARD 20)
|
|
set(CMAKE_CXX_STANDARD_REQUIRED ON)
|
|
|
|
add_library(mymodule MODULE mymodule.cpp)
|
|
|
|
set_target_properties(mymodule PROPERTIES
|
|
PREFIX ""
|
|
SUFFIX ".so"
|
|
)
|
|
|
|
target_link_libraries(mymodule PRIVATE dpm-core)
|
|
|
|
install(TARGETS mymodule LIBRARY DESTINATION lib/dpm/modules)
|
|
```
|
|
|
|
```
|
|
cmake -B <build-dir>
|
|
cmake --build <build-dir>
|
|
```
|
|
|
|
libdpm-core is the only DPM link dependency a module ever has. Dependencies on other modules are runtime concerns, resolved through the require/get_api pair — a peer module is never linked and never needs to be present to build.
|
|
|
|
A module that depends on a peer is the party that judges the peer's version. Require it, read its reported version with `dpm_module_info_of`, and decide whether it is too new or too old for the calls you intend to make. libdpm-core reports; it does not rule.
|
|
|
|
## Running and testing locally
|
|
|
|
Load the freshly built module through a locally run `dpm` without installing anything:
|
|
|
|
```
|
|
dpm --module-path <build-dir> mymodule <command>
|
|
```
|
|
|
|
libdpm-core runs the full validation sequence on every load, so a contract mistake surfaces here, immediately and itemized, rather than after installation. The `--config-dir` flag points the module's configuration namespace at local files during development, and `--root` directs package operations at a scratch tree.
|
|
|
|
## Installing
|
|
|
|
Modules install to `lib/dpm/modules` under the install prefix (`/usr/lib/dpm/modules` on a distribution install). libdpm-core discovers the module on its next scan; no registration step exists beyond the file being present and valid.
|
|
|
|
## A working example
|
|
|
|
The info module bundled with the `dpm` binary and libdpm-core, at `src/bundled-modules/info/`, tests and demonstrates full DPM system functionality, and in doing so shows the contract, an API table, and this build structure in working form.
|
