Library overview

This directory documents the libraries that are built or vendored by mars-nwe. It is intentionally separate from the API headers: the headers define ABI/API, while these notes explain which library should be used by mars-nwe code and which imported helpers are only low-level dependencies.

Mars/NW libraries

nwcore: common Mars helpers — INI reader/writer, logging facade. Does not contain NSS helpers; those are in libnwnss.
nwnss: imported NSS userspace provider — namespace, XAttr, trustee, quota, salvage and AdminVolume semantics. Host-FS/OtherFS policy lives in parallel *Userspace.c companions.
nwfs: Mars/NCP filesystem wrapper around libnwnss; owns NCP wire parsing, volume options and host persistence.

nwtui

nwtui is the Mars terminal UI helper library. It provides the project-facing terminal abstraction and uses the bundled termbox2 backend.

Use nwtui from Mars tools that need terminal interaction. Do not call termbox2 directly from new higher-level code. If a terminal feature is missing, extend the nwtui wrapper and keep backend details below that API.

third_party/termbox2: backend implementation detail for nwtui. It is not a public Mars library API.

See also TOOLBOX_PLAN.md for the TUI and INI roadmap.

nwssl

nwssl is the Mars SSL/TLS compatibility layer. It wraps the bundled MatrixSSL implementation and exposes the API shape expected by Mars components.

Consumers should link the Mars SSL target instead of depending directly on MatrixSSL when they need the project compatibility API.

Database and service libraries

nwflaim

nwflaim documents the bundled FLAIM database library used by Mars services. The source lives under third_party/flaim and is built through the Mars CMake integration.

Use the exported FLAIM targets for database code. Keep local patches small and separate from Mars wrapper changes.

nwxflaim

nwxflaim documents the XML FLAIM companion library from the bundled FLAIM source tree.

Use it only where the XML FLAIM API is required. General Mars database code should use the narrower FLAIM API it actually needs.

Wrapped or vendored third-party libraries

These pages document third-party libraries that are useful project-facing surfaces or long-lived wrapped dependencies. Some vendored packages are intentionally documented under their owning Mars library instead of receiving a standalone public page. For example, iniparser and Unicode tables are internal nwcore details, and termbox2 is an internal nwtui backend.

nwmatrixssl

nwmatrixssl documents the bundled MatrixSSL TLS implementation under third_party/matrixssl.

Prefer the Mars nwssl compatibility library for project code. Use MatrixSSL interfaces directly only in the SSL wrapper or when porting upstream MatrixSSL code.

nwlibsodium

nwlibsodium documents the bundled libsodium cryptographic library under third_party/libsodium.

Use the bundled CMake target instead of assuming a system libsodium dependency. Keep cryptographic API usage isolated and documented at the caller level.

nwowfat

nwowfat documents the bundled libowfat support library under third_party/libowfat.

Mars code should use the CMake target exported by the bundled libowfat integration rather than assuming a system libowfat installation.

Naming rule

The directory names use the nw... prefix for documentation even when the underlying CMake target or upstream project keeps its original name. This keeps Mars-specific documentation grouped and avoids collisions with upstream docs.

NSS userspace adaptation boundary

See ../NSS_IMPORT_NOTES.md for the rule that NSS imports provide semantics and dependency provenance, while Mars NWE provides the userspace storage, xattr, AdminVolume and integration backends.