dpm-core-ng/docs/OVERVIEW.md

DPM — An Overview

What DPM Is

DPM is the package manager for Dark Horse Linux. At its center is libdpm-core.so, a shared library that discovers modules, validates them, and routes calls to them, and that provides configuration and logging to whatever it has loaded. Modules — shared objects in the module directory — implement package functionality.

The dpm binary is the command-line tool, and it is one consumer of that library. Build systems, image builders, distribution tooling, and programs in any language with C FFI are equal consumers of the same library through the same interface.

libdpm-core.so implements no package operations. It routes and hosts.

The Shape of the System

Everything reaches a module the same way, and a module reaching another module is the same step repeated:

the dpm binary   ->  <dpm/core.h>  ->  module A  ->  <dpm/core.h>  ->  module B
a build system   ->  <dpm/core.h>  ->  module A  ->  <dpm/core.h>  ->  module B

<dpm/core.h> is the declared interface; libdpm-core.so is what implements it. A caller includes the header, links -ldpm-core, and asks the library to discover and invoke modules by name.

It all happens in one address space. The dpm binary (or the build system) is the process; libdpm-core.so is mapped into it; every module the library loads is mapped into it as well. Calls are direct function calls with no subprocess, no serialization, and no output parsing anywhere in the chain.

Two properties make the routing rule real rather than a convention:

• There is one instance of libdpm-core.so in the process. A module links against the library like any other consumer, and when the module is loaded the dynamic linker binds it to the copy already mapped. A module therefore drives the same context, the same module registry, and the same configuration the original caller opened.
• Modules cannot see each other. They are loaded with RTLD_LOCAL, so a module's symbols never enter the global namespace. The only symbols a module can resolve are libdpm-core.so's, so there is physically no path from one module to another that does not pass through the library.

Running the dpm Binary

The dpm binary's subcommand surface is exactly the set of loadable modules. dpm <module> <command> [args...] loads that module and hands the command to it; dpm <module> help asks the module to describe itself. There is no fixed list of operations baked into the tool, because the tool contains no capability logic — it parses arguments and prints.

dpm --list-modules shows every module that passes validation, with its version and description. Candidates that fail are excluded from the listing and logged, so what is listed is what can actually be run.

Four flags redirect the system defaults:

• -c, --config-dir PATH — where configuration is read from
• -m, --module-path PATH — which directory modules are loaded from
• -r, --root PATH — the target root that package operations act on
• -L, --log-level LEVEL — FATAL, ERROR, WARN, INFO, or DEBUG

These four exist because of a rule the design imposes on itself: every field a linked program can override must also be a flag, so anything reachable from code is reachable from a shell. That rule holds for any override added in the future.

Writing a Program Against the Library

A program includes <dpm/core.h> and links -ldpm-core, the same as it would link any other shared library. Everything it does happens through a context, an opaque handle obtained from dpm_open.

Opening a context reads the configuration files, resolves which directory modules will be loaded from, and initializes logging. It loads no modules. The same four things the dpm binary exposes as flags are the fields of the overrides struct passed to dpm_open, and passing NULL accepts the system defaults — which is what makes a default context equivalent to what the installed dpm binary sees, since that binary is just another caller doing the same thing.

The target root override is what makes chroot builds, image assembly, and sysroot management work: package operations act on the given tree instead of the running system. Multiple contexts with different roots may be open at once.

The context owns everything it hands out. Every string a caller receives stays valid until dpm_close, and callers never free anything.

Acquiring a module. dpm_require resolves a module by name, validates it completely, and returns a handle — or returns NULL, with dpm_last_error carrying the precise reason. Modules load at most once per context, and repeated calls return the same handle.

Reading what the library saw. dpm_module_info_of fills in a module's name, version, and description. Those values are reported, and no conclusion is drawn from them.

Calling into a module. dpm_execute passes a command name and an argument vector to the module's entry point and returns its result. This is the only path into module code, and it is the same one the dpm binary takes.

