rlogg/CROSS_COMPILE.md

Cross-Compilation Guide

Build Windows binaries from Linux using Docker-based cross-compilation.

Prerequisites

1. Install Docker:

   # Ubuntu/Debian
   sudo apt-get install docker.io
   sudo usermod -aG docker $USER
   # Log out and back in for group changes to take effect
   

2. Verify Docker:

   docker --version
   

Quick Start

Option 1: Interactive Menu

./cross-compile.sh

Then select:

• 1 - Linux native
• 2 - Windows (MinGW)
• 3 - Both platforms
• 4 - Exit

Option 2: Command Line

./cross-compile.sh windows  # Windows (MinGW/GNU)
./cross-compile.sh all      # All platforms
./cross-compile.sh linux    # Linux native

Option 3: Make

make cross-windows  # Build for Windows
make cross-all      # Build for all platforms

What Gets Built

Binaries are created in the dist/ directory:

• rlogg-linux-x86_64 - Linux binary
• rlogg-windows-x86_64.exe - Windows binary (MinGW)

How It Works

The cross tool:

1. Automatically installs on first use
2. Uses Docker to run cross-compilation in containers
3. Provides complete toolchains for each target
4. No need to install Windows SDK or MinGW manually

About Windows Cross-Compilation

Why MinGW/GNU Only?

When cross-compiling from Linux to Windows, only the GNU target (x86_64-pc-windows-gnu) is supported:

• MinGW (GNU) - Uses open-source MinGW toolchain

  • ✅ Fully supported by cross from Linux
  • ✅ Works great for most Windows applications
  • ✅ Smaller binaries
  • ✅ No runtime dependencies on Visual C++ redistributables

• MSVC - Microsoft Visual C++ toolchain

  • ❌ Not available for cross-compilation from Linux
  • ❌ Requires proprietary Microsoft tools
  • ❌ Can only be built on Windows or via Windows VM

Compatibility

The MinGW binaries work on all Windows systems (Windows 7+) without requiring additional runtime installations. They're fully compatible with standard Windows applications.

Troubleshooting

Docker permission denied

sudo usermod -aG docker $USER
# Log out and back in

cross installation fails

# Install from source
cargo install cross --git https://github.com/cross-rs/cross

Build fails with linker errors

The cross tool handles all linker configuration automatically. If you see linker errors, try:

# Clean and rebuild
make clean
./cross-compile.sh windows

Very slow first build

The first build downloads the Docker image (~1-2 GB) and compiles dependencies. Subsequent builds are much faster due to caching.

Alternative: Manual Cross-Compilation (Advanced)

If you don't want to use Docker, you can manually set up cross-compilation:

For Windows from Linux

# Install MinGW
sudo apt-get install mingw-w64

# Add Rust target
rustup target add x86_64-pc-windows-gnu

# Configure cargo
mkdir -p ~/.cargo
cat >> ~/.cargo/config.toml << EOF
[target.x86_64-pc-windows-gnu]
linker = "x86_64-w64-mingw32-gcc"
EOF

# Build
cargo build --release --target x86_64-pc-windows-gnu

Note: This only works for the GNU target, not MSVC.

Testing Windows Binaries on Linux

Use Wine to test Windows binaries:

# Install Wine
sudo apt-get install wine64

# Run the Windows binary
wine dist/rlogg-windows-x86_64-gnu.exe

CI/CD Integration

The GitHub Actions workflow automatically cross-compiles for all platforms. Just push to trigger builds:

git push origin master

Artifacts are available in the Actions tab.

Performance Considerations

Cross-compilation is:

• Fast: Similar speed to native compilation
• Cached: Dependencies are cached in Docker volumes
• Isolated: Doesn't affect your system

Typical build times:

• First build: 2-5 minutes (includes Docker image download)
• Incremental builds: 30-60 seconds