Installation

Installation

Requirements

Build requirements:

• Free Pascal Compiler 3.2.2 or a compatible Free Pascal 3.x release.
• Free Pascal FV, FCL, and DB units.
• GNU make.
• A POSIX host: GNU/Linux (with /proc) or macOS (Apple Silicon or Intel).

Test requirements:

• Python 3.
• Python package pyte.

Remote terminal requirements:

• openssh-client for SSH connections.
• sshpass only when password authentication is explicitly configured.

Prebuilt packages

Prebuilt v3.2 packages are attached to the release page: https://github.com/garacil/superterm/releases/tag/v3.2. Every package installs /usr/bin/superterm plus documentation and examples; the only runtime dependency is glibc. The current release ships x86_64 GNU/Linux packages; on macOS (or GNU/Linux on ARM) build from source with the steps below. An ARM build may be added to a future release.

Arch and derivatives (superterm-3.2-1-x86_64.pkg.tar.zst):

sudo pacman -U superterm-3.2-1-x86_64.pkg.tar.zst

Debian/Ubuntu (superterm_3.2_amd64.deb):

sudo apt install ./superterm_3.2_amd64.deb   # or: sudo dpkg -i superterm_3.2_amd64.deb

Fedora/RHEL/openSUSE (superterm-3.2-1.x86_64.rpm):

sudo dnf install ./superterm-3.2-1.x86_64.rpm   # or: sudo rpm -i superterm-3.2-1.x86_64.rpm

Generic tarball (superterm-3.2-gnu-x86_64.tar.gz, verify with the companion .sha256):

sha256sum -c superterm-3.2-gnu-x86_64.tar.gz.sha256
tar xzf superterm-3.2-gnu-x86_64.tar.gz
./superterm-3.2/superterm

Upgrading from an earlier release

The session protocol moves to version 3 in 3.2, because the pane snapshot's cell size changed. A 3.2 client refuses to attach to a daemon from an older release -- it says so rather than failing silently -- so close any live session before installing:

superterm list          # see what is running
superterm kill NAME     # or detach and let it exit

Configure and Build

The project includes a self-contained POSIX configure script (not generated by GNU Autoconf). It builds from a clean checkout on any architecture that has a native Free Pascal compiler.

./configure
make release

The release binary is bin/superterm. A debug build is available with:

make debug

The debug binary is bin/superterm-debug.

Useful overrides:

./configure --with-fpc=/usr/local/bin/fpc
./configure --with-python=/usr/bin/python3
./configure --prefix="$HOME/.local" \
  --sysconfdir="$HOME/.config/superterm"

Inspect the selected paths with:

make info

The compatibility wrapper remains available:

./compile.sh
./compile.sh -B

macOS

superterm builds from the same source tree on macOS (Apple Silicon and Intel). Install the Free Pascal compiler with Homebrew; libsqlite3 already ships with the system, and Free Pascal auto-defines DARWIN, so the configure and make commands above are identical:

brew install fpc        # or: make install-deps   (auto-detects macOS/Homebrew)
./configure
make release

See docs/MACOS.md for terminal setup (Terminal.app / iTerm2), mouse support, and platform notes.

Run

./bin/superterm

Optional runtime diagnostics:

SUPERTERM_DEBUG=/tmp/superterm-debug.log ./bin/superterm

Test

Build the release binary and run the complete PTY/UI regression suite:

make test

The tests launch isolated PTYs and do not attach to, restart, or modify a user's tmux server.

Install System-Wide

System installation normally requires root:

./configure --prefix=/usr/local --sysconfdir=/etc
make release
sudo make install

For a user-local installation:

./configure --prefix="$HOME/.local" \
  --sysconfdir="$HOME/.config/superterm"
make install

Ensure $HOME/.local/bin is in PATH after a user-local installation.