doc: getting_started: Add instructions for multi-platform Zephyr SDK

stephanosio · carlescufi · commit 97e226c79bd8 · 2022-03-29T11:14:29.000+02:00
This commit adds the Linux, macOS and Windows instructions for
installing the new multi-platform Zephyr SDK.

Signed-off-by: Stephanos Ioannidis &lt;root@stephanos.io&gt;
diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst
@@ -163,7 +163,7 @@ The current minimum required version for the main dependencies are:
          .. code-block:: console
 
             choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
-            choco install ninja gperf python git dtc-msys2 wget
+            choco install ninja gperf python git dtc-msys2 wget unzip
 
       #. Close the window and open a new ``cmd.exe`` window **as a regular user** to continue.
 
@@ -471,71 +471,154 @@ Install a Toolchain
 A toolchain provides a compiler, assembler, linker, and other programs required
 to build Zephyr applications.
 
+The Zephyr Software Development Kit (SDK) contains toolchains for each of
+Zephyr's supported architectures. It also includes additional host tools, such
+as custom QEMU and OpenOCD builds.
+
 .. tabs::
 
    .. group-tab:: Ubuntu
 
-      The Zephyr Software Development Kit (SDK) contains toolchains for each of
-      Zephyr's supported architectures. It also includes additional host tools,
-      such as custom QEMU binaries and a host compiler.
-
-      |p|
-
-      #. Download the `latest SDK installer
+      #. Download and verify the `latest Zephyr SDK bundle
          <https://github.com/zephyrproject-rtos/sdk-ng/releases>`_:
 
          .. code-block:: bash
 
             cd ~
-            wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.13.2/zephyr-sdk-0.13.2-linux-x86_64-setup.run
+            wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/zephyr-sdk-0.14.0_linux-x86_64.tar.gz
+            wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/sha256.sum | shasum --check --ignore-missing
 
-      #. Run the installer, installing the SDK in :file:`~/zephyr-sdk-0.13.2`:
+         If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace ``x86_64``
+         with ``aarch64`` in order to download the 64-bit ARM Linux SDK.
+
+      #. Extract the Zephyr SDK bundle archive:
 
          .. code-block:: bash
 
-            chmod +x zephyr-sdk-0.13.2-linux-x86_64-setup.run
-            ./zephyr-sdk-0.13.2-linux-x86_64-setup.run -- -d ~/zephyr-sdk-0.13.2
+            tar xvf zephyr-sdk-0.14.0_linux-x86_64.tar.gz
 
          .. note::
-            It is recommended to install the Zephyr SDK at one of the following locations:
+            It is recommended to extract the Zephyr SDK bundle at one of the following locations:
+
+            * ``$HOME``
+            * ``$HOME/.local``
+            * ``$HOME/.local/opt``
+            * ``$HOME/bin``
+            * ``/opt``
+            * ``/usr/local``
 
-            * ``$HOME/zephyr-sdk[-x.y.z]``
-            * ``$HOME/.local/zephyr-sdk[-x.y.z]``
-            * ``$HOME/.local/opt/zephyr-sdk[-x.y.z]``
-            * ``$HOME/bin/zephyr-sdk[-x.y.z]``
-            * ``/opt/zephyr-sdk[-x.y.z]``
-            * ``/usr/zephyr-sdk[-x.y.z]``
-            * ``/usr/local/zephyr-sdk[-x.y.z]``
+            The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.14.0`` directory and, when
+            extracted under ``$HOME``, the resulting installation path will be
+            ``$HOME/zephyr-sdk-0.14.0``.
 
-            where ``[-x.y.z]`` is optional text, and can be any text, for example ``-0.13.2``.
+      #. Run the Zephyr SDK bundle setup script:
 
-            If installing the Zephyr SDK outside any of those locations, please read: :ref:`zephyr_sdk`
+         .. code-block:: bash
 
