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_linux:
71
72Install Zephyr SDK on Linux
73***************************
74
75#. Download and verify the `Zephyr SDK bundle`_:
76
77   .. code-block:: bash
78
79      wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.3/zephyr-sdk-0.16.3_linux-x86_64.tar.xz
80      wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.3/sha256.sum | shasum --check --ignore-missing
81
82   You can change ``0.16.3`` to another version if needed; the `Zephyr SDK
83   Releases`_ page contains all available SDK releases.
84
85   If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace
86   ``x86_64`` with ``aarch64`` in order to download the 64-bit ARM Linux SDK.
87
88#. Extract the Zephyr SDK bundle archive:
89
90   .. code-block:: bash
91
92      cd <sdk download directory>
93      tar xvf zephyr-sdk-0.16.3_linux-x86_64.tar.xz
94
95#. Run the Zephyr SDK bundle setup script:
96
97   .. code-block:: bash
98
99      cd zephyr-sdk-0.16.3
100      ./setup.sh
101
102   If this fails, make sure Zephyr's dependencies were installed as described
103   in :ref:`Install Requirements and Dependencies <linux_requirements>`.
104
105If you want to uninstall the SDK, remove the directory where you installed it.
106If you relocate the SDK directory, you need to re-run the setup script.
107
108.. note::
109   It is recommended to extract the Zephyr SDK bundle at one of the following
110   default locations:
111
112   * ``$HOME``
113   * ``$HOME/.local``
114   * ``$HOME/.local/opt``
115   * ``$HOME/bin``
116   * ``/opt``
117   * ``/usr/local``
118
119   The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.3`` directory and, when
120   extracted under ``$HOME``, the resulting installation path will be
121   ``$HOME/zephyr-sdk-0.16.3``.
122
123.. _toolchain_zephyr_sdk_install_macos:
124
125Install Zephyr SDK on macOS
126***************************
127
128#. Download and verify the `Zephyr SDK bundle`_:
129
130   .. code-block:: bash
131
132      cd ~
133      wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.3/zephyr-sdk-0.16.3_macos-x86_64.tar.xz
134      wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.3/sha256.sum | shasum --check --ignore-missing
135
136   If your host architecture is 64-bit ARM (Apple Silicon, also known as M1), replace
137   ``x86_64`` with ``aarch64`` in order to download the 64-bit ARM macOS SDK.
138
139#. Extract the Zephyr SDK bundle archive:
140
141   .. code-block:: bash
142
143      tar xvf zephyr-sdk-0.16.3_macos-x86_64.tar.xz
144
145   .. note::
146      It is recommended to extract the Zephyr SDK bundle at one of the following
147      default locations:
148
149      * ``$HOME``
150      * ``$HOME/.local``
151      * ``$HOME/.local/opt``
152      * ``$HOME/bin``
153      * ``/opt``
154      * ``/usr/local``
155
156      The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.3`` directory and, when
157      extracted under ``$HOME``, the resulting installation path will be
158      ``$HOME/zephyr-sdk-0.16.3``.
159
160#. Run the Zephyr SDK bundle setup script:
161
162   .. code-block:: bash
163
164      cd zephyr-sdk-0.16.3
165      ./setup.sh
166
167   .. note::
168      You only need to run the setup script once after extracting the Zephyr SDK bundle.
169
170      You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
171      the initial setup.
172
173.. _toolchain_zephyr_sdk_install_windows:
174
175Install Zephyr SDK on Windows
176*****************************
177
178#. Open a ``cmd.exe`` window by pressing the Windows key typing "cmd.exe".
179
180#. Download the `Zephyr SDK bundle`_:
181
182   .. code-block:: console
183
184      cd %HOMEPATH%
185      wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.3/zephyr-sdk-0.16.3_windows-x86_64.7z
186
187#. Extract the Zephyr SDK bundle archive:
188
189   .. code-block:: console
190
191      7z x zephyr-sdk-0.16.3_windows-x86_64.7z
192
193   .. note::
194      It is recommended to extract the Zephyr SDK bundle at one of the following
195      default locations:
196
197      * ``%HOMEPATH%``
198      * ``%PROGRAMFILES%``
199
200      The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.16.3`` directory and, when
201      extracted under ``%HOMEPATH%``, the resulting installation path will be
202      ``%HOMEPATH%\zephyr-sdk-0.16.3``.
203
204#. Run the Zephyr SDK bundle setup script:
205
206   .. code-block:: console
207
208      cd zephyr-sdk-0.16.3
209      setup.cmd
210
211   .. note::
212      You only need to run the setup script once after extracting the Zephyr SDK bundle.
213
214      You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
215      the initial setup.
216
217.. _Zephyr SDK bundle: https://github.com/zephyrproject-rtos/sdk-ng/releases/tag/v0.16.3
218.. _Zephyr SDK Releases: https://github.com/zephyrproject-rtos/sdk-ng/tags
219.. _Zephyr SDK Version Compatibility Matrix: https://github.com/zephyrproject-rtos/sdk-ng/wiki/Zephyr-SDK-Version-Compatibility-Matrix
220