Skip to content
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

docs: Rework of getting started guide #46949

Merged
merged 2 commits into from
Aug 30, 2022
Merged

docs: Rework of getting started guide #46949

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4f21357
docs: getting_started: change default python setup to use virtual env
danieldegrasse Jun 27, 2022
4c85ee3
docs: getting_started: add note about west boards command
danieldegrasse Jun 27, 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
140 changes: 75 additions & 65 deletions doc/develop/getting_started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,11 +184,15 @@ Next, clone Zephyr and its :ref:`modules <modules>` into a new :ref:`west
<west>` workspace named :file:`zephyrproject`. You'll also install Zephyr's
additional Python dependencies.

Python is used by the ``west`` meta-tool as well as by many scripts invoked by
the build system. It is easy to run into package incompatibilities when
installing dependencies at a system or user level. This situation can happen,
for example, if working on multiple Zephyr versions at the same time. For this
reason it is suggested to use `Python virtual environments`_.

.. note::

It is easy to run into Python package incompatibilities when installing
dependencies at a system or user level. This situation can happen,
for example, if working on multiple Zephyr versions or other projects
using Python on the same machine.

For this reason it is suggested to use `Python virtual environments`_.

.. _Python virtual environments: https://docs.python.org/3/library/venv.html

Expand All @@ -198,40 +202,6 @@ reason it is suggested to use `Python virtual environments`_.

.. tabs::

.. group-tab:: Install globally

#. Install west, and make sure :file:`~/.local/bin` is on your
:envvar:`PATH` :ref:`environment variable <env_vars>`:

.. code-block:: bash

pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

#. Get the Zephyr source code:

.. code-block:: bash

west init ~/zephyrproject
cd ~/zephyrproject
west update

#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.

.. code-block:: console

west zephyr-export

#. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.

.. code-block:: bash

pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt

.. group-tab:: Install within virtual environment

#. Use ``apt`` to install Python ``venv`` package:
Expand Down Expand Up @@ -290,17 +260,16 @@ reason it is suggested to use `Python virtual environments`_.

pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

.. group-tab:: macOS

.. tabs::

.. group-tab:: Install globally

#. Install west:
#. Install west, and make sure :file:`~/.local/bin` is on your
:envvar:`PATH` :ref:`environment variable <env_vars>`:

.. code-block:: bash

pip3 install -U west
pip3 install --user -U west
echo 'export PATH=~/.local/bin:"$PATH"' >> ~/.bashrc
source ~/.bashrc

#. Get the Zephyr source code:

Expand All @@ -323,7 +292,11 @@ reason it is suggested to use `Python virtual environments`_.

.. code-block:: bash

pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt
pip3 install --user -r ~/zephyrproject/zephyr/scripts/requirements.txt

.. group-tab:: macOS

.. tabs::

.. group-tab:: Install within virtual environment

Expand Down Expand Up @@ -377,41 +350,40 @@ reason it is suggested to use `Python virtual environments`_.

pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt

.. group-tab:: Windows

.. tabs::

.. group-tab:: Install globally

#. Install west:

.. code-block:: bat
.. code-block:: bash

pip3 install -U west

#. Get the Zephyr source code:

.. code-block:: bat
.. code-block:: bash

cd %HOMEPATH%
west init zephyrproject
cd zephyrproject
west init ~/zephyrproject
cd ~/zephyrproject
west update

#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.

.. code-block:: bat
.. code-block:: console

west zephyr-export

#. Zephyr's ``scripts\requirements.txt`` file declares additional Python
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.

.. code-block:: bat
.. code-block:: bash

pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt

.. group-tab:: Windows

.. tabs::

.. group-tab:: Install within virtual environment

Expand All @@ -420,7 +392,7 @@ reason it is suggested to use `Python virtual environments`_.
.. code-block:: bat

cd %HOMEPATH%
python3 -m venv zephyrproject\.venv
python -m venv zephyrproject\.venv

#. Activate the virtual environment:

Expand Down Expand Up @@ -469,8 +441,41 @@ reason it is suggested to use `Python virtual environments`_.

pip install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt

.. group-tab:: Install globally

#. Install west:

.. code-block:: bat

pip3 install -U west

#. Get the Zephyr source code:

.. code-block:: bat

cd %HOMEPATH%
west init zephyrproject
cd zephyrproject
west update

#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.

.. code-block:: bat

west zephyr-export

#. Zephyr's ``scripts\requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.

.. code-block:: bat

pip3 install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt

.. rst-class:: numbered-step


Install Zephyr SDK
******************

Expand Down Expand Up @@ -640,6 +645,9 @@ Build the Blinky Sample
does not meet Blinky's :ref:`blinky-sample-requirements`, then
:ref:`hello_world` is a good alternative.

If you are unsure what name west uses for your board, ``west boards``
can be used to obtain a list of all boards Zephyr supports.

Build the :ref:`blinky-sample` with :ref:`west build <west-building>`, changing
``<your-board-name>`` appropriately for your board:

Expand All @@ -650,24 +658,26 @@ Build the :ref:`blinky-sample` with :ref:`west build <west-building>`, changing
.. code-block:: bash

cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky
west build -p always -b <your-board-name> samples/basic/blinky

.. group-tab:: macOS

.. code-block:: bash

cd ~/zephyrproject/zephyr
west build -p auto -b <your-board-name> samples/basic/blinky
west build -p always -b <your-board-name> samples/basic/blinky

.. group-tab:: Windows

.. code-block:: bat

cd %HOMEPATH%\zephyrproject\zephyr
west build -p auto -b <your-board-name> samples\basic\blinky
west build -p always -b <your-board-name> samples\basic\blinky

The ``-p auto`` option automatically cleans byproducts from a previous build
if necessary, which is useful if you try building another sample.
The ``-p always`` option forces a pristine build, and is recommended for new
users. Users may also use the ``-p auto`` option, which will use
heuristics to determine if a pristine build is required, such as when building
another sample.

.. rst-class:: numbered-step

Expand Down