michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: getting_started: remove global Python setup

Browse source 
As it was already outlined, installing Python dependencies at a system
level or user level can be dangerous. For this reason, the default setup
instructions already pointed users to use Python virtual environments. On
newer Ubuntu installations (23.04 onwards) system-level pip installs are
not allowed. Let's make Zephyr _Python-safe_ as well by removing dangerous
instructions.

Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>
This commit is contained in:
Gerard Marull-Paretas 2024-07-15 16:06:13 +02:00 • committed by Carles Cufí
commit 33d92b4acd
1 changed files with 94 additions and 216 deletions
Download patch file Download diff file Expand all files Collapse all files

310
doc/develop/getting_started/index.rst
View file

@ -207,298 +207,176 @@ Get Zephyr and install Python dependencies
Next, clone Zephyr and its :ref:`modules <modules>` into a new :ref:`west Next, clone Zephyr and its :ref:`modules <modules>` into a new :ref:`west
<west>` workspace named :file:`zephyrproject`. You'll also install Zephyr's <west>` workspace named :file:`zephyrproject`. You'll also install Zephyr's
additional Python dependencies. additional Python dependencies in a `Python virtual environment`_.
.. _Python virtual environment: https://docs.python.org/3/library/venv.html
.. 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
.. tabs:: .. tabs::
.. group-tab:: Ubuntu .. group-tab:: Ubuntu
.. tabs:: #. Use ``apt`` to install Python ``venv`` package:
.. group-tab:: Install within virtual environment .. code-block:: bash
#. Use ``apt`` to install Python ``venv`` package: sudo apt install python3-venv
.. code-block:: bash #. Create a new virtual environment:
sudo apt install python3-venv .. code-block:: bash
#. Create a new virtual environment: python3 -m venv ~/zephyrproject/.venv
.. code-block:: bash #. Activate the virtual environment:
python3 -m venv ~/zephyrproject/.venv .. code-block:: bash
#. Activate the virtual environment: source ~/zephyrproject/.venv/bin/activate
.. code-block:: bash Once activated your shell will be prefixed with ``(.venv)``. The
virtual environment can be deactivated at any time by running
``deactivate``.
source ~/zephyrproject/.venv/bin/activate .. note::
Once activated your shell will be prefixed with ``(.venv)``. The Remember to activate the virtual environment every time you
virtual environment can be deactivated at any time by running start working.
``deactivate``.
.. note:: #. Install west:
Remember to activate the virtual environment every time you .. code-block:: bash
start working.
#. Install west: pip install west
.. code-block:: bash #. Get the Zephyr source code:
pip install west .. code-block:: bash
#. Get the Zephyr source code: west init ~/zephyrproject
cd ~/zephyrproject
west update
.. code-block:: bash #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.
west init ~/zephyrproject .. code-block:: bash
cd ~/zephyrproject
west update
#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to west zephyr-export
automatically load boilerplate code required for building Zephyr
applications.
.. code-block:: bash #. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip``.
west zephyr-export .. code-block:: bash
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
dependencies. Install them with ``pip``.
.. code-block:: bash
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. 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:: bash
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:: macOS .. group-tab:: macOS
.. tabs:: #. Create a new virtual environment:
.. group-tab:: Install within virtual environment .. code-block:: bash
#. Create a new virtual environment: python3 -m venv ~/zephyrproject/.venv
.. code-block:: bash #. Activate the virtual environment:
python3 -m venv ~/zephyrproject/.venv .. code-block:: bash
#. Activate the virtual environment: source ~/zephyrproject/.venv/bin/activate
.. code-block:: bash Once activated your shell will be prefixed with ``(.venv)``. The
virtual environment can be deactivated at any time by running
``deactivate``.
source ~/zephyrproject/.venv/bin/activate .. note::
Once activated your shell will be prefixed with ``(.venv)``. The Remember to activate the virtual environment every time you
virtual environment can be deactivated at any time by running start working.
``deactivate``.
.. note:: #. Install west:
Remember to activate the virtual environment every time you .. code-block:: bash
start working.
#. Install west: pip install west
.. code-block:: bash #. Get the Zephyr source code:
pip install west .. code-block:: bash
#. Get the Zephyr source code: west init ~/zephyrproject
cd ~/zephyrproject
west update
.. code-block:: bash #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.
west init ~/zephyrproject .. code-block:: bash
cd ~/zephyrproject
west update
#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to west zephyr-export
automatically load boilerplate code required for building Zephyr
applications.
.. code-block:: bash #. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip``.
west zephyr-export .. code-block:: bash
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
dependencies. Install them with ``pip``.
.. code-block:: bash
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. group-tab:: Install globally
#. Install west:
.. code-block:: bash
pip3 install -U west
#. 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:: bash
west zephyr-export
#. Zephyr's ``scripts/requirements.txt`` file declares additional Python
dependencies. Install them with ``pip3``.
.. code-block:: bash
pip3 install -r ~/zephyrproject/zephyr/scripts/requirements.txt
.. group-tab:: Windows .. group-tab:: Windows
.. tabs:: #. Open a ``cmd.exe`` terminal window **as a regular user**
.. group-tab:: Install within virtual environment #. Create a new virtual environment:
#. Open a ``cmd.exe`` terminal window **as a regular user** .. code-block:: bat
#. Create a new virtual environment: cd %HOMEPATH%
python -m venv zephyrproject\.venv
.. code-block:: bat #. Activate the virtual environment:
cd %HOMEPATH% .. code-block:: bat
python -m venv zephyrproject\.venv
#. Activate the virtual environment: zephyrproject\.venv\Scripts\activate.bat
.. code-block:: bat Once activated your shell will be prefixed with ``(.venv)``. The
virtual environment can be deactivated at any time by running
``deactivate``.
zephyrproject\.venv\Scripts\activate.bat .. note::
Once activated your shell will be prefixed with ``(.venv)``. The Remember to activate the virtual environment every time you
virtual environment can be deactivated at any time by running start working.
``deactivate``.
.. note:: #. Install west:
Remember to activate the virtual environment every time you .. code-block:: bat
start working.
#. Install west: pip install west
.. code-block:: bat #. Get the Zephyr source code:
pip install west .. code-block:: bat
#. Get the Zephyr source code: west init zephyrproject
cd zephyrproject
west update
.. code-block:: bat #. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to
automatically load boilerplate code required for building Zephyr
applications.
west init zephyrproject .. code-block:: bat
cd zephyrproject
west update
#. Export a :ref:`Zephyr CMake package <cmake_pkg>`. This allows CMake to west zephyr-export
automatically load boilerplate code required for building Zephyr
applications.
.. code-block:: bat #. Zephyr's ``scripts\requirements.txt`` file declares additional Python
dependencies. Install them with ``pip``.
west zephyr-export .. code-block:: bat
#. Zephyr's ``scripts\requirements.txt`` file declares additional Python
dependencies. Install them with ``pip``.
.. code-block:: bat
pip install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
.. group-tab:: Install globally
#. Open a ``cmd.exe`` terminal window **as a regular user**
#. 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
pip install -r %HOMEPATH%\zephyrproject\zephyr\scripts\requirements.txt
Install the Zephyr SDK Install the Zephyr SDK
********************** **********************