docs: move compiler setup guides into doc

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

1 files changed, 2 insertions, 223 deletions

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)