How to Set Up the OpenLogi Development Environment: Complete Guide

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/master/docs/DEVELOPMENT.md) and the Nix configuration in 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:

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.

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:

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

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

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 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.

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