Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 29, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c15abb5
doc: getting_started: Add wget as a common host dependency
stephanosio Feb 21, 2022
9fda663
doc: getting_started: Add instructions for multi-platform Zephyr SDK
stephanosio Feb 21, 2022
7aafa77
doc: beyong-GSG: Update instructions for multi-platform Zephyr SDK
stephanosio Mar 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 116 additions & 33 deletions doc/getting_started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd personally remove M1 references, I'm pretty sure we'll have M2 or M1plus or whatever at some point.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, Apple is currently working on the "M2" chip; but, as of now, all the production Macs are M1 and they refer to those as "M1" in the marketing materials too.

I think we can update/generalise this later when they actually have multiple M series SoCs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think just mentioning Apple Sillicon means we don't have to keep updating the document when, e.g., M2 is released.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @gmarull, let's stick to "Apple Silicon". Please send a follow-up PR @stephanosio.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at https://www.apple.com/mac-mini/, they almost exclusively refer to their Arm-based Mac Minis as "M1" and there is not a single mention of the "Apple Silicon" on that page (from what I can see, they stopped using the "Apple Silicon" term, at least in the marketing materials); in that sense, I think it is helpful to keep that "aka. M1" for now.

When they release a new M series SoC, I will make sure to send a follow-up PR either generalising that phrase or just completely removing it.

``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:

Expand Down
111 changes: 57 additions & 54 deletions doc/getting_started/installation_linux.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
14 changes: 6 additions & 8 deletions doc/guides/beyond-GSG.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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 <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 <env_vars>` 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 <boards>`. If you're targeting an Arm
Cortex-M board, for example, :ref:`toolchain_gnuarmemb` is a safe bet.)
:ref:`board-level documentation <boards>`.)

.. toctree::
:maxdepth: 2
Expand Down