vnm_terminal_surface

vnm_terminal_surface is a BSD-licensed Qt Quick terminal component. It embeds a real interactive terminal, backed by a ConPTY (Windows) or PTY (Linux, macOS) child process, in a Qt Quick application as a single C++ QQuickItem: VNM_TerminalSurface. It was built for and ships in Varinomics products, and the same component is usable by any Qt Quick host.

Highlights

• Real terminal behavior, not a log viewer: alternate screen, cursor addressing, scrollback, keyboard and mouse reporting modes, bracketed paste, selection, clipboard policy, and terminal replies.
• Native process hosting per platform: ConPTY on Windows and PTY on Linux and macOS, with resize propagation and process lifecycle signals.
• GPU text rendering through the Qt Scene Graph: a glyph-atlas render node with MSDF and glyph raster paths and LCD subpixel modes.
• A documented public API (docs/public_surface.md), typed scroll diagnostics, and a public diagnostics serialization API.
• Continuously tested on Windows, Linux, and macOS: contract, model, backend, renderer, conformance, randomized-parser, and lifecycle test families.

Requirements

• Qt 6.7 or newer
• A C++20 compiler
• CMake 3.21 or newer

Start Here

For a first pass through the repository, read these in order:

1. Developer orientation - the shortest stable explanation of what the project is, where the important code lives, and how the pieces fit together.
2. Architecture - the runtime model, ownership boundaries, and data flow.
3. Public surface - the VNM_TerminalSurface API.
4. Repository guide - build targets, test families, generated/provenance material, and common entry points.

The documentation index has a time-budgeted reading path and links to the reference material.

Build On Windows

Configure once:

cmake -S . -B build -DBUILD_TESTING=ON

Project tests are configured only when both CTest's BUILD_TESTING switch and VNM_TERMINAL_SURFACE_BUILD_TESTING are ON. The project-specific gate defaults to ON for a top-level checkout and OFF when embedded as a subproject.

Diagnostic transcript capture/replay is compiled out by default. Enable it only for local diagnostic builds with -DVNM_TERMINAL_ENABLE_TRANSCRIPT_CAPTURE_REPLAY=ON; distribution builds must use -DVNM_TERMINAL_DISTRIBUTION_BUILD=ON and leave transcript capture/replay disabled.

Build from an x64 MSVC Developer Command Prompt or another shell where the Visual Studio C++ environment has already been initialized:

cmake --build build --target vnm_terminal_surface --config Release

Run the configured test suite:

ctest --test-dir build -C Release --output-on-failure

Windows CI runs vnm_terminal_windows_conpty_backend in the normal test suite and in a focused AddressSanitizer job. vnm_terminal_compat_smoke is a local Windows gate for the full native-surface fixture smoke. To reproduce the ASan job locally, configure a separate AddressSanitizer build (only our library and tests are instrumented; Qt and the FetchContent dependencies are left uninstrumented). This focused run exercises the worker-thread backend-destruction path under ASan; failures in that path can surface after the triggering callback returns, so repeat the command when chasing a suspected lifetime regression:

cmake -S . -B build-asan -DBUILD_TESTING=ON -DVNM_TERMINAL_SANITIZE_ADDRESS=ON
cmake --build build-asan --target vnm_terminal_windows_conpty_backend --config Release
ctest --test-dir build-asan -C Release -R vnm_terminal_windows_conpty_backend --output-on-failure

Run from an x64 MSVC Developer Command Prompt so the AddressSanitizer runtime is resolvable on PATH.

On Linux and macOS, use the same configure step and the normal generated build command for the selected generator.

Use the repository guide for test families, conformance controls, benchmarks, and focused validation commands.

License

BSD 2-Clause. See LICENSE.