Enumerating. dpm_list_modules yields a cursor over every valid module, which is what backs the listing the dpm binary prints.

Services. A module reaches the library through the context that dispatched the call: dpm_log to write a message, dpm_config_get to read a value from its own configuration namespace, dpm_module_path to learn where modules live, dpm_core_version to learn the library's version. A module needs no file handling and no logging machinery of its own.

How a Module Reaches Another Module

A module is a consumer of <dpm/core.h> exactly like the dpm binary is. To reach a peer it performs the identical two steps its own caller performed: ask the library for the module by name, then ask the library to invoke it.

int dpm_module_execute(dpm_ctx* ctx, const char* command, int argc, char** argv)
{
    dpm_module* peer = dpm_require(ctx, "othermodule");
    if (!peer) {
        dpm_log(ctx, DPM_LOG_ERROR, dpm_last_error(ctx));
        return 1;
    }
    return dpm_execute(ctx, peer, "somecommand", argc, argv);
}

The ctx a module needs is the one handed to it in its own entry point, so it requires nothing else to reach the library.

A module never links, includes, or hardcodes anything belonging to another module. No peer headers, no shared struct layouts, no peer symbols. The only build dependency a module has is libdpm-core.so, and the only knowledge it holds about a peer is the peer's name and the command it wants to run. That is what allows every module to live in its own repository and be built with no peer present anywhere on the machine.

What DPM Reads and Writes on Disk

Configuration lives in /etc/dpm/conf.d/. Each .conf file in that directory is one namespace named after the file: core.conf holds the library's own settings, and a module named mymodule reads mymodule.conf. Files are sectioned, and a value is addressed by namespace, section, and key. The library's own file carries the log level, whether to write a log file and where, and the default module directory.

Modules live in /usr/lib/dpm/modules/. A module's name is its filename without the .so extension, so info.so is the module named info. Discovery is the presence of a valid file in that directory — there is no registry, and no registration step.

Logging goes to the console always, and to a log file when configuration enables one; the default path is /var/log/dpm/dpm.log.

The target root defaults to /. Pointed elsewhere, it is the tree that package operations act on, which is what turns a scratch directory into a complete target for image assembly or a chroot build.

Installed artifacts:

Artifact	Location
the dpm binary	/usr/bin/dpm
libdpm-core.so	/usr/lib/libdpm-core.so
public header	/usr/include/dpm/core.h
modules	/usr/lib/dpm/modules/<name>.so

The Module Contract

What a module author implements.

A module is one .so in the module directory exporting three reserved symbols: a command entry point, its own version, and a one-line description. It includes <dpm/core.h> for those declarations and links -ldpm-core, and that is its entire build dependency.

The entry point receives the context that dispatched the call, the command name, and an argument vector, and returns an int. Everything a module offers the rest of the system is reachable through that one function, addressed by command name — which is what keeps a caller free of any compile-time knowledge of the module it is calling.

A module is built against the system-installed libdpm-core.so and is responsible for being correct against it. Where it needs to know what it is running on, dpm_core_version() reports the running version and the module acts on that itself.

Load-Time Enforcement

libdpm-core.so validates a module completely before offering it to anyone:

1. Every reserved contract symbol resolves.
2. The version and description probes return well-formed values.

A module failing any step is refused with an itemized reason and its library handle closed. Validation is all-or-nothing: if a handle comes back, the contract already passed. Consumers never defend against partially valid modules, because they cannot receive one.

From the command line this shows up as a module missing from --list-modules with a logged reason, or as an itemized failure when the module is named directly.

Versioning

Every version question belongs to the party that has to live with the answer.

A module determines its own compatibility with the library it is running against. dpm_core_version() reports the running version, and the module proceeds or fails on its own judgement. A module is built against the system-installed libdpm-core.so and is responsible for being correct against it.

