How to Build OpenLogi From Source: Complete Installation Guide

Building OpenLogi from source requires the stable Rust toolchain (MSRV 1.98), platform-specific system libraries, and Cargo commands to compile the workspace crates into CLI, GUI, or packaged binaries.

OpenLogi is a pure-Rust workspace that provides Logitech device management through a GPUI-based desktop application and background agent. Whether you need to compile a development build for testing or create a production release bundle, the repository's Cargo.toml workspace structure and xtask helpers streamline the process across macOS, Linux, and Windows.

Prerequisites and Toolchain Setup

Before you can build OpenLogi from source, install the Rust toolchain and platform-specific dependencies as documented in docs/DEVELOPMENT.md.

macOS Requirements

macOS builds require Xcode 26 or newer with the Metal toolchain to compile GPUI shaders. Install the Xcode command-line tools and ensure the Metal SDK is available:

xcode-select --install

The Metal dependency is critical for the openlogi-desktop crate's rendering pipeline.

Linux Requirements

Linux systems need development headers for udev, fontconfig, and Wayland. Install the required packages before compiling:

# Debian/Ubuntu

sudo apt-get install libudev-dev libfontconfig-dev libwayland-dev

# Fedora/RHEL

sudo dnf install systemd-devel fontconfig-devel wayland-devel

These libraries enable HID device access and native GUI rendering in the crates/openlogi-agent/ and crates/openlogi-desktop/ components.

Windows Requirements

Windows only requires the standard Rust toolchain from rustup. While pre-built binaries are code-signed, source compilation works with any recent stable Rust compiler without additional system dependencies.

Cloning and Compiling the Workspace

Clone the repository and verify your toolchain can compile the default workspace member:

git clone https://github.com/AprilNEA/OpenLogi
cd OpenLogi

The workspace Cargo.toml defines crates/openlogi as the default member, meaning a plain cargo build produces only the CLI binary. To build specific components, target their respective crates using the -p flag.

Build the CLI Binary

Run a quick sanity check to verify compilation works:

cargo run -p openlogi --release -- list

This compiles the openlogi crate and executes the list subcommand to enumerate connected Logitech devices.

Building Specific Components

Desktop GUI Application

The main graphical interface is located in crates/openlogi-desktop/. Compile and run the full desktop app with:

cargo run -p openlogi-desktop --release

This command builds the GPUI-based GUI and the openlogi-agent background process, linking against platform-specific graphics APIs.

Background Agent

To build only the background agent that handles HID I/O and input hooks:

cargo build -p openlogi-agent --release

The agent binary resides in crates/openlogi-agent/ and manages device communication independently of the GUI frontend.

Packaging and Distribution

OpenLogi includes an xtask helper crate for creating platform-specific release bundles. These commands are defined in xtask/README.md and handle code signing, resource packaging, and installer generation.

macOS Bundles

Create a signed .app bundle for local testing:

cargo run -p xtask -- macos bundle

This outputs target/dev/OpenLogi.app marked as "OpenLogi Dev" in the Dock. For distribution, generate a release DMG:

cargo run -p xtask -- macos package

The package command produces target/release/OpenLogi.dmg ready for notarization and distribution.

Linux Packages

Generate native package formats (.deb, .rpm, or .pkg.tar.zst) using the same xtask interface:

cargo run -p xtask -- linux package

This creates distribution packages in target/release/ suitable for installation via dpkg, rpm, or pacman depending on your host distribution.

Optional Development Workflows

Nix/devenv Environment

For reproducible builds, the repository includes a devenv.nix configuration that provisions the Rust toolchain, system libraries, and utilities like create-dmg and sccache. Enter the development shell and run predefined tasks:

# Launch the GUI with all dependencies provided

devenv tasks run openlogi:gui

# Run formatting, clippy, tests, and rustdoc checks

devenv tasks run openlogi:check

# Reproduce all CI jobs supported on this host

devenv tasks run openlogi:ci

These tasks execute the host-OS gate and validation pipeline without manual environment setup.

Hardware-Free GUI Development

Develop the desktop interface without physical Logitech hardware using the mock agent. Start the mock agent in one terminal:

cargo run -p openlogi-agent --bin openlogi-agent-mock

Then launch the desktop GUI in another terminal with the development agent endpoint:

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

The mock agent provides a scripted device inventory, enabling rapid UI iteration while the openlogi-desktop binary connects to the simulated backend.

Summary

• Install the Rust toolchain (MSRV 1.98) and platform libraries: Xcode 26+ (macOS), libudev-dev/libwayland-dev (Linux), or standard Rust (Windows).
• Clone and build using cargo run -p openlogi --release for the CLI or cargo run -p openlogi-desktop --release for the full GUI.
• Package releases with the xtask helper: cargo run -p xtask -- macos package or linux package for distribution-ready installers.
• Use devenv for reproducible development environments with pre-configured tasks for building, testing, and CI verification.
• Develop without hardware by running the mock agent and setting OPENLOGI_DEV_AGENT=0 when launching the desktop binary.

Frequently Asked Questions

What is the minimum Rust version required to build OpenLogi?

OpenLogi requires Rust 1.98 (MSRV) or newer. This version requirement is enforced in the workspace Cargo.toml to ensure compatibility with dependencies used across the crates/ directory.

Why does the desktop build fail on macOS with Metal errors?

The openlogi-desktop crate compiles GPUI shaders that require Xcode 26 or newer with the Metal toolchain. Install the latest Xcode command-line tools and ensure the Metal SDK is present in /Library/Developer/CommandLineTools/SDKs/.

How do I create a distributable package instead of just compiling binaries?

Use the xtask helper crate included in the repository. Run cargo run -p xtask -- macos package to generate a signed DMG on macOS, or cargo run -p xtask -- linux package to build .deb, .rpm, or Arch packages. These commands handle resource bundling and code signing automatically.

Can I develop the GUI without owning Logitech hardware?

Yes. Build and run the mock agent binary (cargo run -p openlogi-agent --bin openlogi-agent-mock), then launch the desktop with OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop. This connects the GUI to a simulated device inventory for interface development without physical HID devices.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}