From 7beb5fe687431ecc6b5e79379284cbaa898f3776 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 14 Oct 2026 09:32:08 +0000 Subject: docs(toolchain): document LLVM and Clang 23 requirements Update build and native-link examples, PATH version-check rules and LLVM API guidance. Record Linux verification and retain the Windows/macOS verification limits. Co-Authored-By: Claude Fable 5.1 --- AGENTS/ARCH.md | 39 +++++++++++++++++++++++---------------- AGENTS/EXTENDING.md | 2 +- AGENTS/PITFALLS.md | 6 +++--- 3 files changed, 27 insertions(+), 20 deletions(-) (limited to 'AGENTS') diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md index 6901c19..178a8a6 100644 --- a/AGENTS/ARCH.md +++ b/AGENTS/ARCH.md @@ -1,7 +1,8 @@ # Architecture `cpsc` compiles CIE A-Level 9618 pseudocode to LLVM IR. Classic three-stage -Kaleidoscope-style design, C++17, built with LLVM 18. Execution is selected at +Kaleidoscope-style design, C++17, built with LLVM 23 and Clang 23. CMake rejects +other major versions and non-Clang compilers. Execution is selected at build time: external lli, an embedded static LLVM engine, or disabled. ``` @@ -38,12 +39,12 @@ development libraries to build; NONE still generates IR. Native binaries remain ```bash # Prepare dependencies using the recommendations in doc/build.md. cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \ - -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ + -DCMAKE_C_COMPILER=clang-23 -DCMAKE_CXX_COMPILER=clang++-23 cmake --build build build/cpsc prog.cps -o prog.ll # default without -o: prog.ir beside the source build/cpsc prog.cps -r # execute using the selected build mode build/cpsc prog.cps -r -o prog.ir # save IR, then run it -clang++-18 prog.ll -o prog && ./prog +clang++-23 prog.ll -o prog && ./prog ``` `doc/build.md` recommends which packages to install and which to download; @@ -55,8 +56,11 @@ under the build directory are also searched. The shared reports missing required dependencies. Compilers, make, LLVM, support libraries, Pandoc, Git and installer/relocation tools use the same lookup policy. System-only and mixed installations are supported. Local dependencies override cached system -paths. Build tools are resolved before `project()` enables compiler checks; -compiler information is refreshed when the selected executable changes. +paths except for supplied compilers. Cached or explicit CMake compiler paths and +initial CC/CXX selections are preserved and validated; default discovery prefers +clang-23/clang++-23, then unversioned clang/clang++. Build tools are resolved before +`project()` enables compiler checks; compiler information is refreshed when the +selected executable changes. Platform modules relocate package paths only inside the extraction directory; Homebrew bottles also receive local Cellar/opt links and Mach-O relocation/signing. Package hashes skip unchanged extractions; a changed package set rebuilds the @@ -65,10 +69,10 @@ not to CMake. The Windows Pandoc ZIP is downloaded directly from its official release because MSYS2 has no Pandoc package. Only the Linux build is verified. Generated IR uses the C++ exception ABI; native binaries must link its runtime -(use `clang++-18`). TRY/CATCH/ENDTRY and bare THROW are compiler extensions. +(use `clang++-23`). TRY/CATCH/ENDTRY and bare THROW are compiler extensions. Runtime checks throw anonymous exceptions; the final handler in generated main prints `Unhandled exception. Program terminated.` to stdout and returns 1. -Exception execution is verified on Linux with LLVM 18; Windows/macOS are unverified. +Exception execution is verified on Linux with LLVM 23; Windows/macOS are unverified. Driver behavior (`tools/driver/main.cc`): @@ -91,8 +95,11 @@ Driver behavior (`tools/driver/main.cc`): (including symlinks/hard links) are rejected. - In PATH mode, `-r` executes PATH's `lli` using LLVM Support process APIs, with inherited stdin/stdout/stderr and no shell. Missing lli is rejected before - compiling or writing output. Process-launch/crash failures return 1. `-r` - alone uses temporary IR removed on return, including execution failure. + compiling or writing output. The selected `lli --version` must identify LLVM 23 + and succeed within five seconds; other or unrecognized versions fail before + source compilation. Without `-r`, no external tools are checked; clang/clang++ + are never invoked or checked by this mode. Process-launch/crash failures return 1. + `-r` alone uses temporary IR removed on return, including execution failure. - In EMBEDDED mode, `-r` uses MCJIT in-process (`tools/driver/EmbeddedRunner.cc`). The engine owns a clone of CodeGen's module; CodeGen retains the context and must outlive the engine. Static C++ exception ABI symbols are explicitly @@ -105,10 +112,10 @@ Driver behavior (`tools/driver/main.cc`): streams. `-r -o` saves IR before executing and keeps it on execution failure. EMBEDDED requires static LLVM archives. `cmake/EmbeddedLLVM.cmake` also selects -static compression/terminal support archives when LLVM uses them. Linux GCC/Clang +static compression/terminal support archives when LLVM uses them. Linux Clang builds link the C++ runtime statically; MinGW uses `-static`. The tested Debian -LLVM 18 executable has only libc, libm and the system loader as dynamic dependencies, -and runs in a minimal chroot without LLVM/lli. Windows EMBEDDED is untested. +LLVM 23 executable has only libc, libm and the system loader as dynamic dependencies. +Windows EMBEDDED is untested. 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 @@ -160,10 +167,10 @@ Linux smoke tests can configure an isolated build with `-DWIN32=TRUE` to exercis HTML/ZIP packaging; the resulting renamed Linux executable is only a test fixture, not a usable Windows release. -Build pin: developed and tested against **LLVM 18**. (The historical LLVM 19 breakage — -`ArithmeticHandler.cc` touching `llvm::Module` through a transitive include — is gone -now that string concatenation lives in `StringHandler`, but newer LLVM versions remain -untested.) +Build pin: **LLVM 23 and upstream Clang 23** (any 23.x release); 23.1.3 is verified +on Linux. LLVM 23 uses `CreateGlobalString` for opaque string pointers, +`hasTerminator()` for block termination checks (its `getTerminator()` requires an +existing terminator), and an explicit `llvm::Triple` for the embedded target. ## Layout diff --git a/AGENTS/EXTENDING.md b/AGENTS/EXTENDING.md index ac9f50e..2b1549f 100644 --- a/AGENTS/EXTENDING.md +++ b/AGENTS/EXTENDING.md @@ -11,7 +11,7 @@ unique_ptr children, move ctor, raw-ptr getters) → `ParseXxx` in `ParseExprList(close, allowEmpty)`; add the new statement's leading keyword to `syncToStatementStart`) → `dynamic_cast` branch in `CodeGen::emitStmt`. Guard every fall-through branch in control-flow codegen with -`if (!Builder->GetInsertBlock()->getTerminator())` — a RETURN in the body may have +`if (!Builder->GetInsertBlock()->hasTerminator())` — a RETURN in the body may have already terminated the block. **New builtin function:** add a `{Name, Arity, ReturnTypeName}` row to the static diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md index 6e0202e..9b32150 100644 --- a/AGENTS/PITFALLS.md +++ b/AGENTS/PITFALLS.md @@ -82,8 +82,8 @@ test programs. ENDTRY. Bare THROW raises a new anonymous exception even inside CATCH; there is no rethrow syntax, error object or what(). Runtime checks are catchable; compiler errors are not. Uncaught exceptions print only the generic message - and return 1. Native binaries must link the C++ runtime with `clang++-18`. - Unwinding does not free heap strings/arrays or close files. Linux LLVM 18 is + and return 1. Native binaries must link the C++ runtime with `clang++-23`. + Unwinding does not free heap strings/arrays or close files. Linux LLVM 23 is verified; Windows and macOS exception execution is not. - **C type extensions.** C_STRING is a raw char pointer, not a STRING: explicitly @@ -93,7 +93,7 @@ test programs. require casts even for literals. C scalar arithmetic uses native promotions, but / always returns REAL. Cast aliases must precede their use. long double may have padding; sizeof does not identify its floating-point format. Native - C support is verified on Linux LLVM 18; cross-target and EXTERN are unsupported. + C support is verified on Linux LLVM 23; cross-target and EXTERN are unsupported. ## Not implemented (9618 features) -- cgit v1.3.1-4-g156e