A module that depends on another module requires it, reads the version reported back, and decides for itself whether that version is suitable for the commands it intends to issue. libdpm-core.so reports what it saw and draws no conclusion from it, so a handle means the module is valid rather than that it suits any particular caller.

Why It Works This Way

Because It Must Run on a Barren System

The founding constraint is that DPM has to work in an environment providing nothing but libc and libstdc++, using the same binaries that run on a fully populated system. That forbids libdpm-core.so from taking on any dependency beyond the baseline, which forbids package logic from living inside it, which produces the division the whole architecture rests on: libdpm-core.so routes and hosts, modules implement. Anything needing a database, compression, or TLS is a module that arrives later.

Because Capability Has to Grow in Layers

Each layer of the system installs the dependencies of the next using only what already works. That requires upper layers to reach lower ones through a stable in-process interface rather than by re-implementing them, and it requires writes to flow strictly downward — a layer mutates the system only through the layer beneath it. Shared concerns like locking are then implemented once, at the bottom, and inherited by everything above.

Because One Implementation Must Serve Every Caller

The requirement that every implementation exist exactly once, and be consumable by the dpm binary, by other layers, and by external programs, is what makes libdpm-core.so a C ABI library rather than an application with a library carved out of it. It is also why the command line and the C API stay in step: the flags are the override fields, one for one, so a program and a person redirect the same things by the same names.

Because Nothing May Be Trusted That Has Not Been Verified

libdpm-core.so is the sole authority on module validity, and the contract is enforced by its validator rather than by an SDK a module author might skip, patch, or fall behind. That is why validation is all-or-nothing and why it happens at load: failures surface loudly and itemized at install time instead of halfway through an operation on a user's system.

Because Coordination Happens at Load, Not at Build

A caller states the module name and command it needs and is told at load whether the module is there. That is what allows modules to be released independently: agreement is reached when the pieces meet, through declared versions each consumer judges for itself, instead of through lockstep builds.

Because Modules Are Developed Independently

One repository per module, plus the libdpm-core.so repository. A module links libdpm-core.so and nothing else from DPM; peer modules never appear in its repository, build, or test environment. "Not all the pieces are there" is the normal, permanent condition at build time, so the architecture is arranged to make that a non-event:

• A module compiles against <dpm/core.h> and nothing else from DPM.
• A peer is addressed by name and command string, so nothing about a peer needs to exist at compile time.
• A harness that links the real libdpm-core.so and points the module path at build output plus fixture stubs exercises the real validation on a bare builder.
• Only final integration needs the whole system, and because alternate roots are first-class, it needs a directory rather than a virtual machine.

This repository's own fixtures are deliberately broken stub modules — missing symbols, a malformed version — plus one known-good stub. Developing libdpm-core.so never requires a real package module to exist.

What This Repository Produces

• libdpm-core.so — the library
• the dpm binary — the command-line tool
• info — a module bundled with the dpm binary and libdpm-core.so, used to test and demonstrate full DPM system functionality where appropriate

Every other module is developed against libdpm-core.so and lives outside this repository.

Invariants

1. libdpm-core.so routes and hosts; modules implement. No package logic inside it, ever.
2. <dpm/core.h> names no module and carries no module-specific type. It offers discovery and interaction only.
3. A module never links, includes, or hardcodes anything belonging to another module. All module-to-module interaction passes through libdpm-core.so.
4. Writes flow down, never sideways: a layer mutates the system only through the layer beneath it, in-process through mediated calls.
5. A module is either fully valid or not loaded — no partial states, no consumer-side defense.
6. Anything a linked program can redirect, a shell user can redirect too.

Further Reading

• DESIGN.md — the full design specification
• CONSUMERS.md — linking libdpm-core.so and driving it from a program
• MODULES.md — writing, building, testing, and installing a module
• BUILD.md — building, testing, and installing libdpm-core.so and the dpm binary
• DOCUMENTATION.md — generating the code reference