Building

Mina Maher edited this page Apr 1, 2026 · 7 revisions

🔨 Building

📋 Prerequisites

Dependency	Version	Notes
🔧 CMake	>= 3.22	Build system
⚡ Ninja	any	Recommended generator (make works too)
💻 C++ compiler	C++20	GCC 12+ or Clang 15+
🎨 Qt 6	>= 6.4	Core, Quick, Svg, DBus, Widgets, Concurrent, Test, QuickTest
🔌 libudev	any	Device discovery via udev/hidraw
🧪 Google Test	any	Test framework (Ubuntu ships source only — needs manual build)
📦 pkg-config	any	Finds libudev

🎨 Qt 6 Modules

The project uses these Qt 6 modules (from CMakeLists.txt):

find_package(Qt6 REQUIRED COMPONENTS Core Quick Svg DBus Widgets Concurrent Test QuickTest)

Plus these QML modules at runtime:

qml6-module-qtquick, qml6-module-qtquick-controls, qml6-module-qtquick-layouts
qml6-module-qtquick-window, qml6-module-qtquick-templates
qml6-module-qtquick-dialogs, qml6-module-qt5compat-graphicaleffects
qml6-module-qttest (for QML tests)

🐧 Ubuntu 24.04

sudo apt-get install -y \
 build-essential cmake ninja-build pkg-config \
 qt6-base-dev qt6-declarative-dev qt6-svg-dev \
 qt6-tools-dev qt6-tools-dev-tools qt6-l10n-tools \
 qml6-module-qtquick qml6-module-qtquick-controls \
 qml6-module-qtquick-layouts qml6-module-qtquick-window \
 qml6-module-qtquick-templates qml6-module-qtqml-workerscript \
 qml6-module-qtquick-dialogs qml6-module-qt5compat-graphicaleffects \
 qt6-qpa-plugins libqt6opengl6-dev libqt6svg6-dev \
 libqt6dbus6 libqt6widgets6 libxkbcommon-dev \
 qml6-module-qttest libudev-dev libgtest-dev
# Build and install GTest (Ubuntu ships source only)
cd /usr/src/googletest && sudo cmake -B build && sudo cmake --build build && sudo cmake --install build

🏔️ Arch Linux

sudo pacman -S cmake ninja qt6-base qt6-declarative qt6-svg qt6-tools \
 qt6-5compat gtest libudev0-shim pkgconf

🚀 Build from Source

git clone https://github.com/logitune/logitune.git
cd logitune
# Configure + build
make build
# Run with debug logging
make run

The make build target runs:

cmake -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -Wno-dev
cmake --build build -j$(nproc)

🎯 Build Commands

The Makefile provides these targets:

Command	Description
`make build`	🔨 Build the project (Debug mode)
`make run`	▶️ Build and run the app with `--debug` (host only)
`make test`	🧪 Run C++ unit/integration tests
`make test-qml`	🎨 Run QML component tests
`make test-tray`	🔔 Run tray manager tests
`make test-all`	✅ Run all test tiers
`make flatpak-setup`	📀 Install Flatpak SDK (first time, ~2GB)
`make flatpak`	📦 Build and install Flatpak
`make release`	🏷️ Version bump, tag, Flatpak, GitHub release
`make setup-hooks`	🪝 Install git pre-push hook
`make clean`	🧹 Remove build artifacts
`make help`	❓ Show all targets

⚙️ CMake Options

Option	Default	Description
`BUILD_TESTING`	`ON`	Build test binaries
`BUILD_HW_TESTING`	`OFF`	Build hardware integration tests (requires connected device)
`CMAKE_BUILD_TYPE`	`Debug`	`Debug` or `Release`

📁 Project Structure

logitune/
├── CMakeLists.txt # Root CMake — project, Qt find, subdirs
├── Makefile # Developer convenience targets
├── com.logitune.Logitune.yml # Flatpak manifest
├── data/
│ ├── 71-logitune.rules # udev rules for hidraw + uinput
│ ├── com.logitune.Logitune.desktop
│ ├── com.logitune.Logitune.metainfo.xml
│ └── com.logitune.Logitune.svg
├── src/
│ ├── core/ # Static library: logitune-core
│ │ ├── CMakeLists.txt
│ │ ├── DeviceManager.cpp/h # Device lifecycle, HID++ orchestration
│ │ ├── DeviceRegistry.cpp/h
│ │ ├── ProfileEngine.cpp/h # Profile CRUD, app bindings, cache
│ │ ├── ActionExecutor.cpp/h
│ │ ├── ButtonAction.h
│ │ ├── hidpp/ # HID++ protocol layer
│ │ │ ├── HidppTypes.h # Report, FeatureId, ErrorCode
│ │ │ ├── HidrawDevice.h # Raw hidraw fd wrapper
│ │ │ ├── Transport.h # Send/receive with timeout + retry
│ │ │ ├── FeatureDispatcher.h # Feature table, call(), callAsync()
│ │ │ ├── CommandQueue.h # Paced sequential command sending
│ │ │ └── features/ # Per-feature param builders + parsers
│ │ ├── devices/
│ │ │ └── MxMaster3sDescriptor.cpp/h
│ │ ├── interfaces/
│ │ │ ├── IDevice.h # Device descriptor interface
│ │ │ ├── IDesktopIntegration.h
│ │ │ ├── IInputInjector.h
│ │ │ └── ITransport.h
│ │ ├── desktop/
│ │ │ ├── KDeDesktop.cpp/h # KDE/KWin integration
│ │ │ └── GenericDesktop.cpp/h
│ │ ├── input/
│ │ │ └── UinputInjector.cpp/h
│ │ └── logging/
│ │ ├── LogManager.cpp/h
│ │ └── CrashHandler.cpp/h
│ └── app/ # Static library: logitune-app-lib + executable
│ ├── CMakeLists.txt
│ ├── main.cpp # Entry point, QML engine, tray
│ ├── AppController.cpp/h # Main orchestrator
│ ├── TrayManager.cpp/h
│ ├── models/
│ │ ├── DeviceModel.h # QML-facing device state
│ │ ├── ButtonModel.h # QAbstractListModel for buttons
│ │ ├── ActionModel.h # Available actions catalog
│ │ └── ProfileModel.h # Profile tabs
│ ├── dialogs/
│ │ ├── CrashReportDialog.cpp/h
│ │ └── GitHubIssueBuilder.cpp/h
│ └── qml/
│ ├── Main.qml
│ ├── Theme.qml # Singleton with design tokens
│ ├── HomeView.qml
│ ├── DeviceView.qml
│ ├── pages/ # PointScrollPage, ButtonsPage, EasySwitchPage, SettingsPage
│ ├── components/ # SideNav, BatteryChip, DeviceRender, etc.
│ └── assets/ # Device images (PNG)
├── tests/
│ ├── CMakeLists.txt
│ ├── test_main.cpp # GTest main with QCoreApplication
│ ├── helpers/
│ │ ├── TestFixtures.h # ProfileFixture, ensureApp()
│ │ └── AppControllerFixture.h # Full integration test fixture
│ ├── mocks/
│ │ ├── MockDesktop.h/cpp
│ │ ├── MockTransport.h/cpp
│ │ ├── MockInjector.h/cpp
│ │ └── MockDevice.h
│ ├── test_*.cpp # C++ test files
│ ├── qml/
│ │ ├── tst_*.qml # QML component tests
│ │ └── tst_qml_main.cpp
│ └── hw/
│ ├── HardwareFixture.h
│ ├── hw_test_main.cpp
│ └── test_hw_*.cpp # Hardware integration tests
├── scripts/
│ ├── pre-push # Git hook: run all tests before push
│ └── release.sh
└── .github/workflows/
 ├── ci.yml # Build + test on push/PR
 └── release.yml # Flatpak bundle on tag push

