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

> Discover OpenLogi build requirements: Rust 1.98+, Xcode 16 or Linux libraries, and xtask. Get your cross-platform Rust project set up easily.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml) and [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

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

```

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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash

# 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`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) handles complex build pipelines by parsing arguments and routing to the appropriate Cargo subcommands:

```rust
// 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`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml)**: Declares the Rust channel, edition 2024 requirements, and required components
- **[`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml)** (workspace root): Defines workspace members, MSRV, and external dependencies including `windows-sys` and `gpui`
- **[`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md)**: Comprehensive guide covering platform toolchains and packaging commands
- **[`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md)
- **Windows** relies on `windows-sys` crates and automatically detects Visual Studio toolchains
- Use the **`xtask`** utility in [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) and handle the complex packaging logic automatically.