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:

      • https://github.com/python-pillow/Pillow/blob/main/Tests/test_image_access.py#L399

      • 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: https://github.com/ImageOptim/libimagequant/pull/66/commits/94adecb956eac74801bc035a0c403aaf44866d16

  • 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

      • https://github.com/glennrp/libpng/pull/397/commits/f8bab870946a1ab9afe253b5d65ab73fc2c55b28

      • https://github.com/mm2/Little-CMS/commit/ade87cf12078680efda6d89095b9264ea1e5c5fe
        

• 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: https://github.com/mesonbuild/wrapdb/pull/205/commits/da6a13fb61f64baca0567763c51efaed9b14c41f

• 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:

    • https://github.com/google/benchmark/commit/ea5a5bbff491fd625c6e3458f6edd680b8bd5452

    • https://github.com/pytorch/cpuinfo/pull/86

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:

      pytest <test directory>

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

  • Example: Example: https://github.com/mesonbuild/meson/pull/9409/commits/466ad78239e0f30bed16c40b863a79dc1a80b4b0

  • 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

  • https://linaro.atlassian.net/wiki/spaces/WOAR/pages/28593914166/setuptools-distutils#4.1.-Built-in-lib-in-Python-interpreter

  • https://linaro.atlassian.net/wiki/spaces/WOAR/pages/28593914166/setuptools-distutils#4.2.-Within-stand-alone-setuptools-package