From 410dd10ffd3270e6f7972f1c9aeb07fb7812fee5 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 21 Oct 2026 12:45:37 +0000 Subject: docs(agents): link plain-text references to the split topic files Co-Authored-By: Claude Sonnet 5.5 --- AGENTS/ARCH/BUILD.md | 7 ++++--- AGENTS/ARCH/DRIVER.md | 4 +++- AGENTS/ARCH/INSTALL.md | 3 ++- AGENTS/ARCH/OVERVIEW.md | 4 ++-- AGENTS/CONVENTIONS.md | 3 ++- AGENTS/EXTENDING.md | 2 +- AGENTS/SUBSYSTEMS.md | 2 +- AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md | 2 +- 8 files changed, 16 insertions(+), 11 deletions(-) (limited to 'AGENTS') diff --git a/AGENTS/ARCH/BUILD.md b/AGENTS/ARCH/BUILD.md index dcad28d..2e4cc69 100644 --- a/AGENTS/ARCH/BUILD.md +++ b/AGENTS/ARCH/BUILD.md @@ -8,7 +8,7 @@ development files to build; NONE supports both outputs. The following commands use Debian/Ubuntu's versioned compiler names: ```bash -# Prepare dependencies using the recommendations in doc/build.md. +# Prepare dependencies using the recommendations in doc/build.md (see DEPENDENCIES.md). cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \ -DCMAKE_C_COMPILER=clang-23 -DCMAKE_CXX_COMPILER=clang++-23 cmake --build build @@ -26,7 +26,8 @@ automatically. Manually linking emitted `.ll` files still requires a C++ driver TRY/CATCH/ENDTRY and bare THROW are compiler extensions. Runtime checks print the source line and error reason to stderr before throwing anonymous exceptions; the final handler in generated main -prints `Unhandled exception. Program terminated.` to stderr and returns 1. -Nightly CI runs compiler tests, including embedded exception execution, on +prints `Unhandled exception. Program terminated.` to stderr and returns 1 +(lowering details: [RUNTIME_CHECKS_EXCEPTIONS.md](../SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md)). +[Nightly CI](NIGHTLY.md) runs compiler tests, including embedded exception execution, on Linux, Windows and macOS with LLVM 23. Platform-specific changes require successful checks on the native runner. diff --git a/AGENTS/ARCH/DRIVER.md b/AGENTS/ARCH/DRIVER.md index 69a2402..49a85be 100644 --- a/AGENTS/ARCH/DRIVER.md +++ b/AGENTS/ARCH/DRIVER.md @@ -1,6 +1,8 @@ # Driver behavior -Driver behavior (`tools/driver/main.cc`): +Driver behavior (`tools/driver/main.cc`). CodeGen-side unit and entry-point invariants are in +[CONVENTIONS/EXCEPTIONS_AND_UNITS.md](../CONVENTIONS/EXCEPTIONS_AND_UNITS.md); diagnostic +style is in [CONVENTIONS/SYMBOLS_AND_ERRORS.md](../CONVENTIONS/SYMBOLS_AND_ERRORS.md). - One or more source files, with optional `-S`, `-o path`, `-r` and `-no-std`; options may appear among inputs. Each stream is parsed independently. INCLUDE paths are relative to the including file, diff --git a/AGENTS/ARCH/INSTALL.md b/AGENTS/ARCH/INSTALL.md index 4c609c5..bf6a1bc 100644 --- a/AGENTS/ARCH/INSTALL.md +++ b/AGENTS/ARCH/INSTALL.md @@ -36,7 +36,8 @@ generate `build/doc/cpsc.1`. The section 1 source is `doc/cpsc.1.md`; section 7 `doc/language/**/*.7.md`. `doc` builds every page, preserving the language category subdirectories, as `.7` on Unix or `.html` on Windows. Sources are discovered with CONFIGURE_DEPENDS; per-page commands regenerate only changed pages. -`cmake/ManualLinks.lua` renders cross-references as man names or local HTML links. +`cmake/ManualLinks.lua` renders cross-references as man names or local HTML links +(manual source rules: [MAN.md](../MAN.md)). Windows `mingw32-make -C build install` builds the HTML manual and invokes `install.ps1` through Windows PowerShell with the build directory and `CMAKE_INSTALL_PREFIX`. The default Windows prefix is the per-user Programs diff --git a/AGENTS/ARCH/OVERVIEW.md b/AGENTS/ARCH/OVERVIEW.md index 6984646..5bb4a86 100644 --- a/AGENTS/ARCH/OVERVIEW.md +++ b/AGENTS/ARCH/OVERVIEW.md @@ -14,7 +14,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), 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.md). Allocation byte sizes are never computed +*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 `sizeof` constant (`TypeSystem::getSizeOfConstant`) folded by the backend. @@ -24,7 +24,7 @@ CScalar/CPointer identities are canonical C types, not pseudocode alias names; native widths and signedness come from sizeof/type traits, while floating formats come from numeric_limits (long double size alone is insufficient). Programs use the compiler's build ABI; cross-target emission is not implemented. EXTERN "C" -declarations call C functions from INCLUDE_OBJ objects (see SUBSYSTEMS.md). +declarations call C functions from INCLUDE_OBJ objects (see [SUBSYSTEMS/EXTERN.md](../SUBSYSTEMS/EXTERN.md)). CTypeGen handles typed numeric conversions, casts, native arithmetic and I/O. Crossing C/pseudocode domains requires a cast, including literals. C arithmetic uses C++ promotions, except that / always returns pseudocode REAL. diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md index b764915..5bf7c6e 100644 --- a/AGENTS/CONVENTIONS.md +++ b/AGENTS/CONVENTIONS.md @@ -1,7 +1,8 @@ # Load-bearing conventions These invariants span modules. Violating any of them breaks code you didn't touch. -(Overview and build instructions: `ARCH.md`.) The details are split by topic under +(Overview and build instructions: [ARCH/OVERVIEW.md](ARCH/OVERVIEW.md), +[ARCH/BUILD.md](ARCH/BUILD.md).) The details are split by topic under `AGENTS/CONVENTIONS/`. - [LEXING.md](CONVENTIONS/LEXING.md) — English-only project text, raw `int` tokens, diff --git a/AGENTS/EXTENDING.md b/AGENTS/EXTENDING.md index 668941b..5728ac5 100644 --- a/AGENTS/EXTENDING.md +++ b/AGENTS/EXTENDING.md @@ -1,6 +1,6 @@ # Extension recipes -Step-by-step patterns for adding features. Read `CONVENTIONS.md` first — every recipe +Step-by-step patterns for adding features. Read [CONVENTIONS.md](CONVENTIONS.md) first — every recipe below assumes those invariants. **New statement:** token in `Lexer.h` enum + keyword match in `Lexer.cc`'s if-chain → diff --git a/AGENTS/SUBSYSTEMS.md b/AGENTS/SUBSYSTEMS.md index a11cf33..d3a7dba 100644 --- a/AGENTS/SUBSYSTEMS.md +++ b/AGENTS/SUBSYSTEMS.md @@ -1,7 +1,7 @@ # Subsystem notes Deep-dives on the CodeGen helper subsystems, split by topic under `SUBSYSTEMS/`. -(Invariants: `CONVENTIONS.md`; known bugs: `PITFALLS.md`.) +(Invariants: [CONVENTIONS.md](CONVENTIONS.md); known bugs: [PITFALLS.md](PITFALLS.md).) - [Arrays](SUBSYSTEMS/ARRAYS.md): `ArrayHandler` storage, checked indexing, array parameters and array OUTPUT. diff --git a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md index c80f825..8cec5e9 100644 --- a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md +++ b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md @@ -51,5 +51,5 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Related: [class lifetime](CLASS - Native binaries require the C++ runtime; EmbeddedRunner defines its statically linked ABI symbols with ORC `absoluteSymbols`, while LLJIT with JITLink manages unwind frames (generic EH-frame on Linux, compact-unwind or EH-frame on macOS, COFF SEH registration - on Windows x86_64). + on Windows x86_64); see [ARCH/EMBEDDED_RUNNER.md](../ARCH/EMBEDDED_RUNNER.md). - Nightly CI exercises embedded exception execution on all three platforms. -- cgit v1.3.1-4-g156e