From 5078c0f81d93bf15d5c5a1c0486355eac12e1020 Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 13 Oct 2026 09:01:59 +0000 Subject: docs: move compiler setup guides into doc Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com --- README.md | 225 +-------------------------------------------------------- doc/build.md | 103 ++++++++++++++++++++++++++ doc/cpsc.md | 6 +- doc/install.md | 109 ++++++++++++++++++++++++++++ 4 files changed, 217 insertions(+), 226 deletions(-) create mode 100644 doc/build.md create mode 100644 doc/install.md diff --git a/README.md b/README.md index 1155db2..03b90c3 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A compiler for CIE Pseudocode (A Level 9618 Computer Science) +[Usage quick reference](doc/cpsc.md) · [Build guide](doc/build.md) · [Installation and releases](doc/install.md) + Details can be found here: [Pseudocode Guide for Teachers](https://www.cambridgeinternational.org/Images/697401-2026-pseudocode-guide-for-teachers.pdf) IDK WHAT HAPPENDED IT IS 100% AI-GENERATED DO NOT OPEN ANY ISSUES JUST CLONE AND FIX IT @@ -34,229 +36,6 @@ IDK WHAT HAPPENDED IT IS 100% AI-GENERATED DO NOT OPEN ANY ISSUES JUST CLONE AND - SET types (`SET` / `DEFINE` are reserved and give a clear "not implemented" error) - CASE OF, CONSTANT, DATE - -## Dependencies - -These are build dependencies. All three modes use LLVM to generate IR, so even -`NONE` requires LLVM development libraries when building the compiler. -Users of an `EMBEDDED` executable do not need to install LLVM or `lli`. - -Linux -```bash -sudo apt-get update -sudo apt-get install -y \ - build-essential \ - cmake \ - llvm-18-dev \ - zlib1g-dev \ - libzstd-dev \ - libtinfo-dev -``` - -The last three packages supply static support archives for `EMBEDDED` when the -LLVM package uses them. `PATH` additionally needs `lli` at run time, for example -from `llvm-18` with `/usr/lib/llvm-18/bin` in PATH. Clang is only needed if you -want to turn the emitted IR into a native executable yourself. - ---- - -mingw-w64 for Windows -```bash -pacman -Syu -pacman -S --needed \ - mingw-w64-x86_64-toolchain \ - mingw-w64-x86_64-cmake \ - mingw-w64-x86_64-llvm \ - mingw-w64-x86_64-clang \ - mingw-w64-x86_64-lld \ - mingw-w64-x86_64-make -``` - -## Build - -You must explicitly choose `-DCPSC_RUN_MODE=PATH`, `EMBEDDED`, or `NONE` on -initial configuration; there is no default. The choice is saved in CMake's cache. - -| Mode | Behavior of `-r` | -|---|---| -| `PATH` | Run external `lli` from PATH; reject `-r` if it is unavailable. | -| `EMBEDDED` | Run with the statically linked LLVM engine inside `cpsc`; no PATH lookup. | -| `NONE` | Reject `-r`; compiling to IR still works. | - -Linux -```bash -cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \ - -DLLVM_DIR=/usr/lib/llvm-18/cmake -DCMAKE_BUILD_TYPE=Release -cmake --build build -j4 -``` - -Distribute `build/cpsc` for `EMBEDDED`. LLVM, the project's libraries and the -compression/terminal support libraries are linked statically; a missing required -archive is a configure error. On Linux with GCC/Clang, the C++ runtime is static -too. The tested Debian/LLVM 18 executable needs only the system libc, libm and -dynamic loader. It runs pseudocode with `-r` as one executable, without LLVM -libraries or `lli` installed. Build for the intended operating system and CPU. - ---- - -mingw-w64 for Windows -```bash -mkdir build && cd build/ -export CMAKE_GENERATOR="MinGW Makefiles" -cmake -DCPSC_RUN_MODE=EMBEDDED .. -mingw32-make -``` - -MinGW uses static linking for `EMBEDDED`; this mode has been verified on Linux, -and the Windows build has not been tested. - - -## Usage - -```bash -cpsc test.cps # save test.ir beside the source file -cpsc test.cps -o result.ir # save IR to the specified path -cpsc test.cps -r # run using the selected build mode -cpsc test.cps -r -o result.ir # save IR and run it -``` - -Only one source file is supported. Options may appear before or after it. -With no arguments, `cpsc` exits silently with status 0; help text is planned. -Diagnostics go to stderr. Failed compilation does not write IR; successful -compilation overwrites an existing output file, but cannot overwrite the source. -`-r` returns the program's exit status. `PATH` uses external `lli`; `EMBEDDED` -executes in-process; `NONE` rejects the option. An unavailable runner is rejected -before compiling or writing IR. The running program inherits -stdin/stdout/stderr, so pseudocode `INPUT` reads from the terminal or piped input. -With `-r` alone, no permanent IR is saved (`PATH` deletes its temporary IR; -`EMBEDDED` runs the in-memory module). With `-r -o`, IR is saved before execution -and kept even if execution fails. - -## Manual - -The command-line quick reference is in `doc/cpsc.md`. Generating the manual requires Pandoc; ordinary builds do not. - -From the project root on Linux: - -```bash -sudo apt-get install pandoc -cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED -make -C build doc -man ./build/doc/cpsc.1 -``` - -You can also run `make doc` inside the configured `build/` directory. -The output is `build/doc/cpsc.1` on Unix and `build/doc/cpsc.html` on Windows, -and is regenerated when the Markdown source changes. On Windows, install Pandoc, -then generate and open the standalone HTML manual from PowerShell: - -```powershell -cmake --build build --target doc -Start-Process .\build\doc\cpsc.html -``` - -The HTML contains its own styles and can be read offline in a browser. - -## Install and release - -On Linux, after configuring and building, install the compiler and manual with: - -```bash -sudo make -C build install -cpsc test.cps -r -man cpsc -``` - -This calls `install.sh` and installs `cpsc` to `/usr/local/bin` and its manual to -`/usr/local/share/man/man1`. Installation generates the manual automatically and -requires Pandoc. Ordinary builds still do not require Pandoc. - -For installation without sudo, set a writable prefix in the existing build: - -```bash -cmake -S . -B build -DCMAKE_INSTALL_PREFIX="$HOME/.local" -make -C build install -export PATH="$HOME/.local/bin:$PATH" -``` - -You can also run `./install.sh --source-dir build --prefix "$HOME/.local"` -directly after building `cpsc` and running `make -C build doc`. -`DESTDIR` is supported for staging, for example `DESTDIR=/tmp/cpsc-stage make -C build install`. - -On Unix, create an installation archive with: - -```bash -make -C build release -``` - -The output is `build/cpsc-VERSION-SYSTEM-ARCH.tar.xz`. `VERSION` uses HEAD's commit -time in UTC followed by its short ID: `yyyy-mm-dd-hh-mm-ss-commit`. -The version is read each time packaging runs. The package uses the current build's -execution mode and contains `cpsc`, `doc/cpsc.1`, `install.sh` and `LICENSE`. -Packaging builds the compiler and manual automatically; it requires Git and Pandoc. -Use `EMBEDDED` when recipients should not need LLVM or `lli` at run time. - -Extract the archive with `tar -xJf`, enter the extracted directory, then run -`sudo ./install.sh`, or `./install.sh --prefix "$HOME/.local"` for a local installation. -The package installer does not require CMake, Git or Pandoc. -For a custom prefix, add its `bin` directory to PATH; `man` normally discovers the -adjacent `share/man` directory from PATH. If your man configuration overrides this, -use `man -M "$HOME/.local/share/man" cpsc` for the local prefix. - -On Windows, install from an existing MinGW build with: - -```powershell -cmake --build build --target install -``` - -This is equivalent to `mingw32-make -C build install`: it generates the HTML -manual with Pandoc and calls `install.ps1`. The Windows default -`CMAKE_INSTALL_PREFIX` is `%LOCALAPPDATA%\Programs\cpsc`; an explicitly configured -prefix is preserved. To change it, run -`cmake -S . -B build -DCMAKE_INSTALL_PREFIX="D:/My Programs/cpsc"` before installing. - -You can also call `install.ps1` directly. It installs for the current user without -administrator rights. Its source directory must contain `cpsc.exe` and `doc/cpsc.html`: - -```powershell -powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SourceDir .\build -``` - -The default destination is `%LOCALAPPDATA%\Programs\cpsc`: `cpsc.exe` goes in -that directory and the HTML manual goes in its `doc` subdirectory. The installer -adds the directory to the user PATH and creates Start Menu > cpsc > cpsc Help, -which opens the manual in the default browser. Open a new terminal afterward; -existing parent terminals retain their old PATH. Reinstalling does not duplicate -the PATH entry. Use `-Prefix 'D:\My Programs\cpsc'` for a custom destination, -or `-Help` for usage. Windows installation does not support `DESTDIR` staging. -The PowerShell installer targets Windows PowerShell 5.1 or later and has only -been reviewed statically; Windows installation still needs testing on Windows. - -Create a Windows installation archive from the configured MinGW build with: - -```powershell -cmake --build build --target release -``` - -This is equivalent to `mingw32-make -C build release`. Windows produces -`build/cpsc-VERSION-Windows-ARCH.zip`, using the same UTC commit version as Unix -and retaining the configured execution mode. The ZIP contains `cpsc.exe`, -`doc/cpsc.html`, `install.ps1` and `LICENSE` under one top-level directory. -It uses CMake's default Deflate compression and needs no additional compression -tool; packaging requires Git and Pandoc, just as on Unix. - -Extract the ZIP using Windows Explorer, open PowerShell in the extracted package -directory, then run: - -```powershell -powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -``` - -Recipients need neither CMake, Git nor Pandoc to install. To check installation, -open a new terminal, run `Get-Command cpsc` and compile a source with -`cpsc test.cps`; open Start Menu > cpsc > cpsc Help to check the manual. Running -the installer again should leave only one entry for its directory in the user PATH. - # Note DO NOT OPEN ANY ISSUES IF YOU COMPILE WITH VISUAL STUDIO OR ANYTHING EXCEPT MINGW-W64 (EVEN WITH MINGW-W64, WINDOWS IS LIKELY TO BE A PROBLEM MAKER) diff --git a/doc/build.md b/doc/build.md new file mode 100644 index 0000000..7e4cc7c --- /dev/null +++ b/doc/build.md @@ -0,0 +1,103 @@ +# Building cpsc + +Run these commands from the project root unless stated otherwise. For installation and release packaging, see [install.md](install.md). + +## Dependencies + +These are build dependencies. All three modes use LLVM to generate IR, so even +`NONE` requires LLVM development libraries when building the compiler. +Users of an `EMBEDDED` executable do not need to install LLVM or `lli`. + +Linux +```bash +sudo apt-get update +sudo apt-get install -y \ + build-essential \ + cmake \ + llvm-18-dev \ + zlib1g-dev \ + libzstd-dev \ + libtinfo-dev +``` + +The last three packages supply static support archives for `EMBEDDED` when the +LLVM package uses them. `PATH` additionally needs `lli` at run time, for example +from `llvm-18` with `/usr/lib/llvm-18/bin` in PATH. Clang is only needed if you +want to turn the emitted IR into a native executable yourself. + +--- + +mingw-w64 for Windows +```bash +pacman -Syu +pacman -S --needed \ + mingw-w64-x86_64-toolchain \ + mingw-w64-x86_64-cmake \ + mingw-w64-x86_64-llvm \ + mingw-w64-x86_64-clang \ + mingw-w64-x86_64-lld \ + mingw-w64-x86_64-make +``` + +## Build + +You must explicitly choose `-DCPSC_RUN_MODE=PATH`, `EMBEDDED`, or `NONE` on +initial configuration; there is no default. The choice is saved in CMake's cache. + +| Mode | Behavior of `-r` | +|---|---| +| `PATH` | Run external `lli` from PATH; reject `-r` if it is unavailable. | +| `EMBEDDED` | Run with the statically linked LLVM engine inside `cpsc`; no PATH lookup. | +| `NONE` | Reject `-r`; compiling to IR still works. | + +Linux +```bash +cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \ + -DLLVM_DIR=/usr/lib/llvm-18/cmake -DCMAKE_BUILD_TYPE=Release +cmake --build build -j4 +``` + +Distribute `build/cpsc` for `EMBEDDED`. LLVM, the project's libraries and the +compression/terminal support libraries are linked statically; a missing required +archive is a configure error. On Linux with GCC/Clang, the C++ runtime is static +too. The tested Debian/LLVM 18 executable needs only the system libc, libm and +dynamic loader. It runs pseudocode with `-r` as one executable, without LLVM +libraries or `lli` installed. Build for the intended operating system and CPU. + +--- + +mingw-w64 for Windows +```bash +mkdir build && cd build/ +export CMAKE_GENERATOR="MinGW Makefiles" +cmake -DCPSC_RUN_MODE=EMBEDDED .. +mingw32-make +``` + +MinGW uses static linking for `EMBEDDED`; this mode has been verified on Linux, +and the Windows build has not been tested. + +## Manual + +The command-line quick reference is in [cpsc.md](cpsc.md). Generating the manual requires Pandoc; ordinary builds do not. + +From the project root on Linux: + +```bash +sudo apt-get install pandoc +cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED +make -C build doc +man ./build/doc/cpsc.1 +``` + +You can also run `make doc` inside the configured `build/` directory. +The output is `build/doc/cpsc.1` on Unix and `build/doc/cpsc.html` on Windows, +and is regenerated when the Markdown source changes. On Windows, install Pandoc, +then generate and open the standalone HTML manual from PowerShell: + +```powershell +cmake --build build --target doc +Start-Process .\build\doc\cpsc.html +``` + +The HTML contains its own styles and can be read offline in a browser. diff --git a/doc/cpsc.md b/doc/cpsc.md index 3aa89a8..bfd54d0 100644 --- a/doc/cpsc.md +++ b/doc/cpsc.md @@ -20,11 +20,11 @@ Without **-o** or **-r**, replace the source filename's extension with `.ir` and : Save IR to the specified path. May be specified only once. With **-r**, keep this file even if execution fails. **-r** -: Run the compiled program with the runner selected at build time (see BUILD MODES). Without **-o**, do not save permanent IR. The program inherits stdin, stdout and stderr; `INPUT` can read terminal or piped input. +: Run the compiled program with the runner selected at build time (see EXECUTION MODES). Without **-o**, do not save permanent IR. The program inherits stdin, stdout and stderr; `INPUT` can read terminal or piped input. -# BUILD MODES +# EXECUTION MODES -Initial CMake configuration requires **-DCPSC_RUN_MODE=PATH**, **EMBEDDED** or **NONE**. No mode is selected by default. All modes compile to IR using LLVM libraries built into the compiler; NONE disables execution, not IR generation. +The executable has one of the following execution modes, selected when it was built. All modes can compile to LLVM IR; the mode determines whether and how **-r** runs the program. **PATH** : Run `lli` from PATH. If it cannot be found, **-r** fails before compilation or output writing. Without **-o**, write temporary IR and delete it afterward, including on execution failure. diff --git a/doc/install.md b/doc/install.md new file mode 100644 index 0000000..365a1c1 --- /dev/null +++ b/doc/install.md @@ -0,0 +1,109 @@ +# Installing and packaging cpsc + +To build from source, follow [build.md](build.md). For command-line usage, see [cpsc.md](cpsc.md). Run build commands from the project root; package installation commands run from the extracted package directory. + +## Linux installation + +After configuring and building, install the compiler and manual with: + +```bash +sudo make -C build install +cpsc test.cps -r +man cpsc +``` + +This calls `install.sh` and installs `cpsc` to `/usr/local/bin` and its manual to +`/usr/local/share/man/man1`. Installation generates the manual automatically and +requires Pandoc. Ordinary builds still do not require Pandoc. + +For installation without sudo, set a writable prefix in the existing build: + +```bash +cmake -S . -B build -DCMAKE_INSTALL_PREFIX="$HOME/.local" +make -C build install +export PATH="$HOME/.local/bin:$PATH" +``` + +You can also run `./install.sh --source-dir build --prefix "$HOME/.local"` +directly after building `cpsc` and running `make -C build doc`. +`DESTDIR` is supported for staging, for example `DESTDIR=/tmp/cpsc-stage make -C build install`. + +## Unix release packages + +Create an installation archive with: + +```bash +make -C build release +``` + +The output is `build/cpsc-VERSION-SYSTEM-ARCH.tar.xz`. `VERSION` uses HEAD's commit +time in UTC followed by its short ID: `yyyy-mm-dd-hh-mm-ss-commit`. +The version is read each time packaging runs. The package uses the current build's +execution mode and contains `cpsc`, `doc/cpsc.1`, `install.sh` and `LICENSE`. +Packaging builds the compiler and manual automatically; it requires Git and Pandoc. +Use `EMBEDDED` when recipients should not need LLVM or `lli` at run time. + +Extract the archive with `tar -xJf`, enter the extracted directory, then run +`sudo ./install.sh`, or `./install.sh --prefix "$HOME/.local"` for a local installation. +The package installer does not require CMake, Git or Pandoc. +For a custom prefix, add its `bin` directory to PATH; `man` normally discovers the +adjacent `share/man` directory from PATH. If your man configuration overrides this, +use `man -M "$HOME/.local/share/man" cpsc` for the local prefix. + +## Windows installation + +Install from an existing MinGW build with: + +```powershell +cmake --build build --target install +``` + +This is equivalent to `mingw32-make -C build install`: it generates the HTML +manual with Pandoc and calls `install.ps1`. The Windows default +`CMAKE_INSTALL_PREFIX` is `%LOCALAPPDATA%\Programs\cpsc`; an explicitly configured +prefix is preserved. To change it, run +`cmake -S . -B build -DCMAKE_INSTALL_PREFIX="D:/My Programs/cpsc"` before installing. + +You can also call `install.ps1` directly. It installs for the current user without +administrator rights. Its source directory must contain `cpsc.exe` and `doc/cpsc.html`: + +```powershell +powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -SourceDir .\build +``` + +The default destination is `%LOCALAPPDATA%\Programs\cpsc`: `cpsc.exe` goes in +that directory and the HTML manual goes in its `doc` subdirectory. The installer +adds the directory to the user PATH and creates Start Menu > cpsc > cpsc Help, +which opens the manual in the default browser. Open a new terminal afterward; +existing parent terminals retain their old PATH. Reinstalling does not duplicate +the PATH entry. Use `-Prefix 'D:\My Programs\cpsc'` for a custom destination, +or `-Help` for usage. Windows installation does not support `DESTDIR` staging. +The PowerShell installer targets Windows PowerShell 5.1 or later and has only +been reviewed statically; Windows installation still needs testing on Windows. + +## Windows release packages + +Create an installation archive from the configured MinGW build with: + +```powershell +cmake --build build --target release +``` + +This is equivalent to `mingw32-make -C build release`. Windows produces +`build/cpsc-VERSION-Windows-ARCH.zip`, using the same UTC commit version as Unix +and retaining the configured execution mode. The ZIP contains `cpsc.exe`, +`doc/cpsc.html`, `install.ps1` and `LICENSE` under one top-level directory. +It uses CMake's default Deflate compression and needs no additional compression +tool; packaging requires Git and Pandoc, just as on Unix. + +Extract the ZIP using Windows Explorer, open PowerShell in the extracted package +directory, then run: + +```powershell +powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 +``` + +Recipients need neither CMake, Git nor Pandoc to install. To check installation, +open a new terminal, run `Get-Command cpsc` and compile a source with +`cpsc test.cps`; open Start Menu > cpsc > cpsc Help to check the manual. Running +the installer again should leave only one entry for its directory in the user PATH. -- cgit v1.3.1-4-g156e From 36bd3abfd47753361098631d9a505a5365a4985e Mon Sep 17 00:00:00 2001 From: _ov4 Date: Tue, 13 Oct 2026 09:04:00 +0000 Subject: docs: simplify compiler README Co-Authored-By: Claude Fable 5.1 noreply@anthropic.com --- README.md | 37 +++++++++++++------------------------ 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 03b90c3..0d536a1 100644 --- a/README.md +++ b/README.md @@ -6,38 +6,27 @@ A compiler for CIE Pseudocode (A Level 9618 Computer Science) Details can be found here: [Pseudocode Guide for Teachers](https://www.cambridgeinternational.org/Images/697401-2026-pseudocode-guide-for-teachers.pdf) -IDK WHAT HAPPENDED IT IS 100% AI-GENERATED DO NOT OPEN ANY ISSUES JUST CLONE AND FIX IT - ## Features -- use LLVM, perhaps support all archs -- built-in runtime checking to prevent illegal operations (eg. array, integer division), and prevent kernal to kill the program immediately -- no Segmentation Fault (Core Dumped), beginner-friendly -- array flatting with row-major (the standard of the industry), with `LowerBounds`, `UpperBounds`, etc. support any dimension with any lower/upper bounds -- cache-friendly array (perhaps) -- dynamic string handling, with full implementation of all CIE string functions, with high security -- native support for BYREF/BYVAL using pointers -- text file handling (OPENFILE/READFILE/WRITEFILE/CLOSEFILE/EOF) with runtime misuse - checking (wrong mode, not open, read past EOF, ... all die with a clean `[Fatal]` - message instead of corrupting anything) -- user-defined types (CIE §4): enumerated types (with runtime range checking on - `enum ± INTEGER`), pointers (`^x` / `p^`, strict nominal typing, null-deref dies - with `[Fatal]` instead of segfaulting — linked lists work, `TYPE NodePtr = ^Node` - may forward-reference), records (nested, arrays of records, `Form[i].Field <- x`) -- whole arrays and records as FUNCTION/PROCEDURE parameters (`ARRAY OF T` or - `ARRAY[l:u,...] OF T` as a checked contract; BYVAL really copies), with the - spec-correct sticky BYREF/BYVAL and BYREF-is-procedure-only rules from §8.3 -- ultra-fast compiling & executing +- **LLVM compilation**: Generate LLVM IR and run programs when execution is enabled in the build. +- **Runtime checks**: Report array bounds errors, division by zero, file misuse, enum range errors and null pointer dereferences. +- **Arrays**: Support multiple dimensions and custom lower and upper bounds. +- **Strings**: Support dynamic strings and built-in string functions. +- **Functions and procedures**: Pass values, arrays and records by value; procedures also support `BYREF` parameters. +- **Text files**: Support `OPENFILE`, `READFILE`, `WRITEFILE`, `CLOSEFILE` and `EOF`. +- **User-defined types**: Support enumerated types, pointers and nested records. ## TODO -- search for `TODO` in my code -- random files (OPENFILE FOR RANDOM / SEEK / GETRECORD / PUTRECORD) — `type` is done, unblocked -- SET types (`SET` / `DEFINE` are reserved and give a clear "not implemented" error) -- CASE OF, CONSTANT, DATE +- **Source TODOs**: Resolve remaining `TODO` comments. +- **Random files**: Add `OPENFILE FOR RANDOM`, `SEEK`, `GETRECORD` and `PUTRECORD`. +- **Set types**: Implement `SET` and `DEFINE`. +- **Other syntax**: Add `CASE OF`, `CONSTANT` and `DATE`. # Note +IDK WHAT HAPPENDED IT IS 100% AI-GENERATED DO NOT OPEN ANY ISSUES JUST CLONE AND FIX IT + DO NOT OPEN ANY ISSUES IF YOU COMPILE WITH VISUAL STUDIO OR ANYTHING EXCEPT MINGW-W64 (EVEN WITH MINGW-W64, WINDOWS IS LIKELY TO BE A PROBLEM MAKER) ONLY TESTED ON DEBIAN (AND A BIT MINGW-W64) -- cgit v1.3.1-4-g156e