Complete Build Requirements for OpenLogi: Cross-Platform Rust Setup Guide

To compile OpenLogi from source, you need Rust 1.98+ (2024 edition) with rustfmt and clippy, platform-specific toolchains including Xcode 16 with Metal on macOS or specific system libraries on Linux, and the xtask utility for automated packaging.

OpenLogi is a Rust-based, cross-platform logistics application developed by AprilNEA that combines a GPUI-based desktop interface with a background agent and supporting crates. Building the project from the source code requires precise toolchain versions and platform-specific dependencies defined in rust-toolchain.toml and docs/DEVELOPMENT.md.

Rust Toolchain Requirements

OpenLogi uses modern Rust features and enforces strict code quality through its toolchain configuration.

Minimum Supported Rust Version (MSRV)

According to rust-toolchain.toml, the minimum supported Rust version (MSRV) is 1.98. The project uses the 2024 edition syntax and requires the rustfmt and clippy components for compilation and linting. The toolchain file automatically enforces these requirements when running cargo commands in the repository root.

Platform-Specific Build Dependencies

Each operating system requires additional tools beyond the base Rust installation to support OpenLogi's hardware interaction layers and GUI framework.

macOS Requirements (Xcode and Metal)

On macOS, you must install Xcode 16 or newer—the full IDE, not just the Command Line Tools. The build process specifically requires the Metal toolchain component for GPUI's shader compilation pipeline. You can verify installation by checking that metal and metallib commands are available in your terminal after launching Xcode to accept licenses.

Linux System Libraries

Linux builds require system libraries for HID device access and GPUI rendering. On Debian or Ubuntu systems, install the complete dependency set:

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

These packages support the underlying libudev HID layer and Wayland/X11 windowing backends used by the application.

Windows Build Environment

Windows developers need no manual compiler installation beyond the Rust toolchain. The repository automatically pulls in windows-sys for FFI bindings via Cargo.toml, and cargo leverages a recent Visual Studio toolchain installed via the Visual Studio Build Tools. Ensure you have the "Desktop development with C++" workload selected if installing Visual Studio manually.

Build and Packaging Tools

OpenLogi provides automated tooling for creating release bundles across platforms.

Optional Development Helpers

While not strictly required for compilation, several tools streamline the development workflow:

• create-dmg: Install via Homebrew to generate macOS disk images (brew install create-dmg)
• cargo-bundle: Automatically installed by the xtask utility for cross-platform app bundling
• devenv or Nix: Optional reproducible environment managers for containerized builds

Packaging Utilities

The xtask binary—implemented in xtask/src/main.rs—provides convenience commands for distribution packaging. This internal tool orchestrates nfpm for generating Linux packages (.deb, .rpm, and .pkg.tar.zst) and handles macOS app bundle creation through dispatched commands like macos bundle and linux package.

Step-by-Step Build Instructions

Follow these commands to build OpenLogi from the AprilNEA/OpenLogi repository:

# 1. Install the stable Rust toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Install platform-specific prerequisites (macOS: Xcode 16+; Linux: see apt command above)

# 3. Clone the repository

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

# 4. Build the CLI for a quick sanity check

cargo run -p openlogi --release -- list

# 5. Build the full desktop GUI

cargo run -p openlogi-desktop --release

The xtask dispatcher in xtask/src/main.rs handles complex build pipelines by parsing arguments and routing to the appropriate Cargo subcommands:

// src/main.rs of the xtask crate
fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("macos") => cargo_run("-p", "xtask", "--", "macos", "bundle"),
        Some("linux") => cargo_run("-p", "xtask", "--", "linux", "package"),
        _ => eprintln!("unknown xtask command"),
    }
}

Key Configuration Files

Understanding these files helps troubleshoot build failures:

• rust-toolchain.toml: Declares the Rust channel, edition 2024 requirements, and required components
• Cargo.toml (workspace root): Defines workspace members, MSRV, and external dependencies including windows-sys and gpui
• docs/DEVELOPMENT.md: Comprehensive guide covering platform toolchains and packaging commands
• xtask/src/main.rs: Build automation providing tasks like openlogi:gui, openlogi:bundle, and openlogi:ci

Summary

• Rust 1.98+ with edition 2024, rustfmt, and clippy is mandatory as specified in rust-toolchain.toml
• macOS requires full Xcode 16+ with the Metal toolchain for GPUI shader compilation
• Linux builds need specific system libraries including libudev-dev, libwayland-dev, and libssl-dev listed in docs/DEVELOPMENT.md
• Windows relies on windows-sys crates and automatically detects Visual Studio toolchains
• Use the xtask utility in xtask/src/main.rs to automate packaging with nfpm for Linux or create-dmg for macOS

Frequently Asked Questions

What is the minimum Rust version required to build OpenLogi?

OpenLogi requires Rust 1.98 as the minimum supported version (MSRV), using the 2024 edition syntax. This requirement is enforced by the rust-toolchain.toml file in the repository root, which also mandates the rustfmt and clippy components.

Can I build OpenLogi on macOS without installing full Xcode?

No, you cannot. While some Rust projects work with only the Command Line Tools, OpenLogi requires full Xcode 16 or newer because the GPUI framework needs the Metal toolchain component for shader compilation. The Command Line Tools alone do not provide the necessary Metal compilers.

Which Linux distributions are supported for building OpenLogi?

OpenLogi builds on any Linux distribution that can provide the required system libraries. The docs/DEVELOPMENT.md file specifically documents installation for Debian and Ubuntu using apt-get. Other distributions like Fedora or Arch can build the project by installing equivalent packages for libudev, wayland, fontconfig, and openssl development headers.

How do I create distributable packages after building OpenLogi?

Use the xtask automation tool provided in the repository. Running cargo run -p xtask -- macos bundle creates macOS application bundles (optionally with create-dmg for disk images), while cargo run -p xtask -- linux package generates .deb, .rpm, or Arch packages using nfpm. These commands are implemented in xtask/src/main.rs and handle the complex packaging logic automatically.

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