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

Every release attaches x86_64 packages; the newest is always at https://github.com/garacil/superterm/releases/latest. Each installs /usr/bin/superterm plus documentation and examples, the only runtime dependency is glibc, and each file ships with its .sha256. On macOS, or on GNU/Linux for ARM, build from source with the steps below.

Substitute the version you downloaded for VER below.

Arch and derivatives:

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

Debian/Ubuntu:

sudo apt install ./superterm_VER_amd64.deb   # or: sudo dpkg -i superterm_VER_amd64.deb

Fedora/RHEL/openSUSE:

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

Generic tarball, verified against its companion .sha256:

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

Upgrading an existing source checkout

Run ./configure again after pulling, or simply make: the Makefile now regenerates itself when its template changes. Skipping it leaves the build without the new backgrounds directory, and the Desktop background menu then offers only None.

Upgrading from an earlier release

The session protocol moved to version 3 in 3.2, because the pane snapshot's cell size changed, and has stayed there since: a 3.4.x client attaches to a 3.2 or 3.3 daemon and the other way round. A 3.2-or-newer 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.