How bismuth-forge/bismuth works
Main Components
• Build & Utility Infrastructure:
– Files like CMakeLists.txt, Makefile, various shell scripts (in /scripts and /github/scripts) show that the project is built using CMake and Make, and it includes scripts for building, testing, and installation.
• Core Functionality (src/core):
– This component (controller.cpp/hpp, qmldir, ts-proxy, etc.) handles the basic window tiling logic, configuration reading, and logic common to the application.
• Configuration and Integration with KDE Settings (src/config and src/kcm):
– The src/config directory contains configuration definitions and CMake configurations.
– The src/kcm folder contains the KDE Control Module (KCM) for configuring Bismuth from the System Settings. This includes QML user interface files and config definitions.
• Window Decorations (src/kdecoration):
– This module provides the window decoration logic (e.g., border-only decorations) integrating with Plasma’s appearance settings.
• KWin Scripting and Layout Engine (src/kwinscript):
– A large subtree in this folder shows the use of TypeScript for KWin scripting, layout algorithms (tile, cascade, spiral, etc.), and both the engine and controller pieces.
– This is where different window layout algorithms reside and where the tiling behavior is implemented.
• Testing & External Dependencies:
– The tests folder (with CMakeLists.txt and core tests) and the external/doctest library help set up automated testing.
Relationships and Interactions
• The KCM (in src/kcm) exposes configuration settings via a QML-based UI. When a user changes settings, these configurations are passed to the Core Functionality (src/core) and the Window Tiling logic.
• The Core Layer acts as a bridge between the configuration, user commands, and real-time window management.
• The KWin Script module (src/kwinscript) implements the actual tiling algorithms and layout management. It listens to window events triggered by the Plasma shell/KWin, processes them (often invoking layout-specific code), and then calls back into the core logic if needed.
• The Window Decoration module (src/kdecoration) uses the core logic’s decisions to alter window style and appearance.
• The build system and scripts ensure these components are compiled, tested, and packaged correctly.
Architectural Patterns and Key Technologies
• Modular Design: Each of the main components (core, config, KCM, decoration, and scripting) are organized into separate subdirectories with their own CMakeLists.txt files, indicating a highly modular structure.
• Integration Pattern: There is a clear separation between UI (KCM/QML), business logic (core and configuration), and the tiling engine (kwinscript). Data flows from the user configuration interface to the core logic and is then used to drive the KWin scripting engines.
• Technologies & Libraries:
– C++ (for core logic, kcm, decoration)
– TypeScript/JavaScript (for the kwinscript engine)
– Qt/QML (for UI components and QML plugins)
– CMake (for the build process)
– KDE Frameworks (to integrate with Plasma and KWin)
Specific Elements to Be Included
• Module/component with labels (e.g., “Src/Core”, “Src/KCM”, “Src/KWinScript”).