# Validating Cross-Platform cfg-Gated Code on a Single OS: The OpenLogi Approach

> Learn how OpenLogi validates cross-platform cfg-gated code on a single OS using a robust CI matrix and documented rules, ensuring compatibility across Windows, macOS, and Linux.

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

---

**OpenLogi relies on a comprehensive CI matrix and documented cross-platform rules to validate cfg-gated code across Windows, macOS, and Linux, even when individual developers work exclusively on one operating system.**

OpenLogi is a Rust-based project that isolates operating system-specific functionality behind `#[cfg(target_os = "...")]` attributes. Because contributors often develop on only one platform, the repository employs automated continuous integration and strict local linting policies to ensure all conditional compilation paths remain correct.

## The Challenge of Single-OS Development with cfg Gates

Rust’s conditional compilation enables clean abstractions, but it creates a verification blind spot: code behind `#[cfg(target_os = "windows")]` is invisible to the compiler on macOS or Linux. When a developer modifies [`crates/openlogi-inject/src/inject/windows.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs) from a macOS workstation, the local `cargo check` skips the Windows module entirely, allowing syntax errors or type mismatches to go undetected until runtime on another platform.

## CI-Driven Cross-Compilation Matrix

According to the source code in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml), OpenLogi implements a multi-OS CI matrix that forces every cfg-gated branch to compile regardless of the runner’s native platform. The workflow executes separate jobs on **Ubuntu**, **macOS**, and **Windows**, each building the entire workspace.

Crucially, the macOS job performs explicit cross-compilation to prevent platform-specific regressions:

```yaml
build-macos:
  runs-on: macos-latest
  steps:
    - uses: actions/checkout@v3
    - name: Cross‑compile Windows & Linux on macOS
      run: |
        cargo check --target x86_64-pc-windows-gnu
        cargo check --target x86_64-unknown-linux-gnu
    - name: Build macOS crates
      run: cargo check --workspace

```

This configuration guarantees that a change breaking the Windows injection logic will fail on the macOS runner before merge, eliminating the "works on my machine" syndrome.

## Local Cross-Lint and Pre-Commit Validation

The repository’s internal policy documented in [`.claude/rules/cross-platform.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/cross-platform.md) establishes a "cross-platform green" status requirement. Developers cannot claim a feature is complete without verifying compilation on all supported targets, either through CI or local cross-lint checks.

Before submitting pull requests, contributors are advised to run targeted cross-compilation commands on their host machine. For example, a developer on macOS can validate the Windows and Linux modules without leaving their terminal:

```bash

# Validate Windows target from macOS

cargo check --target x86_64-pc-windows-gnu

# Validate Linux target from macOS  

cargo check --target x86_64-unknown-linux-gnu

```

These commands force Cargo to resolve all `#[cfg]` attributes for the specified target triples, surfacing compilation errors in platform-specific code that would otherwise remain dormant.

## Module Structure and Platform-Specific Implementations

OpenLogi organizes platform-specific logic into separate modules within relevant crates. The `openlogi-inject` crate demonstrates this pattern clearly:

- [`crates/openlogi-inject/src/inject/windows.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs) – Windows-only injection logic
- [`crates/openlogi-inject/src/inject/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/macos.rs) – macOS-only injection logic  
- [`crates/openlogi-inject/src/inject/linux.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/linux.rs) – Linux-only injection logic

The high-level entry point in [`crates/openlogi-inject/src/inject.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject.rs) dispatches to these modules using cfg gates:

```rust
pub fn inject(action: Action) {
    #[cfg(target_os = "windows")]
    windows::inject(action);   // compiled only on Windows

    #[cfg(target_os = "macos")]
    macos::inject(action);     // compiled only on macOS

    #[cfg(target_os = "linux")]
    linux::inject(action);     // compiled only on Linux
}

```

Each CI job compiles all three variants, ensuring that a breaking change in any single file triggers an immediate build failure.

## Policy Enforcement and Governance

The cross-platform validation strategy extends beyond CI configuration. As noted in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), the project maintains explicit documentation listing which crates contain cfg-gated code and referencing the cross-platform rule. This governance layer ensures that new contributors understand the requirement to verify inactive compilation paths.

The CI workflow runs `cargo check`, `cargo clippy`, and the full test suite for each platform. This comprehensive approach catches not only compilation errors but also lint warnings and runtime test failures specific to individual operating systems.

## Summary

- **CI Matrix Validation**: The GitHub Actions workflow in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) runs builds on Linux, macOS, and Windows runners, with macOS explicitly cross-compiling for other targets to force resolution of all cfg branches.
- **Local Cross-Lint**: Developers can run `cargo check --target <triple>` to validate inactive platform code before pushing, as mandated by [`.claude/rules/cross-platform.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/cross-platform.md).
- **Modular Architecture**: Platform-specific implementations reside in dedicated files like [`crates/openlogi-inject/src/inject/windows.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs), gated by `#[cfg(target_os = "...")]` attributes.
- **Strict Policy**: The "cross-platform green" rule prevents merging code that hasn't been verified on all supported operating systems.

## Frequently Asked Questions

### How does CI catch cfg-gated compilation errors if the code is inactive on the runner?

The CI workflow uses explicit cross-compilation targets. Even when running on macOS, the job executes `cargo check --target x86_64-pc-windows-gnu`, which forces the Rust compiler to evaluate the `#[cfg(target_os = "windows")]` branches and detect errors in the Windows-specific modules.

### Can I validate Windows-specific code on macOS without a Windows machine?

Yes. By installing the appropriate target toolchain and running `cargo check --target x86_64-pc-windows-gnu`, you can verify that the Windows-specific code in [`crates/openlogi-inject/src/inject/windows.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs) compiles correctly. While this doesn't replace runtime testing, it catches compilation errors and type mismatches.

### What is the "cross-platform green" rule in OpenLogi?

According to [`.claude/rules/cross-platform.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/rules/cross-platform.md), this rule states that a feature or fix cannot be considered complete until it achieves successful compilation and testing across all supported platforms—either through the CI matrix or through local cross-lint validation. Developers must re-read any changed cfg-gated files against the master branch before submitting pull requests.

### Which crates contain the most platform-specific cfg-gated code?

The primary crates implementing OS-specific functionality are `openlogi-inject`, `openlogi-hook`, and `openlogi-hid`. Each contains separate modules for Windows, macOS, and Linux implementations, as documented in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) and visible in the file structure of `crates/openlogi-inject/src/inject/`.