# Cross-Compilation Guide

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

## Prerequisites

1. **Install Docker**:
   ```bash
   # 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**:
   ```bash
   docker --version
   ```

## Quick Start

### Option 1: Interactive Menu
```bash
./cross-compile.sh
```

Then select:
- `1` - Linux native
- `2` - Windows (MinGW)
- `3` - Both platforms
- `4` - Exit

### Option 2: Command Line
```bash
./cross-compile.sh windows  # Windows (MinGW/GNU)
./cross-compile.sh all      # All platforms
./cross-compile.sh linux    # Linux native
```

### Option 3: Make
```bash
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
```bash
sudo usermod -aG docker $USER
# Log out and back in
```

### cross installation fails
```bash
# 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:
```bash
# 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
```bash
# 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:
```bash
# 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:
```bash
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