Title-case every page and section heading
DPM is public-facing, and its headings read as titles: capitalized throughout, with articles, conjunctions, and short prepositions left lowercase in the middle. Applies to the markdown documents and to the Doxygen page and section titles in the public header, so the generated reference matches. One prose cross-reference in DESIGN.md follows the section it names.
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
A DPM module is one shared object in the module directory. libdpm-core.so loads it, validates it completely, and dispatches commands to it on behalf of whatever asked — the `dpm` binary, a build system, or another module. This document covers writing, building, testing, and installing a module.
|
||||
|
||||
## The module contract
|
||||
## The Module Contract
|
||||
|
||||
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.
|
||||
|
||||
@@ -21,7 +21,7 @@ The `dpm_ctx` type and the service declarations all come from the installed publ
|
||||
#include <dpm/core.h>
|
||||
```
|
||||
|
||||
## You determine your own compatibility with the library
|
||||
## You Determine Your Own Compatibility With the Library
|
||||
|
||||
Your module is built against the system-installed `libdpm-core.so` and is responsible for being correct against it. Where you need to act on what you are running under, `dpm_core_version()` reports the running version and you decide what to do:
|
||||
|
||||
@@ -31,7 +31,7 @@ const char* running = dpm_core_version();
|
||||
|
||||
Check it, proceed or fail on your own terms, and report through `dpm_log` and your return code.
|
||||
|
||||
## Your interface is your command vocabulary
|
||||
## Your Interface Is Your Command Vocabulary
|
||||
|
||||
A module publishes no headers, no struct layouts, and no symbols to anything that calls it. Everything it offers is reached through `dpm_module_execute`, addressed by command string, with arguments passed as an argument vector and a status returned as an int.
|
||||
|
||||
@@ -39,7 +39,7 @@ That is what a caller compiles against: a module name and a command name, both s
|
||||
|
||||
**Symbol naming**: every functional export is prefixed with the module's name (mymodule_\*). The dpm_ prefix is reserved for the contract symbols and for libdpm-core.so.
|
||||
|
||||
## Calling another module
|
||||
## Calling Another Module
|
||||
|
||||
A module reaches a peer by performing the same two steps its own caller performed — ask libdpm-core.so for the module by name, then ask libdpm-core.so to invoke it:
|
||||
|
||||
@@ -62,7 +62,7 @@ The `ctx` is the one handed to your entry point. Nothing else is needed to reach
|
||||
|
||||
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 suitable for the commands you intend to issue. libdpm-core.so reports; it does not rule.
|
||||
|
||||
## Validation at load
|
||||
## Validation at Load
|
||||
|
||||
libdpm-core.so is the sole authority on module validity, and validation is all-or-nothing. Before a module is offered to anyone, it verifies that every reserved contract symbol resolves and that the version and description probes return well-formed values. A module failing either 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.
|
||||
|
||||
@@ -96,7 +96,7 @@ cmake --build <build-dir>
|
||||
|
||||
libdpm-core.so is the only DPM link dependency a module ever has. Dependencies on other modules are runtime concerns, resolved by name through require and dispatch — a peer module is never linked, never included, and never needs to be present to build or to test.
|
||||
|
||||
## Running and testing locally
|
||||
## Running and Testing Locally
|
||||
|
||||
Load the freshly built module through a locally run `dpm` binary without installing anything:
|
||||
|
||||
@@ -112,6 +112,6 @@ Where your module calls a peer, put a **stub module** in the fixture module path
|
||||
|
||||
Modules install to `lib/dpm/modules` under the install prefix (`/usr/lib/dpm/modules` on a distribution install). libdpm-core.so discovers the module on its next scan; no registration step exists beyond the file being present and valid.
|
||||
|
||||
## A working example
|
||||
## A Working Example
|
||||
|
||||
The info module bundled with the `dpm` binary and libdpm-core.so, at `src/bundled-modules/info/`, tests and demonstrates full DPM system functionality, and in doing so shows the contract, command routing, and this build structure in working form.
|
||||
|
||||
Reference in New Issue
Block a user