[llvm][docs] Update CMake commands for cross compiling Arm builtins (#151544)

DavidSpickett · web-flow · commit dc41571cd8af · 2025-08-13T09:47:43.000+01:00
This does a few things:
* LLVM_CONFIG_PATH is deprecated, use LLVM_CMAKE_DIR instead.
* Don't use $ before command examples. I would normally, but the key
cmake commands didn't use it so I removed it from all commands.
* Makes the commands shown full commands, so you don't have to piece
them together.
* Uses shell variables to cut down on repetition and make this easier to
port to other targets.
* Adds a few options to disable more compiler-rt things.
* Use the built in cmake options for sysroot and toolchains.
* Include test options in the first cmake command, so you don't have to
re-do the whole thing after you read the testing section.
* Removes the section about using BaremetalARM.cmake.

The closest I got to getting that cache to work was:
```
SYSROOT=/home/david.spickett/arm-gnu-toolchain-14.3.rel1-x86_64-arm-none-eabi/arm-none-eabi/libc
LLVM_TOOLCHAIN=/home/david.spickett/LLVM-20.1.8-Linux-X64/

cmake \
  -G Ninja \
  -DCMAKE_C_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
  -DBAREMETAL_ARMV6M_SYSROOT=${SYSROOT} \
  -DBAREMETAL_ARMV7M_SYSROOT=${SYSROOT} \
  -DBAREMETAL_ARMV7EM_SYSROOT=${SYSROOT} \
  -DCMAKE_BUILD_TYPE=Release \
  -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
  -C ../llvm-project/clang/cmake/caches/BaremetalARM.cmake \
  -DCOMPILER_RT_BUILD_BUILTINS=ON \
  -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
  -DCOMPILER_RT_BUILD_MEMPROF=OFF \
  -DCOMPILER_RT_BUILD_PROFILE=OFF \
  -DCOMPILER_RT_BUILD_CTX_PROFILE=OFF \
  -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
  -DCOMPILER_RT_BUILD_XRAY=OFF \
  -DCOMPILER_RT_BUILD_ORC=OFF \
  -DCOMPILER_RT_BUILD_CRT=OFF \
  ../llvm-project/runtimes
```
All this does is build the x86 builtins. I tried forcing the issue with:
```
  -DBUILTIN_SUPPORTED_ARCH="armv7m;armv6m;armv7em" \
```
But again, just x86.

It's probably something deep in compiler-rt failing a compiler check for
the Arm targets. Even if that's the case, fixing that means adding more
options to the cmake command.

I can't find evidence of a full command using this cache file since the
commit that introduced it and that command no longer works.

I think if you ever got this to work again the command would be as long
and complex as the ones already shown in the document.

I would also argue that some of the other caches, for example Fuschia's,
are much better example of multi-target runtimes builds. If what's in
this document isn't enough, folks should be learning from those files
and about the runtimes build overall before attempting anything complex
(though it does not take much to be "complex").
diff --git a/llvm/docs/HowToCrossCompileBuiltinsOnArm.rst b/llvm/docs/HowToCrossCompileBuiltinsOnArm.rst
@@ -25,12 +25,16 @@ using as many of the LLVM tools as we can, but it is possible to use GNU
 equivalents.
 
 You will need:
- * A build of LLVM for the llvm-tools and ``llvm-config``.
+ * A build of LLVM for the llvm-tools and LLVM CMake files.
  * A clang executable with support for the ``ARM`` target.
- * compiler-rt sources.
+ * ``compiler-rt`` sources.
  * The ``qemu-arm`` user mode emulator.
  * An ``arm-linux-gnueabihf`` sysroot.
 
+.. note::
+  An existing sysroot is required because some of the builtins include C library
+  headers and a sysroot is the easiest way to get those.
+
 In this example we will be using ``ninja`` as the build tool.
 
 See https://compiler-rt.llvm.org/ for information about the dependencies
@@ -52,78 +56,94 @@ toolchain from https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloa
 Building compiler-rt builtins for Arm
 =====================================
 
-We will be doing a standalone build of compiler-rt using the following cmake
-options::
+We will be doing a standalone build of compiler-rt. The command is shown below.
+Shell variables are used to simplify some of the options::
+
+  LLVM_TOOLCHAIN=<path-to-llvm-install>/
+  TARGET_TRIPLE=arm-none-linux-gnueabihf
+  GCC_TOOLCHAIN=<path-to-gcc-toolchain>
+  SYSROOT=${GCC_TOOLCHAIN}/${TARGET_TRIPLE}/libc
+  COMPILE_FLAGS="-march=armv7-a"
 
-  cmake path/to/compiler-rt \
+  cmake ../llvm-project/compiler-rt \
     -G Ninja \
-    -DCMAKE_AR=/path/to/llvm-ar \
-    -DCMAKE_ASM_COMPILER_TARGET="arm-linux-gnueabihf" \
-    -DCMAKE_ASM_FLAGS="build-c-flags" \
-    -DCMAKE_C_COMPILER=/path/to/clang \
-    -DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf" \
-    -DCMAKE_C_FLAGS="build-c-flags" \
+    -DCMAKE_AR=${LLVM_TOOLCHAIN}/bin/llvm-ar \
+    -DCMAKE_NM=${LLVM_TOOLCHAIN}/bin/llvm-nm \
+    -DCMAKE_RANLIB=${LLVM_TOOLCHAIN}/bin/llvm-ranlib \
+    -DLLVM_CMAKE_DIR="${LLVM_TOOLCHAIN}/lib/cmake/llvm" \
+    -DCMAKE_SYSROOT="${SYSROOT}" \
+    -DCMAKE_ASM_COMPILER_TARGET="${TARGET_TRIPLE}" \
+    -DCMAKE_ASM_FLAGS="${COMPILE_FLAGS}" \
+    -DCMAKE_C_COMPILER_TARGET="${TARGET_TRIPLE}" \
+    -DCMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN=${GCC_TOOLCHAIN} \
+    -DCMAKE_C_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+    -DCMAKE_C_FLAGS="${COMPILE_FLAGS}" \
+    -DCMAKE_CXX_COMPILER_TARGET="${TARGET_TRIPLE}" \
+    -DCMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN=${GCC_TOOLCHAIN} \
+    -DCMAKE_CXX_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+    -DCMAKE_CXX_FLAGS="${COMPILE_FLAGS}" \
     -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" \
-    -DCMAKE_NM=/path/to/llvm-nm \
-    -DCMAKE_RANLIB=/path/to/llvm-ranlib \
     -DCOMPILER_RT_BUILD_BUILTINS=ON \
     -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
     -DCOMPILER_RT_BUILD_MEMPROF=OFF \
     -DCOMPILER_RT_BUILD_PROFILE=OFF \
+    -DCOMPILER_RT_BUILD_CTX_PROFILE=OFF \
     -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
     -DCOMPILER_RT_BUILD_XRAY=OFF \
+    -DCOMPILER_RT_BUILD_ORC=OFF \
+    -DCOMPILER_RT_BUILD_CRT=OFF \
     -DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON \
-    -DLLVM_CONFIG_PATH=/path/to/llvm-config
+    -DCOMPILER_RT_EMULATOR="qemu-arm -L ${SYSROOT}" \
+    -DCOMPILER_RT_INCLUDE_TESTS=ON \
+    -DCOMPILER_RT_TEST_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+    -DCOMPILER_RT_TEST_COMPILER_CFLAGS="--target=${TARGET_TRIPLE} ${COMPILE_FLAGS} --gcc-toolchain=${GCC_TOOLCHAIN} --sysroot=${SYSROOT} -fuse-ld=lld"
 
-The ``build-c-flags`` need to be sufficient to pass the C-make compiler check,
-compile compiler-rt, and if you are running the tests, compile and link the
-tests. When cross-compiling with clang we will need to pass sufficient
-information to generate code for the Arm architecture we are targeting.
+.. note::
+  The command above also enables tests. Enabling tests is not required, more details
+  in the testing section.
 
-We will need to select:
- * The Arm target and Armv7-A architecture with ``--target=arm-linux-gnueabihf -march=armv7a``.
- * Whether to generate Arm (the default) or Thumb instructions (``-mthumb``).
+``CMAKE_<LANGUAGE>_<OPTION>`` options are set so that the correct ``--target``,
+``--sysroot``, ``--gcc-toolchain`` and ``-march`` options will be given to the
+compilers.
 
-When using a GCC ``arm-linux-gnueabihf`` toolchain the following flags are
-needed to pick up the includes and libraries:
+The combination of these settings needs to be enough to pass CMake's compiler
+checks, compile compiler-rt and build the test cases.
 
- * ``--gcc-toolchain=/path/to/dir/toolchain``
- * ``--sysroot=/path/to/toolchain/arm-linux-gnueabihf/libc``
+The flags need to select:
+ * The Arm target (``--target arm-none-linux-gnueabihf``)
+ * The Arm architecture level (``-march=armv7-a``)
+ * Whether to generate Arm (``-marm``, the default) or Thumb (``-mthumb``) instructions.
 
-In this example we will be adding all of the command line options to both
-``CMAKE_C_FLAGS`` and ``CMAKE_ASM_FLAGS``. There are cmake flags to pass some of
-these options individually which can be used to simplify the ``build-c-flags``::
+It is possible to pass all these flags to CMake using ``CMAKE_<LANGUAGE>_FLAGS``,
+but the command above uses standard CMake options instead. If you need to
+add flags that CMake cannot generate automatically, add them to
+``CMAKE_<LANGUAGE>_FLAGS``.
 
- -DCMAKE_C_COMPILER_TARGET="arm-linux-gnueabihf"
- -DCMAKE_ASM_COMPILER_TARGET="arm-linux-gnueabihf"
- -DCMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN=/path/to/dir/toolchain
- -DCMAKE_SYSROOT=/path/to/dir/toolchain/arm-linux-gnueabihf/libc
+When CMake has finished, build with Ninja::
 
-Once cmake has completed the builtins can be built with ``ninja builtins``
+  ninja builtins
 
 Testing compiler-rt builtins using qemu-arm
 ===========================================
 
-To test the builtins library we need to add a few more cmake flags to enable
-testing and set up the compiler and flags for test case. We must also tell
-cmake that we wish to run the tests on ``qemu-arm``::
+The following options are required to enable tests::
+
+ -DCOMPILER_RT_EMULATOR="qemu-arm -L ${SYSROOT}" \
+ -DCOMPILER_RT_INCLUDE_TESTS=ON \
+ -DCOMPILER_RT_TEST_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+ -DCOMPILER_RT_TEST_COMPILER_CFLAGS="--target=${TARGET_TRIPLE} -march=armv7-a --gcc-toolchain=${GCC_TOOLCHAIN} --sysroot=${SYSROOT} -fuse-ld=lld"
 
- -DCOMPILER_RT_EMULATOR="qemu-arm -L /path/to/armhf/sysroot"
- -DCOMPILER_RT_INCLUDE_TESTS=ON
- -DCOMPILER_RT_TEST_COMPILER="/path/to/clang"
- -DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"
+This tells compiler-rt that we want to run tests on ``qemu-arm``. If you do not
+want to run tests, remove these options from the CMake command.
 
-The ``/path/to/armhf/sysroot`` should be the same as the one passed to
-``--sysroot`` in the ``build-c-flags``.
+Note that ``COMPILER_RT_TEST_COMPILER_CFLAGS`` contains the equivalent of the
+options CMake generated for us with the first command. We must pass them
+manually here because standard options like ``CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN``
+do not apply here.
 
-The ``test-c-flags`` need to include the target, architecture, gcc-toolchain,
-sysroot and Arm/Thumb state. The additional cmake defines such as
-``CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN`` do not apply when building the tests. If
-you have put all of these in ``build-c-flags`` then these can be repeated. If you
-wish to use lld to link the tests then add ``-fuse-ld=lld``.
+When CMake has finished, run the tests::
 
-Once cmake has completed the tests can be built and run using
-``ninja check-builtins``
+  ninja check-builtins
 
 Troubleshooting
 ===============
@@ -133,9 +153,10 @@ The cmake try compile stage fails
 At an early stage cmake will attempt to compile and link a simple C program to
 test if the toolchain is working.
 
-This stage can often fail at link time if the ``--sysroot=`` and
+This stage can often fail at link time if the ``--sysroot=``, ``--target`` or
 ``--gcc-toolchain=`` options are not passed to the compiler. Check the
-``CMAKE_C_FLAGS`` and ``CMAKE_C_COMPILER_TARGET`` flags.
+``CMAKE_<LANGUAGE>_FLAGS`` and ``CMAKE_<LANGAUGE>_COMPILER_TARGET`` flags along
+with any of the specific CMake sysroot and toolchain options.
 
 It can be useful to build a simple example outside of cmake with your toolchain
 to make sure it is working. For example::
@@ -179,10 +200,10 @@ The flags used to build the tests are not the same as those used to build the
 builtins. The c flags are provided by ``COMPILER_RT_TEST_COMPILE_CFLAGS`` and
 the ``CMAKE_C_COMPILER_TARGET``, ``CMAKE_ASM_COMPILER_TARGET``,
 ``CMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN`` and ``CMAKE_SYSROOT`` flags are not
-applied.
+applied to tests.
 
 Make sure that ``COMPILER_RT_TEST_COMPILE_CFLAGS`` contains all the necessary
-information.
+flags.
 
 
 Modifications for other Targets
@@ -206,13 +227,13 @@ You will need to use an ``arm-linux-gnueabi`` GNU toolchain for soft-float.
 AArch64 Target
 --------------
 The instructions for Arm can be used for AArch64 by substituting AArch64
-equivalents for the sysroot, emulator and target.
+equivalents for the sysroot, emulator and target::
 
-* ``-DCMAKE_C_COMPILER_TARGET=aarch64-linux-gnu``
-* ``-DCOMPILER_RT_EMULATOR="qemu-aarch64 -L /path/to/aarch64/sysroot``
+ -DCMAKE_C_COMPILER_TARGET=aarch64-linux-gnu
+ -DCOMPILER_RT_EMULATOR="qemu-aarch64 -L /path/to/aarch64/sysroot
 
-The CMAKE_C_FLAGS and COMPILER_RT_TEST_COMPILER_CFLAGS may also need:
-``"--sysroot=/path/to/aarch64/sysroot --gcc-toolchain=/path/to/gcc-toolchain"``
+You will also have to update any use of the target triple in compiler flags.
+For instance in ``CMAKE_C_FLAGS`` and ``COMPILER_RT_TEST_COMPILER_CFLAGS``.
 
 Armv6-m, Armv7-m and Armv7E-M targets
 -------------------------------------
@@ -221,7 +242,7 @@ but more difficult. The main problems are:
 
 * There is not a ``qemu-arm`` user-mode emulator for bare-metal systems.
   ``qemu-system-arm`` can be used but this is significantly more difficult
-  to setup.
+  to setup. This document does not explain how to do this.
 * The targets to compile compiler-rt have the suffix ``-none-eabi``. This uses
   the BareMetal driver in clang and by default will not find the libraries
   needed to pass the cmake compiler check.
@@ -235,31 +256,68 @@ into a binary and execute the tests correctly but it will not catch if the
 builtins use instructions that are supported on Armv7-A but not Armv6-M,
 Armv7-M and Armv7E-M.
 
-To get the cmake compile test to pass you will need to pass the libraries
-needed to successfully link the cmake test via ``CMAKE_CFLAGS``::
-
- -DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY \
- -DCOMPILER_RT_OS_DIR="baremetal" \
- -DCOMPILER_RT_BUILD_BUILTINS=ON \
- -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
- -DCOMPILER_RT_BUILD_XRAY=OFF \
- -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
- -DCOMPILER_RT_BUILD_PROFILE=OFF \
- -DCMAKE_C_COMPILER=${host_install_dir}/bin/clang \
- -DCMAKE_C_COMPILER_TARGET="your *-none-eabi target" \
- -DCMAKE_ASM_COMPILER_TARGET="your *-none-eabi target" \
- -DCMAKE_AR=/path/to/llvm-ar \
- -DCMAKE_NM=/path/to/llvm-nm \
- -DCMAKE_RANLIB=/path/to/llvm-ranlib \
- -DCOMPILER_RT_BAREMETAL_BUILD=ON \
- -DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON \
- -DLLVM_CONFIG_PATH=/path/to/llvm-config \
- -DCMAKE_C_FLAGS="build-c-flags" \
- -DCMAKE_ASM_FLAGS="build-c-flags" \
- -DCOMPILER_RT_EMULATOR="qemu-arm -L /path/to/armv7-A/sysroot" \
- -DCOMPILER_RT_INCLUDE_TESTS=ON \
- -DCOMPILER_RT_TEST_COMPILER="/path/to/clang" \
- -DCOMPILER_RT_TEST_COMPILER_CFLAGS="test-c-flags"
+This requires a second ``arm-none-eabi`` toolchain for building the builtins.
+Using a bare-metal toolchain ensures that the target and C library details are
+specific to bare-metal instead of using Linux settings. This means that some
+tests may behave differently compared to real hardware, but at least the content
+of the builtins library is correct.
+
+Below is an example that builds the builtins for Armv7-M, but runs the tests
+as Armv7-A. It is presented in full, but is very similar to the earlier
+command for Armv7-A build and test::
+
+  LLVM_TOOLCHAIN=<path to llvm install>/
+
+  # For the builtins.
+  TARGET_TRIPLE=arm-none-eabi
+  GCC_TOOLCHAIN=<path to arm-none-eabi toolchain>/
+  SYSROOT=${GCC_TOOLCHAIN}/${TARGET_TRIPLE}/libc
+  COMPILE_FLAGS="-march=armv7-m -mfpu=vfpv2"
+
+  # For the test cases.
+  A_PROFILE_TARGET_TRIPLE=arm-none-linux-gnueabihf
+  A_PROFILE_GCC_TOOLCHAIN=<path to arm-none-linux-gnueabihf toolchain>/
+  A_PROFILE_SYSROOT=${A_PROFILE_GCC_TOOLCHAIN}/${A_PROFILE_TARGET_TRIPLE}/libc
+
+  cmake ../llvm-project/compiler-rt \
+    -G Ninja \
+    -DCMAKE_AR=${LLVM_TOOLCHAIN}/bin/llvm-ar \
+    -DCMAKE_NM=${LLVM_TOOLCHAIN}/bin/llvm-nm \
+    -DCMAKE_RANLIB=${LLVM_TOOLCHAIN}/bin/llvm-ranlib \
+    -DLLVM_CMAKE_DIR="${LLVM_TOOLCHAIN}/lib/cmake/llvm" \
+    -DCMAKE_SYSROOT="${SYSROOT}" \
+    -DCMAKE_ASM_COMPILER_TARGET="${TARGET_TRIPLE}" \
+    -DCMAKE_ASM_FLAGS="${COMPILE_FLAGS}" \
+    -DCMAKE_C_COMPILER_TARGET="${TARGET_TRIPLE}" \
+    -DCMAKE_C_COMPILER_EXTERNAL_TOOLCHAIN=${GCC_TOOLCHAIN} \
+    -DCMAKE_C_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+    -DCMAKE_C_FLAGS="${COMPILE_FLAGS}" \
+    -DCMAKE_CXX_COMPILER_TARGET="${TARGET_TRIPLE}" \
+    -DCMAKE_CXX_COMPILER_EXTERNAL_TOOLCHAIN=${GCC_TOOLCHAIN} \
+    -DCMAKE_CXX_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+    -DCMAKE_CXX_FLAGS="${COMPILE_FLAGS}" \
+    -DCMAKE_EXE_LINKER_FLAGS="-fuse-ld=lld" \
+    -DCOMPILER_RT_BUILD_BUILTINS=ON \
+    -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
+    -DCOMPILER_RT_BUILD_MEMPROF=OFF \
+    -DCOMPILER_RT_BUILD_PROFILE=OFF \
+    -DCOMPILER_RT_BUILD_CTX_PROFILE=OFF \
+    -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
+    -DCOMPILER_RT_BUILD_XRAY=OFF \
+    -DCOMPILER_RT_BUILD_ORC=OFF \
+    -DCOMPILER_RT_BUILD_CRT=OFF \
+    -DCOMPILER_RT_DEFAULT_TARGET_ONLY=ON \
+    -DCOMPILER_RT_EMULATOR="qemu-arm -L ${A_PROFILE_SYSROOT}" \
+    -DCOMPILER_RT_INCLUDE_TESTS=ON \
+    -DCOMPILER_RT_TEST_COMPILER=${LLVM_TOOLCHAIN}/bin/clang \
+    -DCOMPILER_RT_TEST_COMPILER_CFLAGS="--target=${A_PROFILE_TARGET_TRIPLE} -march=armv7-a --gcc-toolchain=${A_PROFILE_GCC_TOOLCHAIN} --sysroot=${A_PROFILE_SYSROOT} -fuse-ld=lld" \
+    -DCMAKE_TRY_COMPILE_TARGET_TYPE=STATIC_LIBRARY \
+    -DCOMPILER_RT_OS_DIR="baremetal" \
+    -DCOMPILER_RT_BAREMETAL_BUILD=ON
+
+.. note::
+  The sysroot used for compiling the tests is ``arm-linux-gnueabihf``, not
+  ``arm-none-eabi`` which is used when compiling the builtins.
 
 The Armv6-M builtins will use the soft-float ABI. When compiling the tests for
 Armv7-A we must include ``"-mthumb -mfloat-abi=soft -mfpu=none"`` in the
@@ -270,19 +328,3 @@ mismatches between the M-profile objects from compiler-rt and the A-profile
 objects from the test. The lld linker does not check the profile
 BuildAttribute so it can be used to link the tests by adding ``-fuse-ld=lld`` to the
 ``COMPILER_RT_TEST_COMPILER_CFLAGS``.
-
-Alternative using a cmake cache
--------------------------------
-If you wish to build, but not test compiler-rt for Armv6-M, Armv7-M or Armv7E-M
-the easiest way is to use the ``BaremetalARM.cmake`` recipe in ``clang/cmake/caches``.
-
-You will need a bare metal sysroot such as that provided by the GNU ARM Embedded
-toolchain.
-
-The libraries can be built with the cmake options::
-
- -DBAREMETAL_ARMV6M_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi \
- -DBAREMETAL_ARMV7M_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi \
- -DBAREMETAL_ARMV7EM_SYSROOT=/path/to/bare/metal/toolchain/arm-none-eabi \
- -C /path/to/llvm/source/tools/clang/cmake/caches/BaremetalARM.cmake \
- /path/to/llvm
