diff --git a/doc/getting_started/index.rst b/doc/getting_started/index.rst index c1f5579161fb..54ae2c6391e6 100644 --- a/doc/getting_started/index.rst +++ b/doc/getting_started/index.rst @@ -119,7 +119,7 @@ The current minimum required version for the main dependencies are: .. code-block:: bash - brew install cmake ninja gperf python3 ccache qemu dtc + brew install cmake ninja gperf python3 ccache qemu dtc wget .. group-tab:: Windows @@ -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 + 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 `_: .. 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 `_ 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 + `_: - Do not forget to set the required :ref:`environment variables ` - (: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 + `_: + + .. 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 ` - (: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 index 442dcb84fa3d..561adbc66e05 100644 --- 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 + `_: -* :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 - `_ 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 + 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 - 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 diff --git a/doc/guides/beyond-GSG.rst b/doc/guides/beyond-GSG.rst index 1cc94bec75d7..45a9138c86a2 100644 --- a/doc/guides/beyond-GSG.rst +++ b/doc/guides/beyond-GSG.rst @@ -64,22 +64,20 @@ a cross-compiler and related tools which are different than the compiler and tools used for developing software that runs natively on your operating system. -On Linux systems, you can install the :ref:`Zephyr SDK ` to -get toolchains for all supported architectures. Otherwise, you can -install other toolchains in the usual way for your operating system: with -installer programs or system package managers, by downloading and -extracting a zip archive, etc. +You can install the :ref:`Zephyr SDK ` to get toolchains for all +supported architectures. Otherwise, you can install other toolchains in the +usual way for your operating system: with installer programs or system package +managers, by downloading and extracting a zip archive, and so on. You configure the Zephyr build system to use a specific toolchain by setting :ref:`environment variables ` such as :envvar:`ZEPHYR_TOOLCHAIN_VARIANT` to a supported value, along with additional variable(s) specific to the toolchain variant. -While the Zephyr SDK includes standard tool chains for all supported +While the Zephyr SDK includes standard toolchains for all supported architectures, there are also customized alternatives as described in these documents. (If you're not sure which to use, check your specific -:ref:`board-level documentation `. If you're targeting an Arm -Cortex-M board, for example, :ref:`toolchain_gnuarmemb` is a safe bet.) +:ref:`board-level documentation `.) .. toctree:: :maxdepth: 2