Development

Development

Source Tree

• src/: Free Pascal application units.
• vendor/fv322/: local FreeVision source overlay.
• docs/: detailed build, configuration, and wizard documentation.
• examples/: configuration examples.
• test/: Python/pyte PTY regression tests.
• bin/ and build/: generated output, ignored by Git.

Build Workflow

Configure the tree and build a release binary:

./configure
make release

Use the debug build when compiler symbols or runtime diagnostics are needed:

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

Tests

Run the complete suite with:

make test

The tests launch isolated PTYs and exercise pane operations, large terminal sizes, xterm and tmux mouse input, focus routing, cursor handling, session restore, system configuration, window classes, profiles, named multi-session detach/attach, the configurable prefix key, editable window titles, the wizard, language switching, and window controls. The legacy [template.*] and SQLite template paths are still covered by template_test.py and sqlite_test.py.

The authoritative suite list is TESTS in Makefile.in (107 independent scripts in 5.2.2, checked against test/*_test.py by suite_manifest_test.py so the inventory cannot drift). It includes renderer-transition, shared-geometry, multi-client stress, daemon identity, protocol bounds, and real isolated OpenSSH transport coverage in addition to the areas above. Run one focused script directly when developing, for example:

python3 test/drive_test.py
python3 test/large_screen_test.py
python3 test/mouse_test.py
SUPERTERM_TEST_TERM=tmux-256color python3 test/mouse_test.py
python3 test/mouse_focus_test.py
python3 test/restore_test.py
python3 test/sysconfig_test.py
python3 test/template_test.py        # legacy templates
python3 test/sqlite_test.py          # legacy SQLite templates
python3 test/wizard_test.py
python3 test/language_test.py
python3 test/window_test.py
python3 test/cursor_test.py
python3 test/wclass_test.py          # window classes
python3 test/profile_test.py         # profiles
python3 test/multisession_test.py    # named detachable sessions
python3 test/prefix_test.py          # configurable prefix key
python3 test/title_test.py           # editable window titles
python3 test/ssh_transport_test.py   # real dedicated OpenSSH transport

Change Guidelines

• Keep PTY and process changes isolated from UI changes when possible.
• Preserve the local FreeVision overlay; do not modify system FPC packages.
• Add or update a regression test for behavior changes.
• Use temporary directories and isolated processes for destructive tests.
• Do not place passwords in source files, command lines, or debug logs.

Platform Boundary

The supported native platforms are GNU/Linux and macOS (both POSIX), built from the same source tree. UI, VT engine, layout, session protocol, and reactor are shared. Small platform adapters are isolated to PTY/process and CPU discovery, secure POSIX types/constants, debug thread identity, and the optional SSH service manager. A native Windows port would need a ConPTY backend and Windows-specific process, resize, signal, and path code.