161 lines
3.8 KiB
Markdown
161 lines
3.8 KiB
Markdown
# 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
|