1.. _toolchain_atfe:
2
3Arm Toolchain for Embedded (ATfE)
4#################################
5
6
7Arm Toolchain for Embedded (ATfE) is a C and C++ toolchain from Arm based
8   on the free and open-source LLVM Compiler Infrastructure and the Picolib C
9   library for baremetal targets.
10
11ATfE is fined-tuned with a particular focus on performance for newer
12   ARM products (post 2024) like 64-bit Arm Architectures (AArch64),
13   or the M-Profile Vector Extension (MVE, a 32-bit Armv8.1-M extension).
14
15Installation
16************
17
18#. Download and install a `Arm toolchain for embedded`_ build for your operating system
19   and extract it on your file system.
20
21#. :ref:`Set these environment variables <env_vars>`:
22
23   - Set :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``llvm``.
24   - Set :envvar:`LLVM_TOOLCHAIN_PATH` to the toolchain installation directory.
25
26#. To check that you have set these variables correctly in your current
27   environment, follow these example shell sessions (the
28   :envvar:`LLVM_TOOLCHAIN_PATH` values may be different on your system):
29
30   .. tabs::
31
32      .. group-tab:: Ubuntu
33
34         .. code-block:: bash
35
36            echo $ZEPHYR_TOOLCHAIN_VARIANT
37            llvm
38            echo $LLVM_TOOLCHAIN_PATH
39            /home/you/Downloads/ATfE
40
41      .. group-tab:: macOS
42
43         .. code-block:: bash
44
45            echo $ZEPHYR_TOOLCHAIN_VARIANT
46            llvm
47            echo $LLVM_TOOLCHAIN_PATH
48            /home/you/Downloads/ATfE
49
50      .. group-tab:: Windows
51
52         .. code-block:: powershell
53
54            > echo %ZEPHYR_TOOLCHAIN_VARIANT%
55            llvm
56            > echo %LLVM_TOOLCHAIN_PATH%
57            C:\ATfE
58
59   .. _toolchain_env_var:
60
61#. You can also set ``ZEPHYR_TOOLCHAIN_VARIANT`` and ``LLVM_TOOLCHAIN_PATH`` as CMake
62   variables when generating a build system for a Zephyr application, like so:
63
64   .. code-block:: console
65
66      west build ... -- -DZEPHYR_TOOLCHAIN_VARIANT=llvm -DLLVM_TOOLCHAIN_PATH=...
67
68Toolchain settings
69******************
70
71Because LLVM is widely compatible with GNU tools, When builiding with any
72LLVM toolchain, you have to specify some settings to let the compiler
73know what tools to use:
74
75Linker
76   * Set :envvar:`CONFIG_LLVM_USE_LLD=y` to use LLVM linker.
77   * Set :envvar:`CONFIG_LLVM_USE_LD=y` to use the GNU LD linker.
78
79Runtime library
80   * Set :envvar:`CONFIG_COMPILER_RT_RTLIB=y` to use LLVM runtime library.
81   * Set :envvar:`CONFIG_LIBGCC_RTLIB=y` to use LibGCC runtime library.
82
83.. code-block:: console
84
85   west build ... -- -DZEPHYR_TOOLCHAIN_VARIANT=llvm -DLLVM_TOOLCHAIN_PATH=... -DCONFIG_LLVM_USE_LLD=y -DCONFIG_COMPILER_RT_RTLIB=y
86
87.. _Arm Toolchain for Embedded: https://developer.arm.com/Tools%20and%20Software/Arm%20Toolchain%20for%20Embedded
88