vectorscan/scripts/README-Windows-ARM64.md

Windows ARM64 Build Instructions

This document provides instructions for building Vectorscan on Windows ARM64 machines using MinGW-w64.

CI/CD Status

This repository includes automated GitHub Actions that build and test the ARM64 Windows version on every push and pull request. See CI Documentation for details.

Prerequisites

1. Windows ARM64 machine (Windows 10 version 1903+ or Windows 11)
2. MSYS2 installed from https://www.msys2.org/

Quick Start

1. Install MSYS2 and open the MINGW64 terminal
2. Run the environment setup script:

   ./setup-env.sh
   

3. Build the project:

   ./build-windows-arm64.sh
   

Manual Setup (Alternative)

If you prefer to set up the environment manually:

1. Install MSYS2

Download and install MSYS2 from https://www.msys2.org/

2. Update MSYS2

Open MSYS2 MINGW64 terminal and run:

pacman -Syu

3. Install MinGW-w64 ARM64 Toolchain

pacman -S mingw-w64-clang-aarch64-gcc \
          mingw-w64-clang-aarch64-g++ \
          mingw-w64-clang-aarch64-cmake \
          mingw-w64-clang-aarch64-make \
          mingw-w64-clang-aarch64-pkg-config

4. Install Dependencies

pacman -S mingw-w64-clang-aarch64-boost \
          mingw-w64-clang-aarch64-sqlite3 \
          mingw-w64-clang-aarch64-ragel \
          mingw-w64-clang-aarch64-pcre

5. Build the Project

# Navigate to the project directory
cd /path/to/vectorscan-ming

## Ensure your PATH has the clangarm64 toolset
export PATH="/clangarm64/bin:$PATH"

# Create build directory
mkdir build-windows-arm64
cd build-windows-arm64

# Configure
cmake .. \
    -G "MinGW Makefiles" -DCMAKE_MAKE_PROGRAM="mingw32-make" \
    -DCMAKE_SYSTEM_NAME=Windows \
    -DCMAKE_SYSTEM_PROCESSOR=ARM64 \
    -DCMAKE_C_COMPILER="$CC" \
    -DCMAKE_CXX_COMPILER="$CXX" \
    -DCMAKE_AR="$AR" \
    -DCMAKE_RANLIB="$RANLIB" \
    -DCMAKE_FIND_ROOT_PATH_MODE_PROGRAM=NEVER \
    -DCMAKE_FIND_ROOT_PATH_MODE_LIBRARY=ONLY \
    -DCMAKE_FIND_ROOT_PATH_MODE_INCLUDE=ONLY \
    -DBUILD_STATIC_LIBS=ON \
    -DBUILD_SHARED_LIBS=ON \
    -DFAT_RUNTIME=ON \
    -DBUILD_AVX2=OFF \
    -DBUILD_AVX512=OFF \
    -DBUILD_SVE=OFF \
    -DBUILD_SVE2=OFF \
    -DSIMDE_BACKEND=OFF \
    -DSIMDE_NATIVE=OFF \
    -DBUILD_UNIT=ON \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_C_FLAGS="-D_WIN32_WINNT=0x0A00 -DWIN32_LEAN_AND_MEAN" \
    -DCMAKE_CXX_FLAGS="-D_WIN32_WINNT=0x0A00 -DWIN32_LEAN_AND_MEAN -Wno-deprecated-declarations -Wno-error=deprecated-declarations"

# Build
mingw32-make -j$(nproc)

Output Files

After a successful build, you'll find the following files:

Static Libraries

• lib/libhs.a - Main Vectorscan library
• lib/libhs_runtime.a - Runtime-only library

Shared Libraries (DLLs)

• bin/hs.dll - Main Vectorscan DLL
• bin/hs_runtime.dll - Runtime-only DLL

Import Libraries

• lib/libhs.dll.a - Import library for hs.dll
• lib/libhs_runtime.dll.a - Import library for hs_runtime.dll

Headers

• Header files in the source tree can be used for compilation

Features Supported

• ARM NEON: Fully supported (Windows ARM64 guarantees NEON availability)
• SVE/SVE2: Currently disabled on Windows (not exposed by Windows APIs)
• Static Linking: Supported
• Dynamic Linking: Supported

Limitations

1. Fat Runtime: Disabled on Windows ARM64
2. SVE/SVE2: Not currently supported on Windows
3. Unit Tests: Disabled by default for cross-compilation

Using the Libraries

Static Linking Example

// Compile with: aarch64-w64-mingw32-gcc -I/path/to/headers main.c -L/path/to/lib -lhs -lws2_32
#include "hs.h"

int main() {
    // Your Vectorscan code here
    return 0;
}

Dynamic Linking Example

// Compile with: aarch64-w64-mingw32-gcc -I/path/to/headers main.c -L/path/to/lib -lhs
// Make sure hs.dll is in PATH or same directory as executable
#include "hs.h"

int main() {
    // Your Vectorscan code here
    return 0;
}

Troubleshooting

Compiler Not Found

If you get "ARM64 cross-compiler not found", ensure you've installed the ARM64 toolchain:

pacman -S mingw-w64-clang-aarch64-gcc mingw-w64-clang-aarch64-g++

CMake Configuration Fails

Make sure you're running in the MINGW64 environment and have CMake installed:

pacman -S mingw-w64-clang-aarch64-cmake

Missing Dependencies

Install all required dependencies:

pacman -S mingw-w64-clang-aarch64-boost \
          mingw-w64-clang-aarch64-ragel \
          mingw-w64-clang-aarch64-pcre

Build Errors

1. Check that all Windows-specific modifications are in place
2. Ensure you're using the correct compiler flags
3. Verify that ARM64 target detection is working

Architecture Detection

The build system now properly detects Windows ARM64 targets by checking for:

• _M_ARM64 (MSVC-style macro)
• __ARM_ARCH_ISA_A64 (GCC-style macro)

CPU Feature Detection

On Windows ARM64, the build system:

• Automatically enables NEON support (guaranteed on Windows ARM64)
• Uses Windows APIs for feature detection where available
• Falls back to safe defaults for unsupported features

Performance Notes

• NEON SIMD instructions provide good performance on ARM64
• SVE support may be added in future Windows versions
• Performance should be competitive with x86_64 builds for most workloads