docs: explain installation and commit-versioned releases

Document system and local installation, DESTDIR staging, release contents,
and the UTC commit timestamp and short ID used for package versions.

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

2 files changed, 58 insertions, 0 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index 0e513c9..4decf15 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -64,6 +64,17 @@ builds link the C++ runtime statically; MinGW uses `-static`. The tested Debian
 LLVM 18 executable has only libc, libm and the system loader as dynamic dependencies,
 and runs in a minimal chroot without LLVM/lli. Windows EMBEDDED is untested.
 
+On Linux, `make -C build install` builds the manual and calls the POSIX
+`install.sh` to copy `cpsc` and `doc/cpsc.1` into `CMAKE_INSTALL_PREFIX/bin` and
+`CMAKE_INSTALL_PREFIX/share/man/man1` (default prefix `/usr/local`). The script
+also supports `--prefix`, `--source-dir` and `DESTDIR` staging. Ordinary builds
+do not require Pandoc; `doc`, installation and release packaging do.
+`make -C build release` packages the executable, manual, installer and license
+as `build/cpsc-VERSION-SYSTEM-ARCH.tar.xz`, retaining the configured execution mode.
+`cmake/Release.cmake` reads HEAD at packaging time; VERSION is the commit's UTC
+timestamp (`yyyy-mm-dd-hh-mm-ss`) followed by its short ID. Git is only required
+for packaging; recipients can install the extracted archive using just the script.
+
 Build pin: developed and tested against **LLVM 18**. (The historical LLVM 19 breakage —
 `ArithmeticHandler.cc` touching `llvm::Module` through a transitive include — is gone
 now that string concatenation lives in `StringHandler`, but newer LLVM versions remain
@@ -84,6 +95,7 @@ untested.)
 | `lib/CodeGen/*Handler.cc`, `FunctionGen.cc`, `RuntimeCheck.cc`, `TypeSystem.cc` | Helpers owned by CodeGen |
 | `CMakeLists.txt` | 3 static libs (CPSLexer, CPSParser, CPSCodeGen) + `cpsc`. **New .cc files must be added to the source lists here** |
 | `tools/driver/EmbeddedRunner.cc`, `cmake/EmbeddedLLVM.cmake` | EMBEDDED-only MCJIT runner and static support-library selection |
+| `install.sh`, `cmake/Install.cmake.in`, `cmake/Release.cmake` | Artifact installation and versioned binary release packaging |
 
 AST nodes live in `include/cps/AST.h` (+ `FunctionAST.h`, `FileAST.h`, `TypeAST.h`);
 they are pure data with virtual destructors only — no codegen/visitor methods.
diff --git a/README.md b/README.md
index d4c009c..bcaf0ea 100644
--- a/README.md
+++ b/README.md
@@ -148,6 +148,52 @@ man ./build/doc/cpsc.1
 You can also run `make doc` inside the configured `build/` directory.
 The output is `build/doc/cpsc.1` and is regenerated when the Markdown source changes.
 
+## 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`.
+
+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.
+
 # 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)