1.. _toolchain_zephyr_sdk:
2
3Zephyr SDK
4##########
5
6The Zephyr Software Development Kit (SDK) contains toolchains for each of
7Zephyr's supported architectures. It also includes additional host tools, such
8as custom QEMU and OpenOCD.
9
10Use of the Zephyr SDK is highly recommended and may even be required under
11certain conditions (for example, running tests in QEMU for some architectures).
12
13Supported architectures
14***********************
15
16The Zephyr SDK supports the following target architectures:
17
18* ARC (32-bit and 64-bit; ARCv1, ARCv2, ARCv3)
19* ARM (32-bit and 64-bit; ARMv6, ARMv7, ARMv8; A/R/M Profiles)
20* MIPS (32-bit and 64-bit)
21* RISC-V (32-bit and 64-bit; RV32I, RV32E, RV64I)
22* x86 (32-bit and 64-bit)
23* Xtensa
24
25.. _toolchain_zephyr_sdk_bundle_variables:
26
27Installation bundle and variables
28*********************************
29
30The Zephyr SDK bundle supports all major operating systems (Linux, macOS and
31Windows) and is delivered as a compressed file.
32The installation consists of extracting the file and running the included setup
33script. Additional OS-specific instructions are described in the sections below.
34
35If no toolchain is selected, the build system looks for Zephyr SDK and uses the toolchain
36from there. You can enforce this by setting the environment variable
37:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to ``zephyr``.
38
39If you install the Zephyr SDK outside any of the default locations (listed in
40the operating system specific instructions below) and you want automatic discovery
41of the Zephyr SDK, then you must register the Zephyr SDK in the CMake package registry
42by running the setup script. If you decide not to register the Zephyr SDK in the CMake registry,
43then the :envvar:`ZEPHYR_SDK_INSTALL_DIR` can be used to point to the Zephyr SDK installation
44directory.
45
46You can also set :envvar:`ZEPHYR_SDK_INSTALL_DIR` to point to a directory
47containing multiple Zephyr SDKs, allowing for automatic toolchain selection. For
48example, you can set ``ZEPHYR_SDK_INSTALL_DIR`` to ``/company/tools``, where the
49``company/tools`` folder contains the following subfolders:
50
51* ``/company/tools/zephyr-sdk-0.13.2``
52* ``/company/tools/zephyr-sdk-a.b.c``
53* ``/company/tools/zephyr-sdk-x.y.z``
54
55This allows the Zephyr build system to choose the correct version of the SDK,
56while allowing multiple Zephyr SDKs to be grouped together at a specific path.
57
58.. _toolchain_zephyr_sdk_compatibility:
59
60Zephyr SDK version compatibility
61********************************
62
63In general, the Zephyr SDK version referenced in this page should be considered
64the recommended version for the corresponding Zephyr version.
65
66For the full list of compatible Zephyr and Zephyr SDK versions, refer to the
67`Zephyr SDK Version Compatibility Matrix`_.
68
69.. _toolchain_zephyr_sdk_install:
70
71Zephyr SDK installation
72***********************
73
74.. toolchain_zephyr_sdk_install_start
75
76.. note:: You can change |sdk-version-literal| to another version in the instructions below
77          if needed; the `Zephyr SDK Releases`_ page contains all available
78          SDK releases.
79
80.. note:: If you want to uninstall the SDK, you may simply remove the directory
81          where you installed it.
82
83.. tabs::
84
85   .. group-tab:: Ubuntu
86
87      .. _ubuntu_zephyr_sdk:
88
89      #. Download and verify the `Zephyr SDK bundle`_:
90
91         .. parsed-literal::
92
93            cd ~
94            wget |sdk-url-linux|
95            wget -O - |sdk-url-linux-sha| | shasum --check --ignore-missing
96
97         If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace ``x86_64``
98         with ``aarch64`` in order to download the 64-bit ARM Linux SDK.
99
100      #. Extract the Zephyr SDK bundle archive:
101
102         .. parsed-literal::
103
104            tar xvf zephyr-sdk- |sdk-version-trim| _linux-x86_64.tar.xz
105
106         .. note::
107            It is recommended to extract the Zephyr SDK bundle at one of the following locations:
108
109            * ``$HOME``
110            * ``$HOME/.local``
111            * ``$HOME/.local/opt``
112            * ``$HOME/bin``
113            * ``/opt``
114            * ``/usr/local``
115
116            The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
117            directory and, when extracted under ``$HOME``, the resulting
118            installation path will be ``$HOME/zephyr-sdk-<version>``.
119
120      #. Run the Zephyr SDK bundle setup script:
121
122         .. parsed-literal::
123
124            cd zephyr-sdk- |sdk-version-ltrim|
125            ./setup.sh
126
127         .. note::
128            You only need to run the setup script once after extracting the Zephyr SDK bundle.
129
130            You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
131            the initial setup.
132
133      #. Install `udev <https://en.wikipedia.org/wiki/Udev>`_ rules, which
134         allow you to flash most Zephyr boards as a regular user:
135
136         .. parsed-literal::
137
138            sudo cp ~/zephyr-sdk- |sdk-version-trim| /sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
139            sudo udevadm control --reload
140
141   .. group-tab:: macOS
142
143      .. _macos_zephyr_sdk:
144
145      #. Download and verify the `Zephyr SDK bundle`_:
146
147         .. parsed-literal::
148
149            cd ~
150            curl -L -O |sdk-url-macos|
151            curl -L |sdk-url-macos-sha| | shasum --check --ignore-missing
152
153         If your host architecture is 64-bit ARM (Apple Silicon), replace
154         ``x86_64`` with ``aarch64`` in order to download the 64-bit ARM macOS SDK.
155
156      #. Extract the Zephyr SDK bundle archive:
157
158         .. parsed-literal::
159
160            tar xvf zephyr-sdk- |sdk-version-trim| _macos-x86_64.tar.xz
161
162         .. note::
163            It is recommended to extract the Zephyr SDK bundle at one of the following locations:
164
165            * ``$HOME``
166            * ``$HOME/.local``
167            * ``$HOME/.local/opt``
168            * ``$HOME/bin``
169            * ``/opt``
170            * ``/usr/local``
171
172            The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
173            directory and, when extracted under ``$HOME``, the resulting
174            installation path will be ``$HOME/zephyr-sdk-<version>``.
175
176      #. Run the Zephyr SDK bundle setup script:
177
178         .. parsed-literal::
179
180            cd zephyr-sdk- |sdk-version-ltrim|
181            ./setup.sh
182
183         .. note::
184            You only need to run the setup script once after extracting the Zephyr SDK bundle.
185
186            You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
187            the initial setup.
188
189   .. group-tab:: Windows
190
191      .. _windows_zephyr_sdk:
192
193      #. Open a ``cmd.exe`` terminal window **as a regular user**
194
195      #. Download the `Zephyr SDK bundle`_:
196
197         .. parsed-literal::
198
199            cd %HOMEPATH%
200            wget |sdk-url-windows|
201
202      #. Extract the Zephyr SDK bundle archive:
203
204         .. parsed-literal::
205
206            7z x zephyr-sdk- |sdk-version-trim| _windows-x86_64.7z
207
208         .. note::
209            It is recommended to extract the Zephyr SDK bundle at one of the following locations:
210
211            * ``%HOMEPATH%``
212            * ``%PROGRAMFILES%``
213
214            The Zephyr SDK bundle archive contains the ``zephyr-sdk-<version>``
215            directory and, when extracted under ``%HOMEPATH%``, the resulting
216            installation path will be ``%HOMEPATH%\zephyr-sdk-<version>``.
217
218      #. Run the Zephyr SDK bundle setup script:
219
220         .. parsed-literal::
221
222            cd zephyr-sdk- |sdk-version-ltrim|
223            setup.cmd
224
225         .. note::
226            You only need to run the setup script once after extracting the Zephyr SDK bundle.
227
228            You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
229            the initial setup.
230
231.. _Zephyr SDK Releases: https://github.com/zephyrproject-rtos/sdk-ng/tags
232.. _Zephyr SDK Version Compatibility Matrix: https://github.com/zephyrproject-rtos/sdk-ng/wiki/Zephyr-SDK-Version-Compatibility-Matrix
233
234.. toolchain_zephyr_sdk_install_end
235