Rust on Windows ARM64 - Setup Guide

_rust-setup.md

Rust on Windows - Setup Guide

Instructions for setting up Rust on Windows, depending on your architecture.

Architectures

• AMD64 (x86_64) — standard Intel/AMD processors
• ARM64 (AArch64) — Snapdragon/Qualcomm ARM-based Windows devices

rust-setup-amd64.md

Rust on Windows x86_64 (AMD64) - Setup Guide

Installation Steps

1. Install Visual Studio Build Tools

winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

Restart your PC after installation.

2. Install Rust

Download and run rustup from https://rustup.rs/ or use winget:

winget install Rustlang.Rustup

Rustup will automatically select the stable-x86_64-pc-windows-msvc toolchain.

3. Fix Git Bash linker conflict

Git Bash ships /usr/bin/link (a coreutils hard-link tool) which shadows MSVC's link.exe. Cargo will fail with:

link: extra operand '...'

Fix by prepending the MSVC tools directory to PATH in ~/.bashrc:

# Prepend MSVC tools so link.exe resolves to MSVC linker, not /usr/bin/link
for _msvc_dir in "/c/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/"*/bin/Hostx64/x64; do
  [ -d "$_msvc_dir" ] && export PATH="$_msvc_dir:$PATH" && break
done
unset _msvc_dir

The glob pattern handles MSVC version changes automatically.

Restart your terminal, then verify:

$ which link
/c/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.44.35207/bin/Hostx64/x64/link

4. Verify it works

rustc --version
cargo --version

cargo new test-project
cd test-project
cargo build --release
./target/release/test-project.exe

Output should be: Hello, world!

Daily Usage

# Create a new project
cargo new myproject
cd myproject

# Development builds
cargo build
cargo run

# Release builds
cargo build --release
./target/release/myproject.exe

Summary

Install VS Build Tools + Rust via winget, fix the Git Bash linker conflict in ~/.bashrc, and cargo build works out of the box.

rust-setup-arm64.md

Rust on Windows ARM64 - Setup Guide

Problem

Running cargo build on Windows ARM64 fails with:

error: linker `rust-lld-link` not found

This happens because Rust defaults to aarch64-pc-windows-msvc which requires MSVC ARM64 libraries that aren't installed by default.

Solution

Build for x86_64 and let Windows ARM64 run binaries through emulation. This works transparently and is fine for development.

Installation Steps

1. Install Rust

Download and run rustup from https://rustup.rs/ or use winget:

winget install Rustlang.Rustup

2. Set x86_64 as the default toolchain

rustup default stable-x86_64-pc-windows-msvc --force-non-host

3. Verify it works

cargo new test-project
cd test-project
cargo build --release
./target/release/test-project.exe

Output should be: Hello, world!

Daily Usage

# Create a new project
cargo new myproject
cd myproject

# Development builds
cargo build
cargo run

# Release builds
cargo build --release

# The binary is x86_64 but runs on ARM64 via emulation
./target/release/myproject.exe

Current Configuration

$ rustup show
Default host: x86_64-pc-windows-msvc

installed toolchains
--------------------
stable-aarch64-pc-windows-msvc
stable-x86_64-pc-windows-msvc (active, default)

Tested Projects

Successfully built and tested:

• rustkyll (static site generator) - 5m 22s build time, 115 dependencies

Building Native ARM64 Binaries

For release builds targeting native ARM64, use GitHub Actions. GitHub's windows-latest runners have full Visual Studio with ARM64 tooling pre-installed.

Example workflow:

name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-pc-windows-msvc
      - run: cargo build --release --target aarch64-pc-windows-msvc
      - uses: softprops/action-gh-release@v2
        with:
          files: target/aarch64-pc-windows-msvc/release/*.exe

Summary

Use x86_64 target for local development, GitHub Actions for release builds targeting ARM64.