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

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 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, 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:

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

# 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 – Windows-only injection logic
• crates/openlogi-inject/src/inject/macos.rs – macOS-only injection logic
• crates/openlogi-inject/src/inject/linux.rs – Linux-only injection logic

The high-level entry point in crates/openlogi-inject/src/inject.rs dispatches to these modules using cfg gates:

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, 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 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.
• Modular Architecture: Platform-specific implementations reside in dedicated files like 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 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, 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 and visible in the file structure of crates/openlogi-inject/src/inject/.

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