From bb1244aaef910579d829eb1563365479860ae7e1 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 21 Oct 2026 12:49:21 +0000 Subject: docs(agents): collapse duplicated passages into single-home links Co-Authored-By: Claude Sonnet 5.5 --- AGENTS/ARCH/DRIVER.md | 2 +- AGENTS/ARCH/EMBEDDED_RUNNER.md | 2 +- AGENTS/ARCH/INSTALL.md | 4 +++- AGENTS/ARCH/LINKING.md | 2 +- AGENTS/ARCH/NIGHTLY.md | 10 +++++----- AGENTS/ARCH/OVERVIEW.md | 2 +- 6 files changed, 12 insertions(+), 10 deletions(-) (limited to 'AGENTS/ARCH') diff --git a/AGENTS/ARCH/DRIVER.md b/AGENTS/ARCH/DRIVER.md index 49a85be..af3925a 100644 --- a/AGENTS/ARCH/DRIVER.md +++ b/AGENTS/ARCH/DRIVER.md @@ -35,7 +35,7 @@ style is in [CONVENTIONS/SYMBOLS_AND_ERRORS.md](../CONVENTIONS/SYMBOLS_AND_ERROR compilation, such as file I/O errors, use `fatal error:`. The driver prints `compilation terminated.` once on compilation failure, including argument errors. Multi-input lexer/parser/codegen diagnostics append the source path after the line number; - Diagnostics.h keeps single-input diagnostic text unchanged. + single-input diagnostics (Diagnostics.h) do not append it. Execution-stage failures do not print that line. Check the exit code rather than grepping stderr. - Successful compilation overwrites the output, but paths aliasing any input source diff --git a/AGENTS/ARCH/EMBEDDED_RUNNER.md b/AGENTS/ARCH/EMBEDDED_RUNNER.md index 7fe0780..0899254 100644 --- a/AGENTS/ARCH/EMBEDDED_RUNNER.md +++ b/AGENTS/ARCH/EMBEDDED_RUNNER.md @@ -30,6 +30,6 @@ Initialize the JIT before looking up `main` and deinitialize while its code is still mapped. Execution failures return 1 without `compilation terminated.`. No external runner or PATH lookup is used; `-r` alone runs in memory. - Platform-specific changes require native CI verification. + Platform-specific changes require native CI verification ([BUILD.md](BUILD.md)). The embedded JIT lazily loads the captured C++ standard-library and compiler-support archives using StaticLibraryDefinitionGenerator. Members defining exception ABI or unwind symbols are filtered so all exception frames use the host runtime; additional host ABI functions are exposed explicitly. Archive buffers own their extracted bytes for the JIT lifetime. diff --git a/AGENTS/ARCH/INSTALL.md b/AGENTS/ARCH/INSTALL.md index bf6a1bc..fa21bac 100644 --- a/AGENTS/ARCH/INSTALL.md +++ b/AGENTS/ARCH/INSTALL.md @@ -2,7 +2,8 @@ On Linux, `make -C build install` builds the manual and calls the POSIX `install.sh` to copy `cpsc` into `CMAKE_INSTALL_PREFIX/bin` and all manuals into -`CMAKE_INSTALL_PREFIX/share/cpsc/man/man1` and `man7` (default prefix `/usr/local`). +`CMAKE_INSTALL_PREFIX/share/cpsc/man/man1` and `man7` (default prefix `/usr/local`); +section 7 pages are installed together in `man7` without category subdirectories. Linux man-db registration appends a deduplicated MANDATORY_MANPATH entry to `/etc/manpath.config` or `/etc/man_db.conf` as root, or `~/.manpath` as a user. macOS root registration uses `/usr/local/etc/man.d/cpsc.conf`; user installation @@ -47,6 +48,7 @@ The release target explicitly passes the configured Windows flag to host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `doc/language/**/*.html`, `install.ps1` and `LICENSE` as `build/cpsc-VERSION-Windows-ARCH.zip` using CMake's default Deflate compression. Unix retains `.tar.xz`, the POSIX installer and the man pages. +Generated files and release packages preserve the language category layout. Linux smoke tests can configure an isolated build with `-DWIN32=TRUE` to exercise HTML/ZIP packaging; the resulting renamed Linux executable is only a test fixture, not a usable Windows release. diff --git a/AGENTS/ARCH/LINKING.md b/AGENTS/ARCH/LINKING.md index d0efe81..7bf1ecd 100644 --- a/AGENTS/ARCH/LINKING.md +++ b/AGENTS/ARCH/LINKING.md @@ -30,7 +30,7 @@ prefix, and leaves LLVM itself installed. Source and build caches are versioned; the resulting local `lib/cmake/lld` takes precedence over shared system packages. The helper's build-time linker can use the installed LLVM dylib; cpsc still links the LLD archives and static LLVM components. -Both macOS configurations explicitly select the SDK with `CMAKE_OSX_SYSROOT` +Both macOS builds (the LLD helper and cpsc) explicitly select the SDK with `CMAKE_OSX_SYSROOT` before compiler detection, so imported SDK include paths do not precede libc++. The nightly macOS job's helper caching and LLVM bottle checks are described in [NIGHTLY.md](NIGHTLY.md#macos-lld-helper-and-desktop-caches). diff --git a/AGENTS/ARCH/NIGHTLY.md b/AGENTS/ARCH/NIGHTLY.md index 8afb53e..00bbe4a 100644 --- a/AGENTS/ARCH/NIGHTLY.md +++ b/AGENTS/ARCH/NIGHTLY.md @@ -17,7 +17,7 @@ the current working directory on startup; macOS keeps the compiler inside the ap Native runner tests check prefilled input, EOF, diagnostics, output before exit, stopping and restart. Portable packages are checked for the desktop executable, compiler and notices, then run with toolchain directories removed from PATH. -The publish job requires both Bundle packages alongside the original four packages. +The publish job requires both Bundle packages alongside the four compiler and VSIX packages. See [`bundle/AGENTS/DEVELOPMENT.md`](../../bundle/AGENTS/DEVELOPMENT.md) for the shared editor and build details. The Linux compiler and plugin jobs use Ubuntu 24.04 x86_64; the macOS compiler @@ -35,7 +35,8 @@ packaged binary and checks native generation plus `.ll` output without tool look Windows system directories, excluding MSYS2 and LLVM. The macOS check also verifies arm64 and rejects non-system dynamic libraries. The plugin uses Node.js 22, `npm ci --ignore-scripts` and -`npm run package`, then checks VSIX contents. Each job retains its checked package +`npm run package` (which runs the plugin's syntax checks and tests before packaging), +then checks VSIX contents. Each job retains its checked package as a separate Actions artifact for one day, failing if the package is missing. Compiler jobs enable BUILD_TESTING and run all CTest cases with the push SHA as seed before @@ -50,7 +51,7 @@ Compiler and VSIX package names use HEAD's UTC commit timestamp and short ID. The VSIX internal version is `YYYYMMDD.HHMMSS.0+commit`, with leading zeros removed from the numeric time component. Before committing workflow changes, run actionlint, simulate release API calls, and smoke-test the packages locally; -do not modify the real release for local verification. +do not contact or modify the real release for local verification. ## macOS LLD helper and desktop caches @@ -64,5 +65,4 @@ compiler/library content, workspace path and helper script hash. No fallback key restores a build from a different toolchain. Homebrew updates and the LLVM archive symbol check still run before cache lookup. Windows and macOS desktop jobs cache compiled Rust dependencies after selecting the toolchain, including on failure; -project crates rebuild with the current compiler payload. Rust release optimization -and archive compression settings are unchanged. +project crates rebuild with the current compiler payload. diff --git a/AGENTS/ARCH/OVERVIEW.md b/AGENTS/ARCH/OVERVIEW.md index 5bb4a86..820c5bb 100644 --- a/AGENTS/ARCH/OVERVIEW.md +++ b/AGENTS/ARCH/OVERVIEW.md @@ -12,7 +12,7 @@ files ──> Lexer ──> Parser ──> vector> ──> C ``` Fixed value representation (ABI — much code infers types backwards from these): -INTEGER = `i64`, REAL = `double`, BOOLEAN = `i1`, CHAR = `i8`. STRING is the standard-library class `%record.STRING`, owning a std::string handle; C_STRING is a raw NUL-terminated pointer. User-defined types (§4): enum = `i64` (0-based ordinal), +INTEGER = `i64`, REAL = `double`, BOOLEAN = `i1`, CHAR = `i8`. STRING is the standard-library class `%record.STRING` (not a builtin pointer type), owning a std::string handle; C_STRING is a raw NUL-terminated pointer. User-defined types (§4): enum = `i64` (0-based ordinal), pointer = opaque `ptr`, record = named struct `%record.NAME`. Enums and pointers are LLVM-identical to INTEGER/C_STRING **by design** — their identity lives in the type *name*, enforced upstream (see [CONVENTIONS/TYPES.md](../CONVENTIONS/TYPES.md)). Allocation byte sizes are never computed host-side: the module has no DataLayout string, so every allocation size is a null-GEP -- cgit v1.3.1-4-g156e