Dark-Horse-Linux/dpm-core-ng
3
0
Fork 0
Code Issues Pull Requests Actions Activity

Stop bolding function signatures in the documentation

Browse Source 
A signature containing char** argv closed its own bold emphasis early,
which garbled the dpm_execute and dpm_module_execute entries and the
text following them. Signatures are plain code spans now, so a signature
carrying a double asterisk renders like every other one.
This commit is contained in:
Chris Punches
2026-08-16 00:21:52 -04:00
parent cd1e15acec
commit dcd8b3fa2c
3 changed files with 28 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/CONSUMERS.md
View File

@@ -48,7 +48,7 @@ The root override is what makes chroot builds, image assembly, and sysroot manag
## Acquiring and Using Modules ## Acquiring and Using Modules
**`dpm_require`** loads a module by name, on demand: `dpm_require` loads a module by name, on demand:
``` ```
dpm_module* mod = dpm_require(ctx, "mymodule"); dpm_module* mod = dpm_require(ctx, "mymodule");
@@ -56,7 +56,7 @@ dpm_module* mod = dpm_require(ctx, "mymodule");
libdpm-core.so validates the module completely at load; a handle is returned only for a fully valid module. NULL means the module is absent or invalid — `dpm_last_error`(ctx) carries the precise reason. Modules load at most once per context; repeated calls return the same handle. libdpm-core.so validates the module completely at load; a handle is returned only for a fully valid module. NULL means the module is absent or invalid — `dpm_last_error`(ctx) carries the precise reason. Modules load at most once per context; repeated calls return the same handle.
**`dpm_module_info_of`** reports what the library saw in the loaded module: `dpm_module_info_of` reports what the library saw in the loaded module:
``` ```
dpm_module_info info; dpm_module_info info;
@@ -67,7 +67,7 @@ dpm_module_info_of(ctx, mod, &info);
Deciding whether that version is suitable is yours. libdpm-core.so applies no version criterion of its own — a handle means the module is valid, not that it suits you. Deciding whether that version is suitable is yours. libdpm-core.so applies no version criterion of its own — a handle means the module is valid, not that it suits you.
**`dpm_execute`** invokes the module — a command name and arguments: `dpm_execute` invokes the module — a command name and arguments:
``` ```
int rc = dpm_execute(ctx, mod, "command", argc, argv); int rc = dpm_execute(ctx, mod, "command", argc, argv);
@@ -90,12 +90,12 @@ The cursor covers every valid module in the module path; invalid candidates are
## Services ## Services
- **`dpm_core_version`()** — the library version; callable without a context. - `dpm_core_version`()** — the library version; callable without a context.
- **`dpm_module_info_of`(ctx, mod, out)** — the name, version, and description read from a loaded module. - `dpm_module_info_of`(ctx, mod, out)** — the name, version, and description read from a loaded module.
- **`dpm_config_get`(ctx, module, section, key)** — a value from a module's configuration namespace, or NULL if unset. - `dpm_config_get`(ctx, module, section, key)** — a value from a module's configuration namespace, or NULL if unset.
- **`dpm_log`(ctx, level, message)** — writes to the context's configured log targets; levels are `DPM_LOG_FATAL` through `DPM_LOG_DEBUG`. - `dpm_log`(ctx, level, message)** — writes to the context's configured log targets; levels are `DPM_LOG_FATAL` through `DPM_LOG_DEBUG`.
- **`dpm_module_path`(ctx)** — the resolved module directory. - `dpm_module_path`(ctx)** — the resolved module directory.
- **`dpm_last_error`(ctx)** — a human-readable description of the most recent failure on the context, or NULL. - `dpm_last_error`(ctx)** — a human-readable description of the most recent failure on the context, or NULL.
## Ownership and Errors ## Ownership and Errors

32
docs/DESIGN.md
View File

