46031df872
Merge 15 files into 3 consolidated docs and update all cross-references: - doc/NSS_IMPORT_NOTES.md: merges NSS_USERSPACE_ADAPTATION.md, NSS_PUBLIC_CORE_AUDIT.md, NSS_NAMESPACE_AUDIT.md - doc/TOOLBOX_PLAN.md: merges TUI_TOOLBOX_PLAN.md, NWCORE_INI_PLAN.md - doc/DIRECTORY_AND_ADMIN_PLAN.md: merges DIRECTORY_STACK_PLAN.md, NWADMIN_CLIENT_PLAN.md - doc/librarys/README.md: inlines 7 one-page stubs (nwtui, nwssl, nwflaim, nwxflaim, nwmatrixssl, nwlibsodium, nwowfat), deletes stub subdirs - REDESIGN.md: absorbs KERNEL_REFERENCE_AUDIT.md into the transport/SPX section; adds Table of Contents after the architecture status table - CLAUDE.md, AI.md, doc/README.md, doc/librarys/nwfs/README.md: all cross-references updated to new file names Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# 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](nwcore/README.md): common Mars helpers — INI reader/writer, logging
|
|
facade. Does not contain NSS helpers; those are in `libnwnss`.
|
|
- [nwnss](../NSS_IMPORT_NOTES.md): imported NSS userspace provider — namespace,
|
|
XAttr, trustee, quota, salvage and AdminVolume semantics. Host-FS/OtherFS
|
|
policy lives in parallel `*Userspace.c` companions.
|
|
- [nwfs](nwfs/README.md): 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](../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`](../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.
|