Skip to main content

ADR-021: Native Platform Builds

Status​

Accepted

Context​

Initially, catnet used a complex WSL (Windows Subsystem for Linux) bridge infrastructure to enable cross-platform development. This approach allowed developers to work in WSL while building and testing Windows-specific features like DirectX 12 rendering and OpenVR integration.

The WSL bridge consisted of:

  • Bidirectional file synchronization scripts
  • Cross-compilation toolchains
  • Remote command execution over SSH
  • Complex build scripts to manage the workflow

However, this approach had significant drawbacks:

  1. Complexity: 16+ shell scripts to maintain
  2. Fragility: Sync issues, permission problems, and timing bugs
  3. Performance: File sync overhead and SSH latency
  4. Debugging: Difficult to debug Windows-specific issues from WSL
  5. Onboarding: New developers struggled with the setup

As the project matured, we found that native development on each platform was more straightforward.

Decision​

We will use native builds on each platform instead of cross-compilation or WSL bridges.

Implementation​

  1. Windows Development

    • Use PowerShell or cmd.exe directly
    • Native cargo commands
    • Visual Studio or VS Code on Windows
    • Direct access to DirectX debugging tools

  2. Linux Development

    • Native Linux builds for CI/CD
    • Server-side components only
    • No Windows-specific features

  3. Simplified Workflow

    # Windows
    cargo build
    cargo test
    cargo run --example vr_dashboard_simple

    # Linux  
    cargo build --workspace
    cargo test --workspace

Consequences​

Positive​

  • Simplicity: Removed 1,500+ lines of bridge scripts
  • Reliability: No sync issues or timing problems
  • Performance: Direct builds are faster
  • Debugging: Native debuggers work properly
  • Onboarding: New developers just run cargo build

Negative​

  • Platform Switching: Developers must use Windows for VR development
  • Tool Differences: PowerShell vs Bash syntax differences
  • CI Complexity: Need both Windows and Linux runners

Neutral​

  • Development Environment: Developers choose their preferred platform
  • Code Sharing: Git handles cross-platform file transfer
  • Testing: Platform-specific tests run on appropriate OS

Migration​

The migration was completed in commit 51f06af, which:

  • Deleted all WSL sync scripts
  • Updated documentation to reference native commands
  • Replaced run_windows_test.sh with test_windows.ps1
  • Simplified CI/CD scripts

The new approach is: develop on the platform you're targeting. For VR features, use Windows. For server features, use either platform.