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 package-deb`	Build a `.deb` package
`make package-rpm`	Build an `.rpm` package
`make package-arch`	Build an Arch package
`make install`	Install to system (`/usr/local`)
`make uninstall`	Remove system install
`make release`	Version bump, tag, push
`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
├── data/
│   ├── 71-logitune.rules       # udev rules for hidraw + uinput
│   ├── com.logitune.Logitune.desktop
│   ├── com.logitune.Logitune.metainfo.xml
│   ├── com.logitune.Logitune.svg
│   └── gnome-extension/        # GNOME Shell extension for focus tracking
│       ├── metadata.json        # Extension UUID and supported Shell versions
│       ├── v42/extension.js     # GNOME 42-44 (imports-based API)
│       └── v45/extension.js     # GNOME 45+ (ES modules API)
├── 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/
│   │   │   ├── LinuxDesktopBase.cpp/h  # Shared .desktop resolution + app listing
│   │   │   ├── KDeDesktop.cpp/h        # KDE/KWin integration
│   │   │   ├── GnomeDesktop.cpp/h      # GNOME Shell extension 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
├── pkg/
│   └── obs/                    # OBS packaging files
│       ├── _service            # Source service config
│       ├── logitune.spec       # RPM spec (Fedora + openSUSE)
│       ├── logitune.dsc        # Debian source descriptor
│       ├── debian.control      # Debian deps
│       ├── debian.rules        # Debian build rules
│       └── debian.changelog
├── scripts/
│   ├── pre-push                # Git hook: run all tests before push
│   └── release.sh
└── .github/workflows/
    ├── ci.yml                  # Multi-distro build + test on push/PR
    └── release.yml             # Native packages on tag push

Native Package Builds

Ubuntu / Debian (.deb)

make package-deb
sudo apt install ./logitune-VERSION_amd64.deb

The .deb package installs the binary, udev rules (71-logitune.rules), and .desktop file. udev rules are activated automatically on install, so no manual udevadm steps are required.

Fedora / RHEL (.rpm)

make package-rpm
sudo dnf install logitune-VERSION.rpm

Arch Linux

make package-arch   # builds with makepkg

Or install from AUR directly. The package installs udev rules and reloads them via a post_install hook.

System Install from Source

make install    # installs to /usr/local, copies udev rules, reloads udev
make uninstall  # removes all installed files

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)
Nerd Font for terminal icons
QT_QPA_PLATFORM=offscreen for headless testing

VS Code Extensions

The devcontainer auto-installs:

llvm-vs-code-extensions.vscode-clangd — C++ language server
ms-vscode.cmake-tools — CMake integration
theqtcompany.qt, theqtcompany.qt-qml, theqtcompany.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)

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

Limitations

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 across three distros:

graph TB
    A[Push / PR] --> Matrix

    subgraph Matrix["Build Matrix"]
        Arch[Arch Linux]
        Fedora[Fedora 42]
        Ubuntu[Ubuntu 24.04]
    end

    Arch --> BuildA[Build + Verify Files]
    Fedora --> BuildF[Build + Verify Files]
    Ubuntu --> BuildU[Build + Test]

    BuildU --> E[C++ Tests]
    BuildU --> F[Tray Tests]
    BuildU --> G[QML Tests]

Each distro job builds the project and verifies the binary and installed files exist. The Ubuntu job additionally runs all three test tiers with QT_QPA_PLATFORM=offscreen.

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

graph LR
    A[Tag Push v*] --> B[Build .deb]
    A --> C[Build .rpm]
    A --> D[Build Arch package]
    B --> E[GitHub Release]
    C --> E
    D --> E

It builds native packages for each distro family and creates a GitHub Release with auto-generated release notes.

OBS (openSUSE Build Service) Packages

Logitune is also published via OBS for one-command installation:

Ubuntu 24.04: sudo apt install logitune (after adding the OBS repo)
Fedora 42: sudo dnf install logitune (after adding the OBS repo)

The OBS packaging files are in pkg/obs/:

File	Purpose
`_service`	Source service — pulls from GitHub, strips non-release dirs
`logitune.spec`	RPM spec with openSUSE/Fedora conditionals
`logitune.dsc`	Debian source package descriptor
`debian.control`	Debian build/runtime dependencies
`debian.rules`	Debian build rules (skips hardware tests)
`debian.changelog`	Debian changelog

See Getting Started for the full install commands.

_{Logitune — Linux configurator for Logitech peripherals · Source · GPL-3.0}

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

Native Package Builds

Ubuntu / Debian (.deb)

Fedora / RHEL (.rpm)

Arch Linux

System Install from Source

Devcontainer / GitHub Codespaces

What's Included

VS Code Extensions

Post-Create

Limitations

CI Pipeline

OBS (openSUSE Build Service) Packages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally