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
72   LLVM toolchain, you have to specify some settings to let the compiler
73   know 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