This page doesn’t try to be a complete porting guide, just a collection of the learnt approaches during porting Python packages and 3rd party libraries.

Common issues

• Start with x86/x64 build as a reference and understand the "clean" build flow if possible, before trying to fix it on win-arm64.

  • There are cases where Windows related packages are released, but still not all tests are passing and these are suppressed on CI.

    • Examples:

      • Pillow/Tests/test_image_access.py at main · python-pillow/Pillow

      • https://gitlab.freedesktop.org/freetype/freetype/-/commit/e990c33f218dc7ca619444e17b0bf5085b4b727c
        
        

• Historically Windows used to be equal to x86/x64, so Intel specific HW features are default enabled.

  • Example: Do not enable SSE feature for ARM64 by default by gaborkertesz-linaro · Pull Request #66 · ImageOptim/libimagequant

  • Example for a nice build error message:

    xmmintrin.h(27,1): fatal error C1189: #error: This header is specific to X86 and X64 targets -> Intel Streaming SIMD Extensions (SSE) HW feature is turned on, as wrong platform was selected by one of the compiler switches.

     

• Does the project include a Visual Studio project?

  • Open with VS and add ARM as new platform and try to build it.

    • Examples:

      • https://gitlab.freedesktop.org/freetype/freetype/-/commit/80bd4cba7eb25ecae313a6ac376ad6b363655243

      • Enable win-arm64 platform by gaborkertesz-linaro · Pull Request #397 · pnggroup/libpng

      • Add ARM64 to Visual Studio 2019 · mm2/Little-CMS@ade87cf
        
        

• Does the project include Arm assembly source file that could be reused for win-arm64?

  • MSVC compiler doesn’t call preprocessor for assembly files, like LLVM, so that should be done explicitly.

  • Example: libpng: Add MSVC assembly support for arm64 by gaborkertesz-linaro · Pull Request #205 · mesonbuild/wrapdb

• Do you have an executable that doesn’t start to run and you don’t see any error messages?

  • If you see this in console, try in GUI (Explorer) again, probably you’ll see some error pop-up window.

  • Do you see this as a CMake error that some simple C or C++ test is not able to run, so the build is aborted?

  • There is a good chance you hit this issue: Debug run-time DLL issue

• Does the build fail in a very early phrase, reporting there are no C/C++ compiler found?

  • Try to invoke vcvars manually, then repeat it.

    • Powershell

      cmd /k '"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsx86_arm64.bat" & powershell'

    • cmd

      "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsx86_arm64.bat"

  • If it’s fixed, you’d need to find where the environment should be set properly by the build process.

• Does any of a dependant external library fail for win-arm64?

  • Check whether there is a newer release for that library.

    • There is a chance it’s already ported, just not donwstreamed.

  • Example:

    • Add MSVC ARM64 support for reading clocks (#1052) · google/benchmark@ea5a5bb

    • Update googlebenchmark to 1.6.1 by gaborkertesz-linaro · Pull Request #86 · pytorch/cpuinfo

• Do you have any issues with some Toolchain stuff (CMake, Bazel, Fortran, Ninja)?

  • https://linaro.atlassian.net/wiki/spaces/WOAR/pages/28684353905/Toolchain

Python related tips

• Tests

  • Is there a test folder with test pythons scripts, but no hint how to run them?

    • Try install pytest and run this:

• Is vcvars.bat called some of the inner scripts and not setuptools or distutils?

  • Example: Example: Add support for win-arm64 to MSVC by gaborkertesz-linaro · Pull Request #9409 · mesonbuild/meson

  • Don’t you find where is it defined?

    • Try to search for vcvars or vc_arch

• Do you want to change the invoked toolchain (for example try x64/arm64 instead of the default x86/arm64) and it’s not set by the project?

  • Keep in mind, that even if you’re working within venv, still the installed Python directory is used for setuptools and distutils

  • setuptools-distutils | 4.1. Built in lib in Python interpreter

  • setuptools-distutils | 4.2. Within stand alone setuptools package