📀 Flatpak Build

🛠️ First-Time Setup

make flatpak-setup

Note

This installs the Flathub remote and the KDE Platform/SDK 6.10 runtime (~2GB download).

📦 Build

On host (builds and installs locally):

make flatpak

In devcontainer (build only — no user session):

make flatpak

The Flatpak manifest (com.logitune.Logitune.yml) configures:

Setting	Value
🖥️ Runtime	`org.kde.Platform` 6.10
🔗 D-Bus	Talks to `org.kde.KWin` and `org.kde.kglobalaccel`, owns `com.logitune.app`
🔌 Device access	`--device=all` for hidraw
📁 Host filesystem	Read-only access to host `.desktop` files for the app profile picker
💾 Config persistence	`~/.config/Logitune` and `~/.local/share/Logitune` shared between host and sandbox

🐳 Devcontainer / GitHub Codespaces

The repository includes a devcontainer configuration for one-click development in VS Code or GitHub Codespaces.

📦 What's Included

The Dockerfile (/.devcontainer/Dockerfile) builds an Ubuntu 24.04 container with:

✅ All build dependencies (Qt 6, CMake, Ninja, GTest, libudev)
✅ Development tools (clangd, gdb, fish shell, bat, eza, ripgrep, fzf)
✅ Flatpak builder
✅ Nerd Font for terminal icons
✅ QT_QPA_PLATFORM=offscreen for headless testing

🧩 VS Code Extensions

The devcontainer auto-installs:

Extension	Purpose
`llvm-vs-code-extensions.vscode-clangd`	C++ language server
`ms-vscode.cmake-tools`	CMake integration
`theqtcompany.qt` / `qt-qml` / `qt-cpp`	Qt/QML support
`vscode-icons-team.vscode-icons`	File icons

🚀 Post-Create

On container creation, postCreateCommand runs:

make setup-hooks
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cmake --build build -j$(nproc)

Tip

The project is fully built and ready to test immediately after the container starts.

⚠️ Limitations

Warning

The devcontainer runs headless (QT_QPA_PLATFORM=offscreen), so:

✅ All tests run fine (C++, QML, tray)
❌ You cannot run the GUI application visually
❌ No hidraw access (no physical device tests)

🔄 CI Pipeline

The CI workflow (.github/workflows/ci.yml) runs on every push to master and every pull request:

graph LR
 A[Push / PR] --> B[Install Dependencies]
 B --> C[Configure CMake]
 C --> D[Build]
 D --> E[C++ Tests]
 D --> F[Tray Tests]
 D --> G[QML Tests]
 E --> H{All Pass?}
 F --> H
 G --> H

The release workflow (.github/workflows/release.yml) triggers on version tags (v*):

graph LR
 A[Tag Push v*] --> B[Install Flatpak Builder]
 B --> C[Install KDE SDK 6.10]
 C --> D[flatpak-builder]
 D --> E[Create Bundle]
 E --> F[GitHub Release]

Note

The release workflow builds a .flatpak bundle and creates a GitHub Release with auto-generated release notes.

Logitune Wiki

🏠 Home

📚 User Guide

🏗️ Architecture

🔧 Extending

🧪 Quality

Navigation Menu

Building

🔨 Building

📋 Prerequisites

🎨 Qt 6 Modules

🐧 Ubuntu 24.04

🏔️ Arch Linux

🚀 Build from Source

🎯 Build Commands

⚙️ CMake Options

📁 Project Structure

📀 Flatpak Build

🛠️ First-Time Setup

📦 Build

🐳 Devcontainer / GitHub Codespaces

📦 What's Included

🧩 VS Code Extensions

🚀 Post-Create

⚠️ Limitations

🔄 CI Pipeline

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally