# How to Set Up the OpenLogi Development Environment: Complete Guide

> Easily set up the OpenLogi development environment with this complete guide. Install Rust, system libraries, and launch the GUI with simple commands.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: getting-started
- Published: 2026-08-22

---

**OpenLogi requires Rust stable (edition 2024, MSRV 1.98), platform-specific system libraries such as Xcode 16 on macOS or `libudev-dev` on Linux, and optionally Nix/devenv for reproducible builds; clone the repository and run `cargo run -p openlogi-desktop --release` to launch the GPUI-based GUI.**

OpenLogi is a multi-process Rust application consisting of a **GPUI desktop client**, a background agent for HID++ communication, and supporting crates for input injection and asset handling. Setting up the OpenLogi development environment involves installing the Rust toolchain, obtaining platform-specific dependencies, and configuring your workspace to build the GUI and agent binaries. This guide references the canonical instructions in [[`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md)](https://github.com/AprilNEA/OpenLogi/blob/master/docs/DEVELOPMENT.md) and the Nix configuration in [`devenv.nix`](https://github.com/AprilNEA/OpenLogi/blob/master/devenv.nix).

## Prerequisites by Platform

OpenLogi targets edition 2024 and requires a minimum Rust version (MSRV) of 1.98. You must install the stable toolchain via **rustup** before proceeding.

On **macOS**, install **Xcode 16 or later with the Metal Toolchain**, which is mandatory for GPUI shader compilation. No additional Homebrew packages are required beyond the Xcode command line tools.

On **Linux**, install the following system libraries before building:

```bash
sudo apt-get install libudev-dev gcc g++ clang \
    libfontconfig-dev libwayland-dev libxkbcommon-x11-dev \
    libx11-xcb-dev libssl-dev libzstd-dev pkg-config

```

On **Windows**, no extra system toolchain is required beyond the Rust compiler; both the GUI and agent build as native binaries using the standard MSVC or GNU toolchain.

## Choosing a Build Strategy

You can configure the OpenLogi development environment **with or without Nix**. Both approaches are documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md).

**Without Nix**, you manually install the Rust toolchain and platform libraries listed above, then use standard Cargo commands. This path is suitable if you prefer to manage dependencies locally.

**With Nix/devenv**, the repository provides a `devenv.nix` file that provisions all required packages, environment variables, and helper tools like **sccache**. Run `devenv shell` or `direnv allow` to enter a reproducible shell with all dependencies pre-configured.

## Cloning and Initial Build

Clone the repository and verify your setup by building the CLI and desktop components:

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

# Optional: enter the Nix development shell

devenv shell

# Build and run the CLI to list paired devices

cargo run -p openlogi --release -- list

# Build and run the desktop GUI (development bundle)

cargo run -p openlogi-desktop --release

```

The `cargo run -p openlogi-desktop` command invokes the runner defined in [[`.cargo/config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/.cargo/config.toml)](https://github.com/AprilNEA/OpenLogi/blob/master/.cargo/config.toml), which handles macOS bundle creation automatically.

## Developing the GUI Without Physical Hardware

When no Logitech devices are attached, use the **mock agent** to simulate the agent IPC contract:

```bash

# Terminal 1: start the mock agent

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

# Terminal 2: launch the desktop client, skipping auto-agent startup

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

```

This workflow allows UI development against the mock implementation in `crates/openlogi-agent` without requiring physical HID++ hardware.

## Essential Development Commands

OpenLogi provides several task runners for common workflows. If using Nix, invoke them via `devenv tasks run`:

| Command | Purpose |
|---------|---------|
| `devenv tasks run openlogi:gui` | Launch the desktop GUI using the GPUI stack. |
| `devenv tasks run openlogi:check` | Run the host-OS gate (formatting, clippy, tests, rustdoc). |
| `devenv tasks run openlogi:ci` | Execute all CI jobs reproducible on the current host. |
| `cargo xtask ci` | Equivalent CI runner without requiring devenv. |
| `cargo run -p xtask -- macos package` | Build the macOS DMG (`target/release/OpenLogi.dmg`). |
| `cargo run -p xtask -- linux package` | Build Linux packages (`.deb`, `.rpm`, `.pkg.tar.zst`). |

These commands are implemented in the `xtask/` directory and documented in the "Local CI" and "Packaging" sections of the Development guide.

## Environment Variables for Advanced Configuration

The OpenLogi build system respects several environment variables defined in the development environment:

- **`OPENLOGI_DEV_BUNDLE=0`** — Run the raw `openlogi-desktop` binary without the macOS bundle wrapper.
- **`OPENLOGI_DEV_AGENT=0`** — Prevent the runner from automatically spawning the real agent; useful when manually running the mock agent.
- **`OPENLOGI_BUNDLE_ASSETS=1`** — Embed all device renders inside the macOS app bundle for offline builds.
- **`OPENLOGI_SIGN_IDENTITY=<identity>`** — Specify a codesigning identity for macOS release builds.

Set these variables before invoking `cargo run` or `cargo build` to override default behaviors in the build scripts and runners.

## Verifying Your Setup

Before submitting changes, run the full pre-push gate to ensure the workspace compiles cleanly across all crates:

```bash
export RUSTFLAGS="-D warnings"
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \
  --document-private-items --exclude openlogi-ui --exclude openlogi-desktop \
  --exclude openlogi-overlay --exclude openlogi-agent

```

These commands mirror the "Pre‑push gate" section in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) and verify formatting, linting, tests, and documentation generation.

## Summary

- **Rust 1.98+** (edition 2024) is required; install via rustup.
- **macOS** requires Xcode 16+ with Metal Toolchain; **Linux** requires `libudev-dev`, `clang`, and Wayland/X11 development libraries.
- Choose between **standard Cargo** or **Nix/devenv** (via `devenv.nix`) for dependency management.
- Use `cargo run -p openlogi-agent --bin openlogi-agent-mock` and `OPENLOGI_DEV_AGENT=0` to develop the GUI without hardware.
- Run `cargo xtask ci` or `devenv tasks run openlogi:ci` to verify changes locally before pushing.

## Frequently Asked Questions

### Is Nix required to build OpenLogi?

No. Nix is optional. You can build OpenLogi using standard Cargo commands after installing the Rust toolchain and platform-specific system libraries. The Nix configuration in `devenv.nix` simply provides a reproducible environment with all dependencies pre-installed.

### Can I develop the OpenLogi GUI on Windows?

Yes. Windows requires no additional system toolchains beyond the Rust compiler. You can run `cargo run -p openlogi-desktop --release` directly, though the mock agent workflow (`cargo run -p openlogi-agent --bin openlogi-agent-mock`) remains the same for hardware-free development.

### What is the mock agent used for?

The mock agent (`openlogi-agent-mock`) simulates the IPC contract between the desktop GUI and the background agent. It allows you to develop and test the UI in `crates/openlogi-desktop` without owning physical Logitech HID++ devices, as documented in the "Developing the GUI without hardware" section.

### What does MSRV 1.98 mean for contributors?

MSRV (Minimum Supported Rust Version) 1.98 indicates the oldest Rust compiler version guaranteed to compile the project. Contributors should ensure their `rustup` default toolchain is 1.98 or newer, or use the Nix shell which pins the correct version automatically.