# OpenLogi Development Setup: Using Nix/devenv or rustup for Reproducible Rust Builds

> Set up OpenLogi development with Nix/devenv for reproducible Rust builds or rustup. Targets MSRV for consistent toolchain management. Get started easily.

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

---

**You can set up OpenLogi development using either a Nix/devenv environment for fully reproducible builds or a traditional rustup-managed toolchain, both targeting the MSRV defined in [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml).**

OpenLogi is a multi-crate Rust workspace maintained by AprilNEA that controls Logitech devices through an open-source stack. Whether you choose **Nix/devenv** or **rustup**, both workflows install Rust 1.98 (the workspace MSRV) and provide access to the `xtask` helper scripts for CI validation and packaging.

## Setting Up OpenLogi Development with Nix and devenv

The Nix workflow provides a hermetic environment where all native dependencies—such as `libudev` on Linux and macOS frameworks—are pinned to exact versions in `devenv.nix`.

### Install Nix and Enable Flakes

Install the Nix package manager with flakes support enabled:

```bash
sh <(curl -L https://nixos.org/nix/install) --daemon
mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf

```

Then install the `devenv` CLI:

```bash
nix profile install nixpkgs#devenv

```

### Initialize the Development Environment

Clone the repository and enter the shell:

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

```

This command reads `devenv.nix` and [`devenv.yaml`](https://github.com/AprilNEA/OpenLogi/blob/main/devenv.yaml) to create a shell with the exact Rust toolchain, Cargo, Clippy, rustfmt, and all native libraries pre-installed. The environment automatically exports `OPENLOGI_DEV_AGENT=0` to prevent stray background agents from interfering with fresh runs.

### Verify the Build and Run CI Tasks

Run a quick compile check on the core crate:

```bash
cargo check -p openlogi-core

```

Execute the full local CI suite using the `xtask` helper:

```bash
cargo xtask ci

```

This runs the same checks as GitHub Actions, including linting, formatting, and unit tests defined in the workspace [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml).

## Setting Up OpenLogi Development with rustup

For developers who prefer a traditional toolchain manager, **rustup** provides a lightweight alternative to Nix. You must manually install system dependencies, but the Rust toolchain installation remains automated.

### Install rustup and the MSRV Toolchain

Install rustup and match the workspace's minimum supported Rust version:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install 1.98
rustup default 1.98

```

Add required components for linting and formatting:

```bash
rustup component add rustfmt clippy

```

Optionally install the `cargo-xtask` helper globally:

```bash
cargo install --path xtask

```

### Install Native Dependencies

Unlike the Nix environment, rustup requires manual installation of native libraries. On Debian/Ubuntu, install `libudev-dev` for the `openlogi-hid` crate. macOS users must install Xcode command-line tools (`xcode-select --install`) to compile Metal shaders for the GPUI-based desktop application.

### Build and Test the Workspace

Verify compilation and run the full test suite:

```bash
cargo check -p openlogi-core
cargo test --workspace
cargo xtask ci

```

Launch the desktop client with:

```bash
cargo run -p openlogi-desktop

```

## Common Development Commands

Both workflows support the same Cargo commands for daily development:

```bash

# Run all unit tests

cargo test --workspace

# Run HID++ protocol tests for fast feedback

cargo test -p openlogi-hidpp

# Format the entire codebase

cargo fmt --all

# Lint with Clippy (CI treats warnings as errors)

cargo clippy --workspace --all-targets -- -D warnings

# Build the release agent binary

cargo build -p openlogi-agent --release

```

## Key Configuration Files

Understanding these files helps troubleshoot build issues across both setups:

- **`devenv.nix`** — Declares the Nix development environment, including Rust toolchain components and native libraries like `libudev`.
- **[`devenv.yaml`](https://github.com/AprilNEA/OpenLogi/blob/main/devenv.yaml)** — Human-readable configuration consumed by the `devenv` CLI for shell hooks and service orchestration.
- **[`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml)** — Pins the exact Rust version (MSRV 1.98) and components required by the workspace.
- **[`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml)** (workspace root) — Defines workspace members and shared dependency versions across crates.
- **[`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md)** — Documents helper commands such as `cargo xtask ci` for local CI replication.
- **[`crates/openlogi-desktop/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/README.md)** — Contains GUI-specific instructions and device pairing troubleshooting.

## Summary

- OpenLogi requires **Rust 1.98** (MSRV) as specified in [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml), regardless of which setup method you choose.
- **Nix/devenv** provides a reproducible environment with all native dependencies pre-installed, activated via `devenv up`.
- **rustup** offers a traditional workflow but requires manual installation of system libraries like `libudev-dev` on Linux or Xcode tools on macOS.
- The **`cargo xtask`** commands documented in [`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md) provide unified CI, packaging, and documentation generation across both environments.
- Both setups support building the desktop client via `cargo run -p openlogi-desktop` and the background agent via `cargo build -p openlogi-agent`.

## Frequently Asked Questions

### What is the minimum Rust version required for OpenLogi development?

OpenLogi requires **Rust 1.98**, defined as the MSRV in [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml). The Nix environment automatically provides this version, while rustup users must manually install it with `rustup toolchain install 1.98`.

### Can I use a newer Rust version than the MSRV with OpenLogi?

While newer stable toolchains often work, running `cargo xtask ci` will warn you if your version diverges from [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml). For consistent CI results matching the repository's GitHub Actions, use the pinned 1.98 toolchain.

### How do I run the OpenLogi desktop application without physical hardware?

Execute `cargo run -p openlogi-desktop` from either environment. The application automatically spawns a mock agent if no Logitech device is detected. Alternatively, manually start the mock agent with `cargo run -p openlogi-agent --bin openlogi-agent-mock`.

### Do I need to install cargo-xtask separately when using devenv?

No. The `cargo xtask` subcommand works automatically within the Nix/devenv shell because the `xtask` crate is defined as a workspace member in the root [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml). rustup users may optionally install it globally with `cargo install --path xtask`, but this is not required as `cargo xtask` invokes the local crate directly.