a1d1234859
doc/librarys/nwcore/README.md: completely rewrite — old content described libnwnss (Unicode, UTC, GUID, WIO, FSM, latch, stdio, library/*, nss/lib, sharedsrc) as if it were libnwcore. libnwcore builds only core.c, nwlog.c, ini.c and exposes only core.h and ini.h. Add correct dependency chain diagram showing libnwcore is independent of libnwnss. TODO.md: - "shared libnwcore/libnwfs helpers" for salvage/deleted metadata → libnwnss/libnwfs (2 occurrences) - "libnwcore/libnwfs" for metadata snapshot helpers → libnwnss/libnwfs - "src/core/" and "include/core/" for NSS imports → src/nwnss/ and include/nwnss/ REDESIGN.md: - Architecture status table: "libnwcore/libnwfs helpers" for NSS-shaped salvage → libnwnss/libnwfs - Salvage snapshot section: nwcore_salvage_snapshot → nwnss_salvage_snapshot; "libnwcore/libnwfs-style helpers" → libnwnss/libnwfs Note: third_party/unicodeTables/COPYRIGHT.md also says "libnwcore" but that file lives in a submodule and cannot be staged here. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.ccompanions. - 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 fornwtui. 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.