Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rikitav/Terminality/llms.txt

Use this file to discover all available pages before exploring further.

Terminality is built around C++23 named modules, which place strict requirements on both the compiler and the build system. The framework targets Windows and Linux, with each platform handled by a dedicated translation unit compiled under the appropriate preprocessor guard.

​
Build system requirements

The root CMakeLists.txt sets the minimum requirements for the entire project: 
cmake_minimum_required(VERSION 4.0)

set(CMAKE_CXX_STANDARD 23)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_SCAN_FOR_MODULES ON)

set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

project(Terminality LANGUAGES CXX)
SettingPurpose
cmake_minimum_required(VERSION 4.0)CMake 4.0 is required for stable C++23 module scanning support.
CMAKE_CXX_STANDARD 23Enables C++23 language features, including named modules.
CMAKE_CXX_SCAN_FOR_MODULES ONTells CMake to scan source files for import/export module declarations and build the correct dependency graph.
CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ONAutomatically generates __declspec(dllexport) entries when building Terminality as a shared library on Windows. Remove this flag if you are linking statically or targeting Linux only.
CMAKE_EXPORT_COMPILE_COMMANDS ONWrites compile_commands.json for tooling such as clangd. Has no effect on the build output.
Do not set CMAKE_CXX_STANDARD below 23. Named modules are a C++23 feature; the project will not compile on earlier standards.

​
Supported compilers

Terminality is tested against the latest stable releases of:
  • MSVC (Visual Studio 2022 or later) — primary development compiler on Windows
  • GCC (13 or later) — used on Linux
Module support in both compilers is still maturing. Use the newest available toolchain version to avoid known module-parsing bugs in older releases.
Clang module support exists but is not officially tested by this project. You may encounter build issues with older Clang versions.

​
Windows

On Windows, HostApplication::EnterTerminal uses the Win32 console API to set up the terminal before any rendering begins:
  • Sets the console code page to UTF-8 (CP_UTF8 = 65001) for both input and output.
  • Enables ENABLE_VIRTUAL_TERMINAL_PROCESSING on the output handle so ANSI/VT sequences are interpreted correctly.
  • Enables ENABLE_WINDOW_INPUT on the input handle so resize events are delivered.
  • Hides the cursor with SetConsoleCursorInfo.
ExitTerminal restores the alternate screen buffer and re-enables cursor visibility.

​
The MessageBox macro conflict

<Windows.h> defines a MessageBox macro that maps to either MessageBoxA or MessageBoxW depending on the character-set setting. This macro shadows terminality::MessageBox and causes a compilation error. The fix is a single #undef immediately after the Windows header, before any Terminality imports: 
#include <Windows.h>
#undef MessageBox       // remove the Win32 macro

import terminality;
using namespace terminality;
This pattern is used in TespApp and must be replicated in any Windows translation unit that uses terminality::MessageBox.

​
Windows-only API: AlertAsync

The terminality:Windows module exports one Windows-specific helper: 
// Only available when _WIN32 is defined
void terminality::AlertAsync(const std::wstring& text, const std::wstring& title);
AlertAsync calls MessageBoxW on a detached background thread, so it returns immediately without blocking the UI loop. Guard every call to it: 
#ifdef _WIN32
    menu->AddItem(L"Alert", []()
    {
        AlertAsync(L"Background message", L"Title");
    });
#endif

​
Linux

On Linux, EnterTerminal uses POSIX terminal APIs:
  • Saves the current termios state with tcgetattr.
  • Puts the terminal into raw mode: disables canonical processing, echo, signal generation (ISIG), and output post-processing.
  • Writes ANSI escape sequences to switch to the alternate screen buffer and hide the cursor.
ExitTerminal restores the saved termios state and returns to the normal screen buffer. Input is read using poll with the configured timeout, and escape sequences are decoded manually to produce InputEvent values for arrow keys and special characters.
A UTF-8 locale must be active for wide-character rendering to work correctly on Linux. EnterTerminal calls setlocale(LC_ALL, "") and attempts to imbue std::wcout, but if no UTF-8 locale is installed on the system a warning is printed and rendering may be incorrect.

​
Quick start

git clone https://github.com/Rikitav/Terminality.git
cd Terminality
mkdir build && cd build
cmake ..
cmake --build .
Open the repository in Visual Studio 2022 and use the CMake project support, or run from the Developer Command Prompt:
cmake -G "Visual Studio 17 2022" ..
cmake --build . --config Release

Build docs developers (and LLMs) love

Get started for freeTalk to us