docs: move compiler setup guides into doc

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

3 files changed, 215 insertions, 3 deletions

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.