# How OpenLogi Uses cfg-Gated Platform Code Per Crate Without Violating Abstraction

> Discover how OpenLogi cfg-gates platform code per crate without abstraction violations. Learn to isolate OS-specific functionality using Cargo and Rust conditional compilation for a uniform API.

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

---

**OpenLogi isolates OS-specific functionality by combining Cargo's target-specific dependency sections with Rust's conditional compilation attributes, ensuring platform code is cfg-gated at the crate level while exposing a uniform trait-based API.**

The AprilNEA/OpenLogi repository demonstrates a systematic approach to cross-platform Rust development where each crate controls its own platform-specific code through conditional compilation. By leveraging `[target.'cfg(...)'.dependencies]` in Cargo.toml and `#[cfg(target_os = "...")]` attributes throughout the source, the project maintains strict abstraction boundaries without leaking OS details into the public API.

## Target-Specific Dependencies in Cargo.toml

Each crate declaratively specifies its platform requirements through Cargo's target-specific dependency sections. This ensures that OS-specific libraries are only fetched and linked when building for that target.

In [`crates/openlogi-core/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/Cargo.toml), the project declares macOS-only dependencies using the target configuration syntax:

```toml
[target.'cfg(target_os = "macos")'.dependencies]
core-graphics = "0.22"
objc = "0.2"

```

This configuration at line 41 ensures that crates like **CoreGraphics** and **objc** are excluded entirely when compiling for Linux or Windows, reducing compile times and binary bloat while preventing accidental usage of platform-specific APIs on the wrong target.

## Conditional Compilation with #[cfg] Attributes

Within source files, OpenLogi uses the `#[cfg(target_os = "...")]` attribute to gate entire modules, structs, and function implementations. This compile-time filtering ensures that only code relevant to the current target platform reaches the LLVM backend.

The hook crate demonstrates this pattern extensively in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs) between lines 555 and 664, where macOS-specific hook implementations are wrapped in conditional compilation guards:

```rust
#[cfg(target_os = "macos")]
mod macos {
    use super::*;
    
    pub struct MacOSHook;
    
    impl Hook for MacOSHook {
        fn install(&self) -> Result<()> {
            // macOS-specific implementation
        }
    }
}

```

Similarly, the HID transport layer in [`crates/openlogi-hid/src/transport.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hid/src/transport.rs) at line 70 uses `#[cfg]` guards to select between macOS, Windows, and Linux transport implementations, ensuring that platform-specific I/O mechanisms never collide.

## Maintaining Abstraction via Traits

The architectural core of OpenLogi's platform isolation relies on **traits** that define generic behavior, with platform-specific implementations hidden behind cfg-gated modules. This pattern allows the rest of the codebase to depend on abstract interfaces like `DeviceIO` or `Injector` without knowing which OS is running underneath.

Consider this simplified pattern from the codebase:

```rust
// Abstract trait visible to all platforms
pub trait Injector {
    fn inject(&self, event: InputEvent);
}

// macOS implementation - compiled only on macOS
#[cfg(target_os = "macos")]
mod macos {
    use super::Injector;
    pub struct MacInjector;
    
    impl Injector for MacInjector {
        fn inject(&self, event: InputEvent) {
            // macOS-specific CGEvent code
        }
    }
}

// Linux implementation - compiled only on Linux
#[cfg(target_os = "linux")]
mod linux {
    use super::Injector;
    pub struct LinuxInjector;
    
    impl Injector for LinuxInjector {
        fn inject(&self, event: InputEvent) {
            // Linux-specific evdev code
        }
    }
}

// Public export aliases the correct implementation
#[cfg(target_os = "macos")]
pub use macos::MacInjector as PlatformInjector;
#[cfg(target_os = "linux")]
pub use linux::LinuxInjector as PlatformInjector;

```

This approach ensures that `PlatformInjector` is always available with a consistent interface, but the concrete type backing it changes based on the target triple.

## Crate-Level Isolation and Entry Points

OpenLogi enforces platform isolation at the crate boundary, meaning that a change to macOS-specific code in one crate cannot break the Linux build of another. The agent crate's entry point in [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) at line 13 uses `#![cfg_attr(...)]` to conditionally compile platform-specific main functions:

```rust
#![cfg_attr(target_os = "macos", allow(dead_code))]

```

This granular control extends to the CI strategy, where the project avoids the "macOS-green is a trap" anti-pattern by ensuring that platform-specific crates are tested independently. Because each crate owns its conditional sections, developers cannot accidentally import a macOS-specific module while working on Linux code—the compiler simply won't find the symbols, catching cross-platform violations at compile time rather than runtime.

## Summary

- **Target-specific dependencies** in [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml) prevent OS-specific crates from being compiled on incompatible platforms, as seen in [`crates/openlogi-core/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/Cargo.toml) at line 41.
- **Conditional compilation** via `#[cfg(target_os = "...")]` attributes gates source files and modules, demonstrated extensively in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs) between lines 555-664.
- **Trait-based abstraction** exposes uniform APIs like `Injector` and `DeviceIO` while hiding platform-specific implementations behind cfg-gated re-exports.
- **Crate-level isolation** ensures platform code changes remain localized, with entry points like [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) using compile-time guards to select the correct platform module.

## Frequently Asked Questions

### What prevents cfg-gated code from leaking into public APIs?

OpenLogi uses **trait abstraction** to ensure that public structs and functions accept or return generic trait objects rather than concrete platform types. While platform-specific implementations exist behind `#[cfg]` guards, the public API only exposes the trait interface, making the cfg-gating an internal implementation detail that doesn't affect consumer code.

### How does OpenLogi handle platform-specific dependencies that aren't available on other OSes?

The project leverages Cargo's `[target.'cfg(...)'.dependencies]` sections, as shown in [`crates/openlogi-core/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/Cargo.toml) at line 41. This syntax ensures that dependencies like `core-graphics` and `objc` are only included when the target OS is macOS, preventing compilation failures on Linux or Windows where these crates would fail to build or link.

### Can a single crate support multiple platforms without code duplication?

Yes, through **modular architecture** and conditional compilation. Each platform implementation lives in its own module (e.g., `mod macos`, `mod linux`) guarded by `#[cfg]`. Common logic resides in platform-agnostic parent modules, while OS-specific behavior overrides provide the specializations. The `PlatformInjector` alias pattern ensures consumers always reference a single type regardless of the underlying platform.

### Why is crate-level cfg-gating preferable to feature flags for platform selection?

Crate-level **cfg-gating** uses the compiler's built-in `target_os` configuration rather than manual feature flags, preventing the "feature unification" problems where enabling a feature for one crate accidentally enables it for all dependents. This approach also integrates with Cargo's target-specific dependency resolution, ensuring that platform-specific native libraries (like IOKit or X11) are only fetched and linked when building for that specific target, which is impossible to guarantee with standard feature flags alone.