240 lines
11 KiB
Markdown
240 lines
11 KiB
Markdown
# Third-party dependencies
|
|
|
|
This directory is for mostly external building blocks that are built or linked by
|
|
mars-nwe but are not project-specific service forks. Code here should normally
|
|
be accessed through a mars-nwe facade or subsystem instead of being included
|
|
from endpoint/provider code directly.
|
|
|
|
## CMake ownership
|
|
|
|
The root `CMakeLists.txt` enters `third_party/` once. This directory owns
|
|
bundled dependency checks, local target names, build-policy cache variables and
|
|
private wrapper targets. Source libraries and tools should consume targets such
|
|
as `mars_nwe::yyjson`, `mars_nwe::iniparser`, `mars_nwe::unicode_tables` and
|
|
`mars_nwe::termbox2` instead of hard-coding paths into individual
|
|
`src/*/CMakeLists.txt` files.
|
|
|
|
Optional FLAIM is a special case because it depends on `mars_nwe::ssl`, which is
|
|
created below `src/ssl`. The third-party CMake file still owns FLAIM setup via
|
|
`mars_nwe_add_flaim_third_party()`, but the root calls that function only after
|
|
`add_subdirectory(src)` when `ENABLE_DIRECTORY` is enabled.
|
|
|
|
## yyjson
|
|
|
|
The salvage metadata backend uses the bundled yyjson submodule for JSON
|
|
read/write support. The submodule is required and is linked statically into the
|
|
mars-nwe server targets that use salvage metadata.
|
|
|
|
Setup:
|
|
|
|
```sh
|
|
git submodule update --init --recursive third_party/yyjson
|
|
```
|
|
|
|
The third-party CMake owner builds a private PIC static target named
|
|
`mars_nwe::yyjson` from the pinned source files. Reader and writer support stay
|
|
enabled; JSON5/non-standard support, utilities and the incremental reader are
|
|
disabled for the mars-nwe build.
|
|
|
|
|
|
## termbox2
|
|
|
|
`third_party/termbox2` is the pinned MIT-licensed terminal backend for the
|
|
future `libnwtui` layer. It is kept as an external submodule and pinned by
|
|
`update-submodules.sh` to release tag `v2.5.0`
|
|
(`9b5a5da862c06c554148c14fd38d2f796be22d57`).
|
|
|
|
Only `src/nwtui` may include `termbox2.h` directly. Tools such as `nwsetup`,
|
|
`nwfiler` and `nwsalvage` must use the project-owned `nwtui_*` API instead.
|
|
|
|
## iniParser
|
|
|
|
`third_party/iniparser` is the pinned MIT-licensed INI reader/writer backend for
|
|
the first `libnwcore` INI wrapper. It is kept as an external submodule and
|
|
pinned by `update-submodules.sh` to release tag `v4.2.6`
|
|
(`4bef811283e0ec1658c60e09950bd5a1ddc92e4b`).
|
|
|
|
Server and tool code must use `nw_ini_*` from `libnwcore`; they must not include
|
|
`iniparser.h` directly. This keeps the backend replaceable and keeps `nw.ini`
|
|
read/write policy in one place.
|
|
|
|
## Planned: libowfat
|
|
|
|
libowfat is the planned hard bundled dependency, initially for the
|
|
tinyldap-derived `mars-tinyldap` / `nwdirectory` work. It should live under
|
|
`third_party/libowfat`, not at the repository root, and should be treated as a
|
|
fixed third-party building block in the same sense as yyjson is fixed for
|
|
salvage metadata. mars-nwe core code may also use it later when there is a
|
|
concrete, reviewed helper use.
|
|
|
|
The reviewed archive is `libowfat-0.34.tar.xz`. Its README describes libowfat
|
|
as general-purpose APIs extracted from Dan Bernstein-style software and
|
|
reimplemented under GNU GPL Version 2 with no later-version grant. Record that
|
|
GPL-2.0-only license and the exact source/version in
|
|
`third_party/libowfat/README.mars-nwe.md` when the dependency is imported.
|
|
|
|
The first mars-nwe integration should provide a real CMake target, for example:
|
|
|
|
```text
|
|
OWFAT::owfat
|
|
```
|
|
|
|
Do not rely on libowfat's original Makefile as the long-term build path. The
|
|
CMake import should be usable by both the standalone tinyldap-derived build and
|
|
the mars-nwe superbuild. The first direct consumers should be the
|
|
`mars-tinyldap`/`nwdirectory` compatibility code and any small wrapper needed for
|
|
that integration. Later mars-nwe core consumers may use libowfat directly when a
|
|
real helper need exists; avoid adding libowfat includes to unrelated dispatch
|
|
code merely because the library is bundled.
|
|
|
|
|
|
The mars-nwe build may expose a renamed shared library for the bundled libowfat
|
|
import. The planned artifact name is `libnwowfat`, with the import still
|
|
recorded as libowfat 0.34 in `third_party/libowfat/README.mars-nwe.md`. Keep
|
|
local changes limited to build, CMake, portability, and naming fixes unless a
|
|
later patch documents a small upstreamable bug fix.
|
|
|
|
Relevant libowfat areas for tinyldap are expected to include `byte`, `buffer`,
|
|
`fmt`, `scan`, `str`, `stralloc`, `uint`, `open`, `socket`, and possibly `io` or
|
|
`cdb`, depending on how much of the original tinyldap code is kept.
|
|
|
|
## Superseded candidate: wolfSSL
|
|
|
|
wolfSSL was previously considered as the fixed TLS implementation. For the
|
|
current GPL-2.0-only dependency direction, MatrixSSL is the preferred candidate
|
|
to evaluate first. Do not import wolfSSL by default. It may only be reconsidered
|
|
in a later explicit dependency-review patch that pins a GPL-2.0-compatible
|
|
release or documents a commercial-license path.
|
|
|
|
## Planned: MatrixSSL
|
|
|
|
MatrixSSL is the planned GPL-2.0-compatible crypto/TLS candidate to evaluate for
|
|
the future FLAIM CCS/NICI compatibility layer and possible later TLS needs. If
|
|
adopted, it should live under `third_party/matrixssl` as a mars-nwe-maintained
|
|
fork/import with a pinned upstream/fork revision and explicit license notes.
|
|
|
|
The MatrixSSL import must not rely on the original Makefiles as the long-term
|
|
mars-nwe build path. Add a native CMake build that works both standalone and as
|
|
a mars-nwe subdirectory. Expected targets are along these lines:
|
|
|
|
```text
|
|
NWMatrixSSL::crypto
|
|
NWMatrixSSL::tls
|
|
```
|
|
|
|
`NWMatrixSSL::crypto` is the important first target for `libnwssl` and the
|
|
Flaim CCS/NICI compat backend. `NWMatrixSSL::tls` may remain disabled until a
|
|
real mars-nwe TLS consumer needs it. The built library should use a mars-nwe
|
|
name such as `libnwmatrixssl` to avoid collisions with system MatrixSSL
|
|
packages.
|
|
|
|
FLAIM should not call MatrixSSL APIs directly. Keep the layering as:
|
|
|
|
```text
|
|
libflaim -> CCS/NICI compatibility layer -> MatrixSSL crypto backend
|
|
```
|
|
|
|
OpenSSL remains out of the default dependency policy. Any old FLAIM/FTK
|
|
OpenSSL-facing network code should be disabled or isolated inside the FLAIM
|
|
import, not exposed to mars-nwe modules.
|
|
|
|
The normal mars-nwe consumer target should be `libnwssl`, not MatrixSSL directly.
|
|
`libnwssl` owns TLS facade APIs and the CCS/NICI compatibility API used by FLAIM;
|
|
it links to `libnwmatrixssl` underneath. If the old FLAIM/FTK network code cannot
|
|
be disabled, `libnwssl` may also provide a private OpenSSL-compat shim for that
|
|
specific import path. That shim is not a public mars-nwe TLS API and must not be
|
|
used by LDAP, provider IPC, or service code.
|
|
|
|
The preferred FLAIM integration should not patch FLAIM source call sites simply
|
|
to replace NICI/CCS or OpenSSL includes. `libnwssl` may provide private
|
|
compatibility headers under `include/nwssl/private/` and the `libnwflaimtk` /
|
|
`libnwflaim` targets may add that directory privately so legacy includes resolve
|
|
through mars-nwe wrappers:
|
|
|
|
```text
|
|
include/nwssl/private/nici.h
|
|
include/nwssl/private/openssl/*.h
|
|
```
|
|
|
|
Those headers are private to the FLAIM import path. They must not be installed
|
|
or used as the public TLS/crypto API for mars-nwe modules.
|
|
|
|
|
|
## Planned: libflaim
|
|
|
|
libflaim is the planned bundled persistent storage engine for the future
|
|
`libnwds` store. It belongs under `third_party/libflaim` because it is a
|
|
storage engine dependency, not a mars-nwe service fork.
|
|
|
|
The import should be mars-nwe-maintained. The initial source may come from the
|
|
SourceForge FLAIM code base or from a distro-vetted source package such as the
|
|
openSUSE `libflaim-4.9.1046` source package. The exact source, version, distro
|
|
patches, licenses, and local changes must be documented in
|
|
`third_party/libflaim/README.mars-nwe.md`.
|
|
|
|
The original FLAIM build system should be replaced with a real CMake build, not
|
|
wrapped from the mars-nwe build. The uploaded r1112 trunk snapshot already has
|
|
Autotools files, but those should be treated as source inventory and build-check
|
|
reference material. The resulting tree should build both as a standalone library
|
|
project and as a mars-nwe subdirectory, exposing normal CMake targets.
|
|
|
|
If old FLAIM/FTK code requires OpenSSL-facing build paths, prefer disabling those
|
|
paths for the initial classic `FLAIM::flaim` target. If a compatibility bridge is
|
|
unavoidable, it should be a private `third_party/libflaim` CMake option using
|
|
the `libnwssl` OpenSSL-compat shim backed by `libnwmatrixssl`, not a new public
|
|
OpenSSL/LibreSSL TLS backend for mars-nwe. Keep the shim limited to the symbols
|
|
used by the imported FLAIM/FTK source rather than growing a general OpenSSL clone.
|
|
|
|
The first required targets are expected to be:
|
|
|
|
```text
|
|
NWFlaim::ftk # libnwflaimtk
|
|
NWFlaim::flaim # libnwflaim
|
|
```
|
|
|
|
SQL FLAIM, XFLAIM, tools, tests, generated documentation, package metadata,
|
|
Windows projects, NetWare NLM files, Java/C# bindings, and other legacy build
|
|
outputs should remain optional/off by default until mars-nwe actually needs
|
|
them.
|
|
|
|
FLAIM is C++ code. mars-nwe C components should not include FLAIM C++ headers
|
|
directly. Access should go through the future `libnwds` C API. The
|
|
imported FLAIM libraries should be renamed to `libnwflaimtk` and `libnwflaim`
|
|
to avoid collisions with a system FLAIM installation.
|
|
|
|
## Logging backend policy
|
|
|
|
Logging is no longer planned as a third-party backend import. The previously
|
|
considered zlog dependency is Apache-2.0 and must not be vendored into the
|
|
GPL-2.0-only core. mars-nwe logging should go through `include/nwlog.h` and
|
|
small in-tree backends owned by the project.
|
|
|
|
## Forked components are not third_party
|
|
|
|
Components that are forked and integrated as mars-nwe services should live at the
|
|
repository root, following the existing pattern used by `admin`, `dosutils`,
|
|
`mail`, and `smart`.
|
|
|
|
The planned tinyldap fork is such a component. It should live as
|
|
`mars-tinyldap/` at the repository root. Its standalone identity remains
|
|
`tinyldap`, while the mars-nwe integration builds the project-facing
|
|
`nwdirectory` service and `libnwdirectory` library. The fork should gain a real
|
|
CMake build that works both standalone under the tinyldap name and as a mars-nwe
|
|
subdirectory.
|
|
|
|
Keep the storage migration staged. LDAPv2/LDAPv3 and schema-import work should
|
|
first run on tinyldap's original flatfile/mmap/journal backend, with CTests over
|
|
TCP. Later, add a mars-nwe FLAIM backend as a parallel source set selected by
|
|
CMake. The FLAIM files may provide the same exported storage function names as
|
|
the flatfile files, so the LDAP/server code does not change while the backend is
|
|
swapped. Do not break the flatfile backend while adding the mars-nwe-specific
|
|
FLAIM backend.
|
|
|
|
The inspected tinyldap snapshot has one handwritten Makefile that builds ASN.1,
|
|
LDAP, LDIF, auth, storage, tiny TLS, server, client, index, ACL, conversion, and
|
|
test utilities. The mars-nwe CMake conversion should split those groups into
|
|
explicit libraries/targets instead of preserving the old monolithic `all` target.
|
|
The original tiny TLS code should be disabled or isolated for the integrated
|
|
`nwdirectory` target; LDAP/LDAPS/StartTLS in mars-nwe should use `nwtls` backed
|
|
by MatrixSSL.
|