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

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.

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:

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:

nix profile install nixpkgs#devenv

Initialize the Development Environment

Clone the repository and enter the shell:

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

This command reads devenv.nix and 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:

cargo check -p openlogi-core

Execute the full local CI suite using the xtask helper:

cargo xtask ci

This runs the same checks as GitHub Actions, including linting, formatting, and unit tests defined in the workspace 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:

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:

rustup component add rustfmt clippy

Optionally install the cargo-xtask helper globally:

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:

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

Launch the desktop client with:

cargo run -p openlogi-desktop

Common Development Commands

Both workflows support the same Cargo commands for daily development:

# 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 — Human-readable configuration consumed by the devenv CLI for shell hooks and service orchestration.
• rust-toolchain.toml — Pins the exact Rust version (MSRV 1.98) and components required by the workspace.
• Cargo.toml (workspace root) — Defines workspace members and shared dependency versions across crates.
• xtask/README.md — Documents helper commands such as cargo xtask ci for local CI replication.
• 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, 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 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. 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. 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. 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.

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