LoxDust

Part of the LOX family: Liquid Oxygen for Embedded Systems.

LoxDust is a portable C99 library for verified persistent object storage. See LICENSE for the full license text.

The core library provides:

• caller-owned context storage
• fixed-width canonical on-disk encoding
• object registration and deterministic layout
• format, mount, propose, read, check, repair, and confirm operations
• FAST, SAFE, and CRITICAL profiles
• RAM and file backends for host testing
• deterministic unit, recovery, power-cut, and property tests

Layout

• include/healing_dust/hd.h public API
• include/healing_dust/hd_backend_ram.h RAM backend helper
• include/healing_dust/hd_backend_file.h file backend helper
• backends/ host test backends
• src/ core implementation
• tests/ deterministic test suite
• docs/ API reference, cookbook, architecture, testing, known issues, and release notes

Build And Install

cmake -S . -B build -G Ninja -DHD_BUILD_TESTS=ON -DHD_WARNINGS_AS_ERRORS=ON
cmake --build build
ctest --test-dir build --output-on-failure
cmake --install build --prefix package

If you prefer the default generator on Windows, the same commands work without -G Ninja.

Using The Package

After installation, the public headers are under include/healing_dust/ and the static library is under lib/.

Consumers can point their build system at the install prefix and include:

#include "healing_dust/hd.h"
#include "healing_dust/hd_backend_ram.h"
#include "healing_dust/hd_backend_file.h"

For local testing or release validation, the generated package can be created with:

cmake --install build --prefix package

Release tags publish packaged archives through GitHub Actions. The release workflow attaches the install tree as downloadable build artifacts.

API Surface

The public namespace lives under healing_dust/:

• hd_init() binds storage, geometry, region bounds, and caller work memory.
• hd_register_object() records the object schema before hd_format() or hd_mount().
• hd_format() writes a canonical empty image.
• hd_mount() validates and opens an existing image.
• hd_propose(), hd_read_verified(), hd_check(), hd_repair(), and hd_confirm_state() implement the recovery model.

Documentation

• Documentation index
• API reference
• Cookbook
• Architecture
• Testing
• Known issues
• Release notes
• Changelog
• Quickstart
• Contributing
• Code of Conduct
• Security
• Support
• Roadmap

License

MIT. See LICENSE.