@@ -51,64 +51,64 @@ All functions are extern "C". All returned strings are owned by the library (or
### Context Lifecycle ### Context Lifecycle
**`dpm_ctx* dpm_open(const dpm_open_overrides* overrides)`** `dpm_ctx* dpm_open(const dpm_open_overrides* overrides)`
Creates a context. Reads configuration from `/etc/dpm/conf.d/` (or the config directory named in overrides), resolves the module path (overrides take precedence over config, config over the built-in default), and initializes logging per configuration. Performs no module loading. Returns NULL only on allocation failure or an unreadable/invalid explicit override; a missing config directory is not an error — defaults apply. `overrides` may be NULL, and may specify: config directory, module path, target root (for chroot/image/sysroot operation), and log level. Multiple simultaneous contexts with different roots are legal. Creates a context. Reads configuration from `/etc/dpm/conf.d/` (or the config directory named in overrides), resolves the module path (overrides take precedence over config, config over the built-in default), and initializes logging per configuration. Performs no module loading. Returns NULL only on allocation failure or an unreadable/invalid explicit override; a missing config directory is not an error — defaults apply. `overrides` may be NULL, and may specify: config directory, module path, target root (for chroot/image/sysroot operation), and log level. Multiple simultaneous contexts with different roots are legal.
**`void dpm_close(dpm_ctx* ctx)`** `void dpm_close(dpm_ctx* ctx)`
Releases the context: unloads every module handle it issued, closes log targets, frees all memory owned by the context. All handles and strings obtained through the context are invalid after this call. NULL is a no-op. Releases the context: unloads every module handle it issued, closes log targets, frees all memory owned by the context. All handles and strings obtained through the context are invalid after this call. NULL is a no-op.
### Module Acquisition ### Module Acquisition
**`dpm_module* dpm_require(dpm_ctx* ctx, const char* name)`** `dpm_module* dpm_require(dpm_ctx* ctx, const char* name)`
Resolves the module `name` in the module path and runs the full load-time validation sequence (see Load-Time Enforcement) if the module is not already loaded in this context. On success returns a module handle owned by the context (repeated calls return the same handle — modules are loaded at most once per context). On failure returns NULL and records the precise reason: not found, or validation step failed with the step and detail. No version criterion is applied here; compatibility is the caller's to determine from the reported version. Resolves the module `name` in the module path and runs the full load-time validation sequence (see Load-Time Enforcement) if the module is not already loaded in this context. On success returns a module handle owned by the context (repeated calls return the same handle — modules are loaded at most once per context). On failure returns NULL and records the precise reason: not found, or validation step failed with the step and detail. No version criterion is applied here; compatibility is the caller's to determine from the reported version.
**`int dpm_module_info_of(dpm_ctx* ctx, dpm_module* mod, dpm_module_info* out)`** `int dpm_module_info_of(dpm_ctx* ctx, dpm_module* mod, dpm_module_info* out)`
Fills `out` with the loaded module's name, version, and description exactly as they were read at load (string pointers valid until context close). This is how a consumer obtains the version it will judge. The library attaches no meaning to the values. Returns 0 on success, nonzero if the module cannot be reported on. Fills `out` with the loaded module's name, version, and description exactly as they were read at load (string pointers valid until context close). This is how a consumer obtains the version it will judge. The library attaches no meaning to the values. Returns 0 on success, nonzero if the module cannot be reported on.
**`int dpm_execute(dpm_ctx* ctx, dpm_module* mod, const char* command, int argc, char** argv)`** `int dpm_execute(dpm_ctx* ctx, dpm_module* mod, const char* command, int argc, char** argv)`
Dispatch: invokes the module's `dpm_module_execute` with the context, `command`, and the argument vector. Returns the module's return value verbatim (0 = success). The library adds nothing to the call besides delivery; argument semantics beyond "argv[0] is the command" are the module's to define. Dispatch: invokes the module's `dpm_module_execute` with the context, `command`, and the argument vector. Returns the module's return value verbatim (0 = success). The library adds nothing to the call besides delivery; argument semantics beyond "argv[0] is the command" are the module's to define.
This is the entire path into module code. A caller addresses a module by name and a capability by command string, so it holds no compile-time knowledge of the module it is calling — no headers, no struct layouts, no symbols. That is what allows a module to be developed, built, and tested with no peer present. This is the entire path into module code. A caller addresses a module by name and a capability by command string, so it holds no compile-time knowledge of the module it is calling — no headers, no struct layouts, no symbols. That is what allows a module to be developed, built, and tested with no peer present.
### Enumeration ### Enumeration
**`dpm_cursor* dpm_list_modules(dpm_ctx* ctx)`** `dpm_cursor* dpm_list_modules(dpm_ctx* ctx)`
Scans the module path and returns a cursor over all *valid* modules (each candidate .so is validated on first scan; failures are logged and excluded). Returns NULL on an unreadable module path. Scans the module path and returns a cursor over all *valid* modules (each candidate .so is validated on first scan; failures are logged and excluded). Returns NULL on an unreadable module path.
**`int dpm_cursor_next(dpm_cursor* cur, dpm_module_info* out)`** `int dpm_cursor_next(dpm_cursor* cur, dpm_module_info* out)`
Advances the cursor. Fills `out` with the next module's name, version, and description (string pointers valid until context close). Returns 0 and fills `out` while entries remain; returns nonzero at end. Advances the cursor. Fills `out` with the next module's name, version, and description (string pointers valid until context close). Returns 0 and fills `out` while entries remain; returns nonzero at end.
**`void dpm_cursor_free(dpm_cursor* cur)`** `void dpm_cursor_free(dpm_cursor* cur)`
Releases the cursor. NULL is a no-op. Releases the cursor. NULL is a no-op.
### Services (Available to Modules and External Consumers Alike) ### Services (Available to Modules and External Consumers Alike)
**`const char* dpm_core_version(void)`** `const char* dpm_core_version(void)`
Returns the library version as a static X.Y.Z string. Callable without a context. Returns the library version as a static X.Y.Z string. Callable without a context.
**`const char* dpm_config_get(dpm_ctx* ctx, const char* module, const char* section, const char* key)`** `const char* dpm_config_get(dpm_ctx* ctx, const char* module, const char* section, const char* key)`
Returns the configured value for `key` in `section` of the named module's config namespace (`/etc/dpm/conf.d/`<module>.conf; the namespace "core", from `core.conf`, is the library's own). Returns NULL if unset. String valid until context close. Returns the configured value for `key` in `section` of the named module's config namespace (`/etc/dpm/conf.d/`<module>.conf; the namespace "core", from `core.conf`, is the library's own). Returns NULL if unset. String valid until context close.
**`void dpm_log(dpm_ctx* ctx, int level, const char* message)`** `void dpm_log(dpm_ctx* ctx, int level, const char* message)`
Writes `message` at `level` (FATAL=0, ERROR=1, WARN=2, INFO=3, DEBUG=4) to the context's configured log targets (console and/or file). Messages above the configured level are dropped. NULL message is a no-op. Writes `message` at `level` (FATAL=0, ERROR=1, WARN=2, INFO=3, DEBUG=4) to the context's configured log targets (console and/or file). Messages above the configured level are dropped. NULL message is a no-op.
**`const char* dpm_module_path(dpm_ctx* ctx)`** `const char* dpm_module_path(dpm_ctx* ctx)`
Returns the resolved module directory path for this context. Returns the resolved module directory path for this context.
**`const char* dpm_last_error(dpm_ctx* ctx)`** `const char* dpm_last_error(dpm_ctx* ctx)`
Returns a human-readable description of the most recent failure recorded on this context, or NULL if none. Overwritten by the next failing call on the same context. Returns a human-readable description of the most recent failure recorded on this context, or NULL if none. Overwritten by the next failing call on the same context.
## Module Contract ## Module Contract
A module is one .so in the module directory. It includes `<dpm/core.h>`, links `-ldpm-core`, and exports the following reserved symbols as extern "C". Returned strings are static or module-owned, non-NULL, and valid for the lifetime of the loaded module; the library and consumers never free them. A module is one .so in the module directory. It includes `<dpm/core.h>`, links `-ldpm-core`, and exports the following reserved symbols as extern "C". Returned strings are static or module-owned, non-NULL, and valid for the lifetime of the loaded module; the library and consumers never free them.
**`int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)`** `int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)`
The module's command entry point, and the only entry through which it performs work. `ctx` is the host context that dispatched the call — the module reaches every service (`dpm_log`, `dpm_config_get`, `dpm_module_path`, ...) through it, and reaches peer modules through it as well. `command` is the subcommand name (equal to argv[0] when argc > 0); argc/argv are the remaining CLI-style arguments. 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. The module's command entry point, and the only entry through which it performs work. `ctx` is the host context that dispatched the call — the module reaches every service (`dpm_log`, `dpm_config_get`, `dpm_module_path`, ...) through it, and reaches peer modules through it as well. `command` is the subcommand name (equal to argv[0] when argc > 0); argc/argv are the remaining CLI-style arguments. 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)`** `const char* dpm_module_version(void)`
Returns the module's own version as an X.Y.Z string. Must be constant for the life of the module. This is the value the library reports to consumers, and the value they judge compatibility against. Returns the module's own version as an X.Y.Z string. Must be constant for the life of the module. This is the value the library reports to consumers, and the value they judge compatibility against.
**`const char* dpm_module_description(void)`** `const char* dpm_module_description(void)`
Returns a one-line human-readable description, used in module listings. Returns a one-line human-readable description, used in module listings.
**Version compatibility with the library is the module's own to determine.** A module is built against the system-installed `libdpm-core.so` and is responsible for being correct against it. Where it needs to act on what it is running under, `dpm_core_version()` reports the running version and the module decides what to do with that. **Version compatibility with the library is the module's own to determine.** A module is built against the system-installed `libdpm-core.so` and is responsible for being correct against it. Where it needs to act on what it is running under, `dpm_core_version()` reports the running version and the module decides what to do with that.

6
docs/MODULES.md
View File

@@ -6,13 +6,13 @@ A DPM module is one shared object in the module directory. libdpm-core.so loads
A module includes `<dpm/core.h>`, links `-ldpm-core`, and 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. A module includes `<dpm/core.h>`, links `-ldpm-core`, and 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)`** `int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)`
The command entry point, and the only entry through which the module performs work. `ctx` is the host context that dispatched the call; the module reaches every service (`dpm_log`, `dpm_config_get`, `dpm_module_path`, ...) through it, and reaches peer modules through it as well. `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. The command entry point, and the only entry through which the module performs work. `ctx` is the host context that dispatched the call; the module reaches every service (`dpm_log`, `dpm_config_get`, `dpm_module_path`, ...) through it, and reaches peer modules through it as well. `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)`** `const char* dpm_module_version(void)`
The module's own version as an X.Y.Z string. libdpm-core.so reports this value to consumers, and each consumer decides for itself whether the version suits it. The module's own version as an X.Y.Z string. libdpm-core.so reports this value to consumers, and each consumer decides for itself whether the version suits it.
**`const char* dpm_module_description(void)`** `const char* dpm_module_description(void)`
A one-line human-readable description, shown in module listings. A one-line human-readable description, shown in module listings.
The `dpm_ctx` type and the service declarations all come from the installed public header: The `dpm_ctx` type and the service declarations all come from the installed public header: