Merge pull request #1329 from spkenv/windows-cross-compilation

Enable Arch Linux to Windows cross-compilation workflow

Author: jrray

.cargo/config.toml

@@ -0,0 +1,3 @@
+[target.x86_64-pc-windows-gnu]
+linker = "x86_64-w64-mingw32-gcc"
+ar = "x86_64-w64-mingw32-gcc-ar"

.github/workflows/rust.yml

@@ -23,6 +23,56 @@ jobs:
         uses: crazy-max/ghaction-chocolatey@v3
         with:
           args: install protoc llvm winfsp make
+      - name: Verify Chocolatey packages and retry if needed
+        # The chocolatey install step can partially succeed: if the
+        # Chocolatey CDN returns a transient error (e.g. 504 Gateway
+        # Timeout) for one package, other packages may still install
+        # fine and the step exits successfully. This leaves the build
+        # missing critical dependencies, causing confusing failures
+        # later (e.g. winfsp-sys build.rs panic). This step verifies
+        # that all required packages are actually present and retries
+        # any that are missing.
+        shell: pwsh
+        run: |
+          function Test-Packages {
+            $missing = @()
+            if (-not (Test-Path "C:\Program Files (x86)\WinFsp")) {
+              $missing += "winfsp"
+            }
+            if (-not (Get-Command protoc -ErrorAction SilentlyContinue)) {
+              $missing += "protoc"
+            }
+            if (-not (Get-Command make -ErrorAction SilentlyContinue)) {
+              $missing += "make"
+            }
+            if (-not (Get-Command clang -ErrorAction SilentlyContinue)) {
+              $missing += "llvm"
+            }
+            return $missing
+          }
+
+          $missing = Test-Packages
+          if ($missing.Count -eq 0) {
+            Write-Host "All required packages verified successfully."
+            exit 0
+          }
+
+          $maxRetries = 2
+          for ($attempt = 1; $attempt -le $maxRetries; $attempt++) {
+            Write-Host "::warning::Missing packages: $($missing -join ', '). Retry attempt $attempt of $maxRetries..."
+            Start-Sleep -Seconds 15
+            choco install $missing -y --allow-unofficial
+            $missing = Test-Packages
+            if ($missing.Count -eq 0) {
+              Write-Host "All required packages verified successfully after retry."
+              exit 0
+            }
+          }
+
+          foreach ($pkg in $missing) {
+            Write-Host "::error::Required package not installed after retries: $pkg"
+          }
+          exit 1
       - name: Install FlatBuffers Compiler
         run: |
           $url = "https://github.com/google/flatbuffers/releases/download/v23.5.26/Windows.flatc.binary.zip"
@@ -146,7 +196,7 @@ jobs:
           crates/spfs/tests/integration/run_privileged_tests.sh
 
   matrix-build:
-    name: build features ${{ matrix.no-default-features }} ${{ matrix.features }}
+    name: build ${{ matrix.platform }} features ${{ matrix.no-default-features }} ${{ matrix.features }}
     runs-on: ubuntu-latest
     timeout-minutes: 45
     container:
@@ -159,12 +209,24 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        platform:
+          - linux
         features:
           # SPI's standand features
           - migration-to-components,sentry,spfs/protobuf-src,spfs-vfs/protobuf-src,statsd,fuse-backend-rhel-7-6
         no-default-features:
           - ""
           - --no-default-features
+        target:
+          - ""
+        exclude_crates:
+          - ""
+        include:
+          - platform: windows
+            features: server,spfs/server
+            no-default-features: ""
+            target: x86_64-pc-windows-gnu
+            exclude_crates: --exclude spfs-cli-winfsp --workspace
     steps:
       - name: Cancel Previous Runs
         uses: styfle/cancel-workflow-action@0.11.0
@@ -179,6 +241,11 @@ jobs:
           curl --proto '=https' --tlsv1.2 -sSfL ${FB_REL}/download/v23.5.26/Linux.flatc.binary.g++-10.zip | funzip > /usr/bin/flatc
           chmod +x /usr/bin/flatc
           rustup component add clippy
+      - name: Setup cross-compilation
+        if: matrix.platform == 'windows'
+        run: |
+          apt-get install -y gcc-mingw-w64-x86-64
+          rustup target add ${{ matrix.target }}
       - name: Configure cargo
         run: |
           mkdir -p .cargo
@@ -188,6 +255,14 @@ jobs:
           # can't cache incremental compiles.
           incremental = false
           EOF
+      - name: Configure cross-compile linker
+        if: matrix.platform == 'windows'
+        run: |
+          cat << 'EOF' >> .cargo/config.toml
+          [target.x86_64-pc-windows-gnu]
+          linker = "x86_64-w64-mingw32-gcc"
+          ar = "x86_64-w64-mingw32-gcc-ar"
+          EOF
       - name: Run sccache-cache
         uses: mozilla-actions/sccache-action@v0.0.9
       - name: Restore ast-grep cache
@@ -213,3 +288,5 @@ jobs:
           ${{ matrix.no-default-features }}
           --features "${{ matrix.features }}"
           --all-targets
+          ${{ matrix.target && format('--target {0}', matrix.target) || '' }}
+          ${{ matrix.exclude_crates }}

.gitignore

@@ -33,3 +33,5 @@ target/
 .cache/
 .hugo_build.lock
 /.cargo/
+!/.cargo/
+!/.cargo/config.toml

Cross.toml

@@ -1,2 +1,7 @@
 [target.x86_64-pc-windows-gnu]
-pre-build = ["apt-get install -y protobuf-compiler"]
+pre-build = [
+    "apt-get update && apt-get install -y protobuf-compiler curl unzip",
+    "curl --proto '=https' --tlsv1.2 -sSfL https://github.com/google/flatbuffers/releases/download/v23.5.26/Linux.flatc.binary.g++-10.zip | funzip > /usr/local/bin/flatc",
+    "chmod +x /usr/local/bin/flatc",
+    "cargo install --locked ast-grep",
+]

Makefile

@@ -9,6 +9,7 @@ cargo_features_arg = $(if $(FEATURES),--features $(FEATURES))
 cargo_packages_arg := $(if $(CRATES),-p=$(CRATES))
 cargo_packages_arg := $(subst $(comma), -p=,$(cargo_packages_arg))
 cargo_packages_arg := $(if $(cargo_packages_arg),$(cargo_packages_arg),--workspace)
+cargo_excludes_arg ?=
 
 # Suppress this warning to not muddle the test output.
 export SPFS_SUPPRESS_OVERLAYFS_PARAMS_WARNING = 1
@@ -54,11 +55,11 @@ lint-fmt:
 
 .PHONY: lint-clippy
 lint-clippy:
-	$(CARGO) clippy --tests $(cargo_features_arg) $(cargo_packages_arg) $(CARGO_ARGS) -- -Dwarnings
+	$(CARGO) clippy --tests $(cargo_features_arg) $(cargo_packages_arg) $(cargo_excludes_arg) $(CARGO_ARGS) -- -Dwarnings
 
 .PHONY: lint-docs
 lint-docs:
-	env RUSTDOCFLAGS="-Dwarnings" cargo doc --no-deps $(cargo_features_arg) $(cargo_packages_arg)
+	env RUSTDOCFLAGS="-Dwarnings" cargo doc --no-deps $(cargo_features_arg) $(cargo_packages_arg) $(cargo_excludes_arg)
 
 .PHONY: format
 format:
@@ -68,13 +69,13 @@ format:
 build: debug
 
 debug:
-	$(CARGO) build $(cargo_packages_arg) $(cargo_features_arg) $(CARGO_ARGS)
+	$(CARGO) build $(cargo_packages_arg) $(cargo_excludes_arg) $(cargo_features_arg) $(CARGO_ARGS)
 
 debug-spfs:
 	$(MAKE) debug CRATES=$(spfs_packages)
 
 release:
-	$(CARGO) build --release $(cargo_packages_arg) $(cargo_features_arg) $(CARGO_ARGS)
+	$(CARGO) build --release $(cargo_packages_arg) $(cargo_excludes_arg) $(cargo_features_arg) $(CARGO_ARGS)
 
 release-spfs:
 	$(MAKE) release CRATES=$(spfs_packages)

Makefile.linux

@@ -8,10 +8,16 @@ CARGO_TARGET_DIR := $(shell \
 
 export PLATFORM ?= unix
 ifeq ($(PLATFORM),windows)
-spfs_packages := $(spfs_packages),spfs-cli-winfsp
-CARGO_ARGS += --target x86_64-pc-windows-gnu
-# swap cargo for cross when building for other platforms
-CARGO = cross
+WINDOWS_TARGET ?= x86_64-pc-windows-gnu
+CARGO_ARGS += --target $(WINDOWS_TARGET)
+# winfsp-sys requires a Windows host in its build script, so exclude the
+# winfsp CLI crate for Linux-hosted workspace cross-compiles.
+cargo_excludes_arg += $(if $(CRATES),,--exclude spfs-cli-winfsp)
+# Default to cargo for Linux -> Windows cross-compilation. This works on
+# Arch Linux with mingw-w64-gcc. To use containerized cross, set:
+#   WINDOWS_CARGO=cross
+WINDOWS_CARGO ?= cargo
+CARGO = $(WINDOWS_CARGO)
 else
 spfs_packages := $(spfs_packages),spfs-cli-fuse,spfs-cli-monitor
 endif

README.md

@@ -234,6 +234,42 @@ ast-grep is also used when compiling, it can be installed with the following com
 cargo install --locked ast-grep
 ```
 
+### Cross-Compiling for Windows from Arch Linux
+
+You can cross-compile Windows binaries on Arch Linux without Docker by using
+the GNU Windows target and MinGW tools.
+
+```sh
+sudo pacman -S --needed \
+    mingw-w64-gcc \
+    protobuf \
+    flatbuffers \
+    ast-grep
+rustup target add x86_64-pc-windows-gnu
+```
+
+Then build with:
+
+```sh
+make release PLATFORM=windows FEATURES=server,spfs/server
+```
+
+Output binaries are written to:
+
+```text
+target/x86_64-pc-windows-gnu/release/
+```
+
+When cross-compiling from Linux, workspace builds automatically exclude
+`spfs-cli-winfsp` because `winfsp-sys` requires running its build script on a
+Windows host. Build that crate natively on Windows if needed.
+
+If you prefer containerized cross-compilation, install `cross` and run:
+
+```sh
+make release PLATFORM=windows WINDOWS_CARGO=cross FEATURES=server,spfs/server
+```
+
 ### Benchmarks
 
 Benchmark tests can be found in `benches/`. All benchmark tests can be run with `cargo bench`, but in order to successfully pass `criterion`-specific options to the `criterion`-based benchmarks, those types of benchmarks need to be filtered for.

cspell.json

@@ -522,6 +522,7 @@
     "OWYWHJKCVRKGSBL",
     "OXFB",
     "OYMIQUY",
+    "pacman",
     "parsedbuf",
     "parsewords",
     "partio",

docs/admin/install.md

@@ -22,3 +22,21 @@ make install-spfs # only spfs
 Currently, only spfs is supported on windows and is still considered experimental. File systems can be mounted and viewed, but not modified. See above on building from source - windows builds will require WinFSP to be installed rather than fuse libraries.
 
 <!-- TODO: include really basic make instructions as above for playing with this -->
+
+### Cross-Compile for Windows From Arch Linux
+
+To cross-compile from Arch Linux, install:
+
+```sh
+sudo pacman -S --needed mingw-w64-gcc protobuf flatbuffers ast-grep
+rustup target add x86_64-pc-windows-gnu
+```
+
+Then build:
+
+```sh
+make release PLATFORM=windows FEATURES=server,spfs/server
+```
+
+For Linux-hosted workspace builds, `spfs-cli-winfsp` is excluded because its
+`winfsp-sys` dependency requires a Windows host during build-script execution.