Enable Windows Arm64

Overview

The skill automatically detects and enables Windows ARM64 compilation support in software projects. For a detailed case study of enabling ARM64 support in Visual Studio projects, see references/case-study-activemq-cpp.md.

Two situations, handled differently:

1. The project already builds on Windows (has CMake / a .vcxproj, MSVC-buildable). Add an ARM64 configuration/preset — the common case, covered by the scripts below.
2. The project only builds on Linux with make/GCC (GNU Makefile/autotools, #include <x86intrin.h>/<cpuid.h>/<sched.h>, no MSVC project files, no make/gcc on the Windows host). Adding -march=armv8-a to the Makefile does not work — the Makefile does not even run, and the source pulls in GCC/Linux-only headers and libc functions. Drive the VS-bundled clang directly and add a small Windows compat layer. See references/linux-make-to-windows-clang.md for the full, verified checklist.

Quick Start

# Enable ARM64 support in a project
python scripts/enable_arm64_workflow.py /path/to/project

# Without creating backups (use with version control)
python scripts/enable_arm64_workflow.py /path/to/project --no-backup

What It Does

1. Detects build system with priority: cmake > visual_studio > make > ninja > autotools > bazel > qmake > scons
2. Checks existing support - Reports if ARM64 is already enabled
3. Modifies build files - Adds ARM64 configurations if needed

What Gets Added

CMake

Adds a windows-arm64 configure preset to CMakePresets.json. This is non-intrusive and does not modify CMakeLists.txt.

Note: CMake projects typically work out-of-the-box for ARM64 once the preset is added.

{
  "name": "windows-arm64",
  "displayName": "Windows ARM64",
  "architecture": {
      "value": "ARM64",
      "strategy": "set"
  },
  "cacheVariables": {
      "CMAKE_BUILD_TYPE": "Release"
  }
}

Visual Studio

• Adds ARM64 platform to ProjectConfigurations
• Creates ARM64 PropertyGroups for Debug/Release
• Clones ItemDefinitionGroups (compiler/linker settings) - CRITICAL
• Updates .sln with ARM64 configurations

Important: Visual Studio projects require careful handling:

1. ItemDefinitionGroups must be cloned - Contains compiler flags, include paths, library paths
2. Dependency paths may need adjustment - e.g., $(APR_DIST)\$(PlatformName)\include → $(APR_DIST)\include\apr-2
3. External dependencies must be built for ARM64 - APR, OpenSSL, Boost, etc.

Make

For a Makefile that already builds on Windows (e.g. via mingw/clang on PATH), add an ARM64 branch:

ifeq ($(OS),Windows_NT)
    ifeq ($(PROCESSOR_ARCHITECTURE),ARM64)
        CFLAGS += -DWINDOWS_ARM64 -march=armv8-a
    endif
endif

⚠️ A GNU/Linux-only Makefile does NOT build this way on Windows ARM64. If the project is Linux/GCC-only (no make on the Windows host, source uses <x86intrin.h>/<cpuid.h>/<sched.h>, GCC dialect), this Make edit is a no-op — there is no make to run it, and even if there were, cl/GCC can't build the source. Do not rely on $(PROCESSOR_ARCHITECTURE) either: the Windows-ARM64 dev shell runs under x64 emulation and reports AMD64. Instead drive the VS-bundled clang (--target=aarch64-pc-windows-msvc -march=armv8-a+crypto) directly and add a Windows compat layer (-include win_compat.h + empty winshim/ stub headers), then optionally add a CMakeLists.txt. Full verified procedure: references/linux-make-to-windows-clang.md.

Supported Build Systems

Individual Scripts

For fine-grained control, use individual scripts:

# Detect only
python scripts/detect_build_system.py /path/to/project

# Check only
python scripts/check_arm64_support.py cmake CMakeLists.txt

# Enable specific file
python scripts/enable_cmake_arm64.py CMakeLists.txt
python scripts/enable_visual_studio_arm64.py project.vcxproj
python scripts/enable_make_arm64.py Makefile

Common Scenarios

Multi-build system project: Only the highest priority system is modified.

Already has ARM64: Script reports existing support and exits.

Multiple build files: All files of the detected build system are modified.

Backup Files

By default, .bak files are created for build systems that require file modification (Visual Studio, Make, etc.). CMake support connects via CMakePresets.json and does not require backups of source files.

Restore others with:

mv Makefile.bak Makefile

Troubleshooting

No build system detected: Ensure build files exist and contain valid syntax.

Modification failed: Check file permissions and syntax validity.

Wrong build system selected: Use individual scripts to target specific files.

GCC/Linux Source on Windows ARM64 (clang path)

make / gcc not found, or the Makefile "runs" but nothing is built for ARM64:

• The project is Linux/GCC-only. Don't patch the Makefile — build with the VS-bundled clang directly. See references/linux-make-to-windows-clang.md.

fatal error: 'x86intrin.h' file not found (or cpuid.h, emmintrin.h):

• x86-only compiler headers. Arch-guard the include and provide a NEON path: #if defined(_M_ARM64) || defined(_M_ARM64EC) || defined(__aarch64__) ... #else #include <x86intrin.h> #endif.

fatal error: 'sched.h' file not found (or unistd.h, netinet/in.h):

• Linux OS headers. Add empty stub headers under winshim/ + -Iwinshim, and supply the real symbols via -include win_compat.h (sched_setaffinity→ SetThreadAffinityMask, ntohl→_byteswap_ulong, ftime→_ftime, a compact getopt, strcasecmp→_stricmp). Don't stub headers clang actually ships (e.g. <sys/timeb.h>).

always_inline function 'vmull_p64' requires target feature 'aes' (or vaes*, vsha*):

• PMULL/AES/SHA are gated behind +crypto. Add -march=armv8-a+crypto. These are baseline on Windows ARM64 — enable at compile time, no runtime guard needed.

argument to '__builtin_neon_vgetq_lane_i64' must be a constant integer:

• A NEON lane index came from a runtime value. Lane selection must be compile-time constant — use fixed-lane macros, not a computed index (see the CRC32 PMULL spec in sse-avx-to-neon).

Visual Studio Specific Issues

Build fails with "cannot open include file":

• Check dependency paths in ItemDefinitionGroup
• Verify environment variables point to ARM64 versions
• Example: $env:APR_DIST = "C:\apr-arm64"

Linker errors (LNK1181, LNK2001):

• Ensure all libraries are built for ARM64
• Check AdditionalLibraryDirectories paths
• Verify library names (e.g., libapr-2.lib not libapr-1.lib)

Platform 'ARM64' not found:

• Install Visual Studio 2022 ARM64 build tools
• Go to: Visual Studio Installer → Modify → Individual Components
• Search: "ARM64" and install "MSVC v143 - VS 2022 C++ ARM64 build tools"

ItemDefinitionGroup missing:

• Re-run the script (older versions didn't clone ItemDefinitionGroups)
• Manually verify: Open .vcxproj and search for Condition="'$(Configuration)|$(Platform)'=='Release|ARM64'"
• Should appear in both <PropertyGroup> AND <ItemDefinitionGroup>