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 Makefile TESTS list is:

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

The test/ directory also contains detach_test.py for the detach/attach lifecycle.

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. The only platform-conditional unit is src/st_pty.pas, which selects its PTY/process backend with {$IFDEF DARWIN}; every other unit is shared, so a change merged on one OS applies to both. A native Windows port would need a ConPTY backend and Windows-specific process, resize, signal, and path code.