Installation

Installation

Requirements

Build requirements:

• Free Pascal Compiler 3.2.2 or a compatible Free Pascal 3.x release.
• Free Pascal FV, FCL, DB, and POSIX thread units (fp-units-misc supplies PThreads on Debian/Ubuntu).
• GNU make.
• A POSIX host: GNU/Linux (with /proc) or macOS (Apple Silicon or Intel).

Test requirements:

• Python 3.
• Python packages pyte and Pillow (PIL).
• rsvg-convert (librsvg2-bin on Debian/Ubuntu, librsvg with Homebrew) for reproducible artwork checks.

Remote terminal requirements:

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

Optional incoming access from a standard SSH client (5.2.2):

• The operating system's OpenSSH server: openssh-server on Debian/Ubuntu; macOS already includes /usr/sbin/sshd.
• A system-wide SuperTerm binary in a protected, root-owned path. The dedicated service deliberately rejects a binary or ancestor directory writable by another user.

This is a separate OpenSSH instance under /etc/superterm/sshd; it does not replace or reconfigure the host's ordinary SSH service. See SSH before publishing it on a network.

Prebuilt packages

Every release attaches x86_64 GNU/Linux packages; the newest is always at https://github.com/garacil/superterm/releases/latest. The .deb, .rpm and Arch packages install /usr/bin/superterm plus documentation and examples; the generic tarball runs in place. These builds require glibc 2.34 or newer, and each file ships with its .sha256. macOS arm64 and universal archives are published separately. GNU/Linux ARM currently builds from source.

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 is exact and versioned (version 16 in 5.2.2, unchanged since 4.2.1, so those two interoperate). A client and daemon from incompatible builds refuse each other explicitly instead of misreading a changed cell or event format. Close every live session before replacing the binary; detach deliberately keeps it alive:

superterm list          # see what is running
superterm kill NAME     # close it; detach is not an upgrade shutdown

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

To prepare the optional dedicated SSH entry after a system-wide install:

sudo superterm ssh-server setup
sudoedit /etc/superterm/sshd/server.ini
sudo superterm ssh-server check
sudo superterm ssh-server restart
sudo superterm ssh-server status

The generated default listens only on loopback. Choose an explicit server address and authentication policy before exposing it to another machine; the complete procedure and rollback-safe administration are documented in SSH.

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.