-            You cannot move the SDK directory after you have installed it.
+            cd zephyr-sdk-0.14.0
+            ./setup.sh
+
+         .. note::
+            You only need to run the setup script once after extracting the Zephyr SDK bundle.
+
+            You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
+            the initial setup.
 
       #. Install `udev <https://en.wikipedia.org/wiki/Udev>`_ rules, which
          allow you to flash most Zephyr boards as a regular user:
 
          .. code-block:: bash
 
-            sudo cp ~/zephyr-sdk-0.13.2/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
+            sudo cp ~/zephyr-sdk-0.14.0/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
             sudo udevadm control --reload
 
    .. group-tab:: macOS
 
-      Follow the instructions in :ref:`gs_toolchain`. Note that the Zephyr SDK
-      is not available on macOS.
+      #. Download and verify the `latest Zephyr SDK bundle
+         <https://github.com/zephyrproject-rtos/sdk-ng/releases>`_:
 
-      Do not forget to set the required :ref:`environment variables <env_vars>`
-      (:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` and toolchain specific ones).
+         .. code-block:: bash
+
+            cd ~
+            wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/zephyr-sdk-0.14.0_macos-x86_64.tar.gz
+            wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/sha256.sum | shasum --check --ignore-missing
+
+         If your host architecture is 64-bit ARM (Apple Silicon, also known as M1), replace
+         ``x86_64`` with ``aarch64`` in order to download the 64-bit ARM macOS SDK.
+
+      #. Extract the Zephyr SDK bundle archive:
+
+         .. code-block:: bash
+
+            tar xvf zephyr-sdk-0.14.0_macos-x86_64.tar.gz
+
+         .. note::
+            It is recommended to extract the Zephyr SDK bundle at one of the following locations:
+
+            * ``$HOME``
+            * ``$HOME/.local``
+            * ``$HOME/.local/opt``
+            * ``$HOME/bin``
+            * ``/opt``
+            * ``/usr/local``
+
+            The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.14.0`` directory and, when
+            extracted under ``$HOME``, the resulting installation path will be
+            ``$HOME/zephyr-sdk-0.14.0``.
+
+      #. Run the Zephyr SDK bundle setup script:
+
+         .. code-block:: bash
+
+            cd zephyr-sdk-0.14.0
+            ./setup.sh
+
+         .. note::
+            You only need to run the setup script once after extracting the Zephyr SDK bundle.
+
+            You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
+            the initial setup.
 
    .. group-tab:: Windows
 
-      Follow the instructions in :ref:`gs_toolchain`. Note that the Zephyr SDK
-      is not available on Windows.
+      #. Open a ``cmd.exe`` window by pressing the Windows key typing "cmd.exe".
+
+      #. Download the `latest Zephyr SDK bundle
+         <https://github.com/zephyrproject-rtos/sdk-ng/releases>`_:
+
+         .. code-block:: console
+
+            cd %HOMEPATH%
+            wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/zephyr-sdk-0.14.0_windows-x86_64.zip
+
+      #. Extract the Zephyr SDK bundle archive:
+
+         .. code-block:: console
+
+            unzip zephyr-sdk-0.14.0_windows-x86_64.zip
+
+         .. note::
+            It is recommended to extract the Zephyr SDK bundle at one of the following locations:
+
+            * ``%HOMEPATH%``
+            * ``%PROGRAMFILES%``
+
+            The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.14.0`` directory and, when
+            extracted under ``%HOMEPATH%``, the resulting installation path will be
+            ``%HOMEPATH%\zephyr-sdk-0.14.0``.
+
+      #. Run the Zephyr SDK bundle setup script:
+
+         .. code-block:: console
+
+            cd zephyr-sdk-0.14.0
+            setup.cmd
+
+         .. note::
+            You only need to run the setup script once after extracting the Zephyr SDK bundle.
 
-      Do not forget to set the required :ref:`environment variables <env_vars>`
-      (:envvar:`ZEPHYR_TOOLCHAIN_VARIANT` and toolchain specific ones).
+            You must rerun the setup script if you relocate the Zephyr SDK bundle directory after
+            the initial setup.
 
 .. _getting_started_run_sample:
 
diff --git a/doc/getting_started/installation_linux.rst b/doc/getting_started/installation_linux.rst
@@ -210,87 +210,90 @@ environment is recommended to avoid interfering with your system Python.
 Install the Zephyr Software Development Kit (SDK)
 *************************************************
 
-Use of the Zephyr SDK is optional, but recommended. Some of the dependencies
-installed above are only needed for installing the SDK.
+The Zephyr Software Development Kit (SDK) contains toolchains for each of
+Zephyr's supported architectures. It also includes additional host tools, such
+as custom QEMU and OpenOCD.
 
-Zephyr's :abbr:`SDK (Software Development Kit)` contains all necessary tools to
-build Zephyr on all supported architectures. Additionally, it includes host
-tools such as custom QEMU binaries and a host compiler. The SDK supports the
-following target architectures:
+Use of the Zephyr SDK is highly recommended and may even be required under
+certain conditions (for example, running tests in QEMU for some architectures).
 
-* :abbr:`X86 (Intel Architecture 32 bits)`
+The Zephyr SDK supports the following target architectures:
 
-* :abbr:`Arm (Advanced RISC Machine)`
+* ARC (32-bit and 64-bit; ARCv1, ARCv2, ARCv3)
+* ARM (32-bit and 64-bit; ARMv6, ARMv7, ARMv8; A/R/M Profiles)
+* MIPS (32-bit and 64-bit)
+* Nios II
+* RISC-V (32-bit and 64-bit; RV32I, RV32E, RV64I)
+* x86 (32-bit and 64-bit)
+* Xtensa
 
-* :abbr:`ARC (Argonaut RISC Core)`
-
-* :abbr:`MIPS (Microprocessor without Interlocked Pipeline Stages)`
-
-* :abbr:`Nios II`
+Follow these steps to install the Zephyr SDK:
 
-* :abbr:`RISC-V`
+#. Download and verify the `latest Zephyr SDK bundle
+   <https://github.com/zephyrproject-rtos/sdk-ng/releases>`_:
 
-* :abbr:`SPARC`
+   .. code-block:: bash
 
-* :abbr:`Xtensa`
+      wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/zephyr-sdk-0.14.0_linux-x86_64.tar.gz
+      wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.14.0/sha256.sum | shasum --check --ignore-missing
 
-Follow these steps to install the Zephyr SDK:
+   You can change ``0.14.0`` to another version if needed; the `Zephyr SDK
+   Releases`_ page contains all available SDK releases.
 
-#. Download the `latest SDK
-   <https://github.com/zephyrproject-rtos/sdk-ng/releases>`_ as a
-   self-extracting installation binary:
+   If your host architecture is 64-bit ARM (for example, Raspberry Pi), replace
+   ``x86_64`` with ``aarch64`` in order to download the 64-bit ARM Linux SDK.
 
-   .. code-block:: console
+#. Extract the Zephyr SDK bundle archive:
 
-      wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.13.2/zephyr-sdk-0.13.2-linux-x86_64-setup.run
+   .. code-block:: bash
 
-   (You can change *0.13.2* to another version if needed; the `Zephyr
-   Downloads`_ page contains all available SDK releases.)
+      cd <sdk download directory>
+      tar xvf zephyr-sdk-0.14.0_linux-x86_64.tar.gz
 
-#. Run the installation binary, installing the SDK at
-   :file:`~/zephyr-sdk-0.13.2`:
+#. Run the Zephyr SDK bundle setup script:
 
-   .. code-block:: console
+   .. code-block:: bash
 
-      cd <sdk download directory>
-      chmod +x zephyr-sdk-0.13.2-linux-x86_64-setup.run
-      ./zephyr-sdk-0.13.2-linux-x86_64-setup.run -- -d ~/zephyr-sdk-0.13.2
+      cd zephyr-sdk-0.14.0
+      ./setup.sh
 
-   You can pick another directory if you want. If this fails, make sure
-   Zephyr's dependencies were installed as described in `Install Requirements
-   and Dependencies`_.
+   If this fails, make sure Zephyr's dependencies were installed as described
+   in `Install Requirements and Dependencies`_.
 
-If you ever want to uninstall the SDK, just remove the directory where you
-installed it.
+If you want to uninstall the SDK, remove the directory where you installed it.
+If you relocate the SDK directory, you need to re-run the setup script.
 
 .. note::
-   It is recommended to install the Zephyr SDK at one of the following locations:
+   It is recommended to extract the Zephyr SDK bundle at one of the following locations:
 
-   * ``$HOME/zephyr-sdk[-x.y.z]``
-   * ``$HOME/.local/zephyr-sdk[-x.y.z]``
-   * ``$HOME/.local/opt/zephyr-sdk[-x.y.z]``
-   * ``$HOME/bin/zephyr-sdk[-x.y.z]``
-   * ``/opt/zephyr-sdk[-x.y.z]``
-   * ``/usr/zephyr-sdk[-x.y.z]``
-   * ``/usr/local/zephyr-sdk[-x.y.z]``
+   * ``$HOME``
+   * ``$HOME/.local``
+   * ``$HOME/.local/opt``
+   * ``$HOME/bin``
+   * ``/opt``
+   * ``/usr/local``
 
-   where ``[-x.y.z]`` is optional text, and can be any text, for example ``-0.13.2``.
+   The Zephyr SDK bundle archive contains the ``zephyr-sdk-0.14.0`` directory and, when
+   extracted under ``$HOME``, the resulting installation path will be
+   ``$HOME/zephyr-sdk-0.14.0``.
 
-   If you install the Zephyr SDK outside any of those locations, then it is
-   required to register the Zephyr SDK in the CMake package registry during
-   installation or set :envvar:`ZEPHYR_SDK_INSTALL_DIR` to point to the Zephyr
-   SDK installation folder.
+   If you install the Zephyr SDK outside any of these locations, you must
+   register the Zephyr SDK in the CMake package registry by running the setup
+   script, or set :envvar:`ZEPHYR_SDK_INSTALL_DIR` to point to the Zephyr SDK
+   installation directory.
 
-   :envvar:`ZEPHYR_SDK_INSTALL_DIR` can also be used for pointing to a folder
-   containing multiple Zephyr SDKs, allowing for automatic toolchain selection,
-   for example: ``ZEPHYR_SDK_INSTALL_DIR=/company/tools``
+   You can also use :envvar:`ZEPHYR_SDK_INSTALL_DIR` for pointing to a
+   directory containing multiple Zephyr SDKs, allowing for automatic toolchain
+   selection. For example, ``ZEPHYR_SDK_INSTALL_DIR=/company/tools``, where
+   the ``company/tools`` folder contains the following subfolders:
 
    * ``/company/tools/zephyr-sdk-0.13.2``
    * ``/company/tools/zephyr-sdk-a.b.c``
    * ``/company/tools/zephyr-sdk-x.y.z``
 
-   this allow Zephyr to pick the right toolchain, while allowing multiple Zephyr
-   SDKs to be grouped together at a custom location.
+   This allows the Zephyr build system to choose the correct version of the
+   SDK, while allowing multiple Zephyr SDKs to be grouped together at a
+   specific path.
 
 .. _sdkless_builds:
 
@@ -316,5 +319,5 @@ To make sure this variable is unset, run:
 
    unset ZEPHYR_SDK_INSTALL_DIR
 
-.. _Zephyr Downloads: https://github.com/zephyrproject-rtos/sdk-ng/releases
+.. _Zephyr SDK Releases: https://github.com/zephyrproject-rtos/sdk-ng/releases
 .. _CMake Downloads: https://cmake.org/download
