From dc86a4c2bf6a87c06cd5a1f32bd69fdb0a20781a Mon Sep 17 00:00:00 2001 From: _ov4 Date: Wed, 14 Oct 2026 11:39:46 +0000 Subject: docs(toolchain): clarify MINGW64 LLVM and Clang 23 setup Select the MINGW64 compiler executables with explicit Windows paths and add version checks for installed Clang and downloaded LLVM packages. Document Windows PATH requirements and platform-specific C++ driver names. Co-Authored-By: Claude Fable 5.1 --- AGENTS/ARCH.md | 12 ++++++++++-- AGENTS/PITFALLS.md | 3 ++- doc/build.md | 37 ++++++++++++++++++++++++++++++++++++- doc/cpsc.1.md | 4 ++-- 4 files changed, 50 insertions(+), 6 deletions(-) diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md index 178a8a6..ccbd9bf 100644 --- a/AGENTS/ARCH.md +++ b/AGENTS/ARCH.md @@ -34,7 +34,8 @@ uses C++ promotions, except that / always returns pseudocode REAL. The compiler emits textual IR. Initial configuration must explicitly select `CPSC_RUN_MODE=PATH`, `EMBEDDED` or `NONE` (no default). All modes need LLVM -development libraries to build; NONE still generates IR. Native binaries remain manual: +development libraries to build; NONE still generates IR. Native binaries remain manual. +The following commands use Debian/Ubuntu's versioned compiler names: ```bash # Prepare dependencies using the recommendations in doc/build.md. @@ -69,7 +70,8 @@ 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++-23`). TRY/CATCH/ENDTRY and bare THROW are compiler extensions. +(use LLVM 23's `clang++`, or `clang++-23` on Debian/Ubuntu). +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 23; Windows/macOS are unverified. @@ -117,6 +119,12 @@ builds link the C++ runtime statically; MinGW uses `-static`. The tested Debian LLVM 23 executable has only libc, libm and the system loader as dynamic dependencies. Windows EMBEDDED is untested. +Windows build instructions retain MSYS2 MINGW64. Its LLVM/Clang package names +and compiler executable names are unversioned; CMake still requires major 23. +The build guide explicitly selects `/mingw64/bin/clang.exe` and `clang++.exe` +through `cygpath -m`. MINGW64 Clang retains the GNU linker and C++ library; +switching to CLANG64 would also change the C/C++ runtime and is a separate task. + 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`). diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md index 9b32150..abea2fa 100644 --- a/AGENTS/PITFALLS.md +++ b/AGENTS/PITFALLS.md @@ -82,7 +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++-23`. + and return 1. Native binaries must link the C++ runtime with LLVM 23's + `clang++` (`clang++-23` on Debian/Ubuntu). Unwinding does not free heap strings/arrays or close files. Linux LLVM 23 is verified; Windows and macOS exception execution is not. diff --git a/doc/build.md b/doc/build.md index c8345a3..1af8a81 100644 --- a/doc/build.md +++ b/doc/build.md @@ -80,6 +80,29 @@ pacman -S --needed \ mingw-w64-x86_64-clang ``` +Confirm that both installed compilers report major version 23: + +```bash +/mingw64/bin/clang.exe --version +/mingw64/bin/clang++.exe --version +``` + +The [MINGW64 Clang package](https://packages.msys2.org/packages/mingw-w64-x86_64-clang) +and [LLVM package](https://packages.msys2.org/packages/mingw-w64-x86_64-llvm) +currently provide 23.1.3. MSYS2 keeps these package names unversioned; its +compiler executables are `clang.exe` and `clang++.exe`, not `clang-23.exe` or +`clang++-23.exe`. CMake rejects another major version even when the package +name is unchanged. MINGW64 Clang uses the GNU linker and C++ library supplied +by its package dependencies; cpsc itself is compiled with Clang 23. + +Before downloading LLVM, confirm that these repository packages' `Version` +fields all start with `23.`: + +```bash +pacman -Si mingw-w64-x86_64-llvm \ + mingw-w64-x86_64-llvm-libs mingw-w64-x86_64-llvm-tools +``` + Recommended dependency downloads to the project build directory: ```bash @@ -150,10 +173,17 @@ MSYS2 MINGW64: ```bash cmake -S . -B build -G "MinGW Makefiles" \ -DCPSC_RUN_MODE=EMBEDDED -DCMAKE_BUILD_TYPE=Release \ - -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ + -DCMAKE_C_COMPILER="$(cygpath -m /mingw64/bin/clang.exe)" \ + -DCMAKE_CXX_COMPILER="$(cygpath -m /mingw64/bin/clang++.exe)" mingw32-make -C build -j4 ``` +These explicit paths select the MINGW64 compilers checked above. `cygpath -m` +converts the MSYS2 paths for native Windows CMake. Configuration must report +Clang 23 for both compilers and `Found LLVM 23.x` for the selected development +libraries. Use the MINGW64 packages throughout; do not mix CLANG64 or UCRT64 +libraries into this build. + macOS: ```bash @@ -196,6 +226,11 @@ MSYS2 MINGW64: export PATH="$PWD/build/deps/root/mingw64/bin:$PATH" ``` +In this shell, `lli.exe --version` should identify LLVM 23. `cpsc -r` validates +the same PATH executable automatically before compiling the source. When +running from PowerShell or Command Prompt, add the Windows path to this `bin` +directory to that terminal's PATH so its DLLs can also be found. + macOS: ```bash diff --git a/doc/cpsc.1.md b/doc/cpsc.1.md index 362d48b..063e2c1 100644 --- a/doc/cpsc.1.md +++ b/doc/cpsc.1.md @@ -66,11 +66,11 @@ Save IR and run it: cpsc test.cps -r -o result.ir ``` -Build a native program with a C++ linker so the exception runtime is linked: +Build a native program with Clang 23's C++ driver so the exception runtime is linked. Use `clang++` from the LLVM 23 installation; Debian/Ubuntu also provides the versioned name `clang++-23`. MSYS2 MINGW64 and Homebrew use the unversioned name. ```sh cpsc test.cps -o test.ll -clang++-23 test.ll -o test +clang++ test.ll -o test ./test ``` -- cgit v1.3.1-4-g156e