diff options
| -rw-r--r-- | AGENTS/ARCH.md | 12 | ||||
| -rw-r--r-- | AGENTS/PITFALLS.md | 3 | ||||
| -rw-r--r-- | doc/build.md | 37 | ||||
| -rw-r--r-- | 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 ``` |