mars_nwe/mars-nwe
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 2 Wiki Activity
Files
ec2b645994feb8da75faf5e4fb28594db0dd7dfd
mars-nwe/AGENTS.md
T
Mario Fetka dd095ec7fa
Source release / source-package (push) Successful in 1m26s
Details
docs: replace AI handoff notes with AGENTS
2026-06-22 08:33:37 +02:00

6.6 KiB
Raw Blame History

AGENTS.md

This file gives coding agents the repository-specific rules for working on MARS-NWE. It is not a changelog or handoff log.

Start Here

  • Default language with Mario is German. Repository documentation stays English unless the existing file is already German.
  • Treat this repository as the root/superproject. Most sibling mars-* projects are mounted here as submodules.
  • Before changing namespace, salvage, transport, directory/NDS, NSS or dependency code, read the root TODO.md, REDESIGN.md, ENDPOINTS.md and the relevant focused files under doc/.
  • Prefer out-of-tree builds. The shared local build directory /home/mario/mars/mars-nwe-build is a maintainer build and should be configured with -DMAINTAINER_BUILD=ON.
  • Do not patch GitHub-pinned external submodules (yyjson, termbox2, iniparser) for local warnings. Maintained mars-* mirrors may be patched and pushed; after that update the root gitlink with ./update-submodules.sh.

Documentation Ownership

  • TODO.md is the active backlog and short implementation dashboard.
  • REDESIGN.md is the durable architecture/design record, not patch chronology.
  • ENDPOINTS.md owns NCP endpoint audit tables. Always record both decimal and wire/code hex notation.
  • doc/*.md files own focused audits and roadmaps.
  • AGENTS.md owns repository-specific agent workflow rules only.

When a TODO is actually finished, remove it from TODO.md in the same patch and record durable design outcome in REDESIGN.md or the matching focused doc/ file. Do not move unfinished work out of TODO.md only because architecture is documented elsewhere.

Build

Maintainer build used in this workspace:

cmake -S /home/mario/mars/mars-nwe \
  -B /home/mario/mars/mars-nwe-build \
  -DMAINTAINER_BUILD=ON \
  -DMARS_NWE_BUILD_TESTS=ON \
  -DMARS_NWE_BUILD_NWFS_TESTS=ON \
  -DENABLE_DIRECTORY=ON \
  -DENABLE_DEBUG_BUILD=ON
cmake --build /home/mario/mars/mars-nwe-build -j2

Normal user build:

cmake -S . -B build
cmake --build build
sudo cmake --install build

Useful options:

Option Default Purpose
MAINTAINER_BUILD OFF Maintainer-only helpers and diagnostics; also forces new DOS utilities.
ENABLE_DEBUG_BUILD OFF Add debug compiler flags.
ENABLE_DEBUG OFF Compile legacy XDPRINTF / DO_DEBUG logging paths.
MARS_NWE_BUILD_TESTS OFF Build optional integration tests.
MARS_NWE_BUILD_NWFS_TESTS OFF Build libnwfs unit tests.
ENABLE_DIRECTORY OFF Build optional nwdirectory / TinyLDAP subsystem.
MARS_NWE_BUILD_MATRIXSSL_PROGRAMS OFF Build MatrixSSL example/test/helper programs.

Tests

ctest --test-dir /home/mario/mars/mars-nwe-build -LE networked --output-on-failure
ctest --test-dir /home/mario/mars/mars-nwe-build --output-on-failure

Networked tests may be run when the local server/client setup is available. Generated test artifacts are part of the result and should be inspected when a test changes user-visible behavior.

Unicode Table Generation

Normal builds consume committed .TAB files from third_party/unicodeTables/TAB/unitables.

Maintainer builds regenerate NSS-compatible .TAB files into the build tree via the mars_nwe_unicode_nss_unitables ALL target. This does not modify the submodule.

To intentionally update committed generated tables, work inside third_party/unicodeTables and use:

./regenerate-tabs.sh
./regenerate-tabs.sh --unicode-version 17.0.0 --commit

Architecture Rules

  • Current default compatibility target is NetWare 1.x/2.x/3.x. NetWare 4.x/NDS endpoints are partial or guarded unless a concrete compatibility path requires them.
  • NCP notation in docs and comments must include both decimal and hex, for example decimal 22/35 == wire/code 0x16/0x23.
  • New namespace/NWFS work must not add new magic return(-1) / return(-2) process handoff paths. Use the audit in doc/HANDOFF_AUDIT.md and provider names in include/ncp_endpoint.h.
  • New logging should use nwlog_* semantic levels 1=error, 2=warn, 3=info, 4=debug, 5=trace. nwlog_detail() is maintainer-only. Do not add zlog or any Apache-2.0 dependency to GPL-2.0-only core code.
  • Do not add new direct curses.h users. Future interactive tools go through nwtui/nwi18n and the nwtoolbox applet model.
  • Production daemons must not depend on the TUI stack.
  • TCP/IP belongs under nwtransport; do not add a separate TCP daemon.

NSS Direction

The former src/nwnss / include/nwnss / tests/nwnss staging tree has been removed. Future NSS work is a root-level nss/ import with provenance-preserving layout:

  • public_core/library/... -> nss/library/...
  • public_core/comn/... -> nss/comn/...
  • public_core/lsa/... -> nss/lsa/...
  • shared/sdk/include/... -> nss/include/include/...
  • shared/sdk/internal/... -> nss/include/internal/...
  • shared/sdk/public/... -> nss/include/public/...
  • shared/sdk/comnSA/... -> nss/include/comnSA/...

Imported original NSS files should stay original-like. Userspace adaptations belong in role-specific companions beside the original file:

  • *Runtime.c/.h for kernel/runtime primitive replacement.
  • *Userspace.c/.h for libnwfs/Mars-NCP/OtherFS/HostFS adapter boundaries.
  • *Fuse.c/.h for future FUSE mount callbacks.
  • *Io.c/.h for concrete pread/pwrite block/image I/O.

Do not route real NSS block/image I/O through VirtualIO. VirtualIO is management/template data-stream infrastructure. FUSE is a presentation/mount layer and must not become the lower block I/O implementation.

Directory/NDS Work Order

  • Keep TinyLDAP/nwdirectory on the existing flatfile/mmap/journal backend while adding LDAPv2/LDAPv3 behavior tests.
  • Do not combine LDAP compatibility work with the FLAIM storage-engine swap.
  • Add libnwnds and console-only nwsetup after flatfile LDAP behavior is testable.
  • Add FLAIM storage later as a selected parallel backend source set exporting the same storage function names as the flatfile files.

Useful References

  • TODO.md - active backlog.
  • REDESIGN.md - durable architecture.
  • ENDPOINTS.md - NCP endpoint audit.
  • doc/NSS_IMPORT_NOTES.md - NSS import notes and boundaries.
  • doc/NWFS_SALVAGE_COMPRESSION_TOOLS.md - salvage/compression/tool plan.
  • doc/HANDOFF_AUDIT.md - nwconn/nwbind handoff audit.
  • doc/TOOLBOX_PLAN.md - terminal UI and shared INI tooling.
  • doc/DIRECTORY_AND_ADMIN_PLAN.md - directory/admin roadmap.
  • doc/LOG_LEVEL_AUDIT.md - logging level audit.
  • /home/mario/mars/nss - local original NSS reference source tree.
Reference in New Issue View Git Blame Copy Permalink