# How to Build OpenLogi From Source: Complete Installation Guide

> Learn how to build OpenLogi from source. Follow our complete guide to install using the stable Rust toolchain, system libraries, and Cargo commands for CLI, GUI, or packaged binaries.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-04

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash
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:

```bash

# 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:

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

```

The workspace [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md) and handle code signing, resource packaging, and installer generation.

### macOS Bundles

Create a signed `.app` bundle for local testing:

```bash
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:

```bash
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:

```bash
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:

```bash

# 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:

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

```

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

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.