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