Documentation inconsistency: Windows cross-build instructions do not match current build process

[JiriDobrySkodagroup]

Summary
The Building from Source documentation describes how to cross-compile the toolchain for Windows, but the process no longer works as written in arm-toolchain/blob/arm-software/arm-software/embedded/docs/building-from-source.md
The released versions cannot be built following the documented steps without applying patch 2293b24 (credit to Volodymyr Turanskyy).

Interestingly, this patch is already present on HEAD, so the development branch is currently easier to build than the official release — which is a bit humorous, but confusing for users following the official guide.

To Reproduce

1. Follow the “Windows cross-build” section in the documentation.
2. Attempt to build the released version (e.g. 21.1.0 or 21.1.1) using the documented procedure.
3. Observe that the build fails unless the above patch is applied.

Expected behavior
The released version should build successfully when following the documented steps for Windows cross-compilation.

Actual behavior
The documented cross-build path fails for Windows targets in released versions.
It appears that the nightly Windows builds are produced natively on Windows rather than through the cross-compilation process described in the documentation.

Environment
Arm Toolchain version: 21.1.0 / 21.1.1 (release)
Host: Debian 13 (attempting to cross-build for Windows)

[Additional context]
To prevent future mismatches between the documented process and official releases, it might help to either:

• add instructions for building natively on Windows (as apparently used in nightly builds), or
• enable the Windows cross-build path in nightly builds so it remains functional.

Ideally, supporting both approaches would ensure reproducibility and consistency between documentation and releases.

Minor note:

cmake . -DLLVM_TOOLCHAIN_CROSS_BUILD_MINGW=ON

should likely read

cmake .. -DLLVM_TOOLCHAIN_CROSS_BUILD_MINGW=ON

[voltur01]

Hi, thank you for reaching out! I cherry-picked the change into the 21.x release branch as well, please give it a try.

It may be a bit implicit, however the build from source page https://github.com/arm/arm-toolchain/blob/arm-software/arm-software/embedded/docs/building-from-source.md states that Linux Ubuntu, macOS and Windows are supported - building instructions apply to all of them. Cross-build is a special case, thus has a dedicated section.

Our Windows CI uses https://github.com/arm/arm-toolchain/blob/arm-software/arm-software/embedded/scripts/build.ps1 which expects MS Visual Studio to be available - the biggest reason to also support Mingw as an alternative.

Hope this helps.

[JiriDobrySkodagroup]

The document could use a bit of cleanup - mainly to make it clearer that the published Windows builds are produced differently (a link to the build script would be enough).

For reference, here’s a minimal working example I tested for cross-compiling version 21.1.1. Hopefully it helps anyone running into the same issue.

git clone https://github.com/arm/arm-toolchain.git
cd arm-toolchain
git reset --hard release-21.1.1-ATfE
git cherry-pick 2293b2495945f2d14e79ff34f54afd17c3fac2c9
cd  arm-software/embedded
export CC=clang
export CXX=clang++
mkdir build
cd build
time cmake .. -GNinja -DLLVM_TOOLCHAIN_CROSS_BUILD_MINGW=ON
time ninja package-llvm-toolchain

EDIT: fix tag from release-21.1.1-ATfL to release-21.1.1-ATfE (thx voltur01)

[voltur01]

Thank you for sharing the steps!

There are two bits of documentation: more user focused here https://github.com/arm/arm-toolchain/tree/arm-software/arm-software/embedded#host-platforms that mentions use of Microsoft Visual Studio and the more toolchain developer focused that gives the options to use different host compilers.

One minor remark regarding the steps is that git reset --hard release-21.1.1-ATfL refers to the Arm Toolchain for Linux tag, if you want to recreate the exact Arm Toolchain for Embedded build then this tag should be used https://github.com/arm/arm-toolchain/releases/tag/release-21.1.1-ATfE (I do not expect any essential differences in ATfE between the two tags though).