From 8f73e7ae9bd9f634253ec06e8e97e7ab6c5ca5dc Mon Sep 17 00:00:00 2001 From: Nicolas Dessart Date: Wed, 10 Nov 2021 17:55:10 +0100 Subject: [PATCH] [DEVMINOR] update install procedure Change-Id: I1ffbb488d1f882af95fa4f587876224b7a7db9aa --- src/olympe/doc/installation.rst | 155 ++++++++++++++++++++++++++++---- 1 file changed, 139 insertions(+), 16 deletions(-) diff --git a/src/olympe/doc/installation.rst b/src/olympe/doc/installation.rst index 3311e65..10db7f8 100644 --- a/src/olympe/doc/installation.rst +++ b/src/olympe/doc/installation.rst @@ -6,20 +6,29 @@ Installation Olympe Python Wheels Runtime Requirements ----------------------------------------- -Olympe is Python 3 only and requires Ubuntu 20.04 or higher, Debian 10 or higher. +Olympe is a Python 3 only package and requires Ubuntu 20.04 or higher, Debian 10 or higher. + +Note: If you're running Linux without a graphical desktop environment installed, you'll also need to +install the `libgl1` package. + +.. code-block:: console + + $ sudo apt-get install libgl1 Install via pip (x86_64 desktop only) ------------------------------------- -Installation of Olympe wheels requires pip version 20.3 or higher. You should first check your -`pip --version` and use a `virtual environment _` -if necessary. +Installation of Olympe wheels requires pip version 20.3 or higher. As Ubuntu and Debian latest LTS +release provided pip versions are currently too old you MUST use a `virtual environment +`_. See the Python environment +:ref:`best practices` below for why and how to install a Python virtual environment. The rest of +this section assumes that you have activated a suitable virtual environment in your current shell. Install the latest available version of Olympe via pip: .. code-block:: console - $ python3 -m pip install --user parrot-olympe + $ pip install parrot-olympe Alternatively, to install a specific Olympe version, you should browse the https://github.com/Parrot-Developers/olympe/releases page and pip install the .whl associated to @@ -27,7 +36,7 @@ this version, for example: .. code-block:: console - $ python3 -m pip install --user https://github.com/Parrot-Developers/olympe/releases/download/v7.0.1/parrot_olympe-7.0.1-py3-none-manylinux_2_27_x86_64.whl + $ pip install https://github.com/Parrot-Developers/olympe/releases/download/v7.0.2/parrot_olympe-7.0.2-py3-none-manylinux_2_27_x86_64.whl Build from source (for x86_64, armv7 or aarch64) @@ -48,7 +57,7 @@ Download and extract the .tar.gz archive associated with the latest release of O .. code-block:: console $ mkdir -p ~/code/{{ workspace }} - $ curl https://github.com/Parrot-Developers/olympe/releases/download/v7.0.1/parrot-olympe-src-7.0.1.tar.gz | tar zxf - -C ~/code/{{ workspace }} --strip-components=1 + $ curl -L https://github.com/Parrot-Developers/olympe/releases/download/v7.0.2/parrot-olympe-src-7.0.2.tar.gz | tar zxf - -C ~/code/{{ workspace }} --strip-components=1 $ cd ~/code/{{ workspace }} @@ -58,7 +67,7 @@ Install {{ olympe_product }} dependencies System dependencies installation procedure ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To install the system dependencies of the "{{ workspace }}" workspace, just execute the `postinst` script. +To install the system dependencies of the `{{ workspace }}` workspace, just execute the `postinst` script. .. code-block:: console @@ -99,10 +108,11 @@ Olympe wheels are built in the `out/olympe-linux/images` workspace subdirectory. Set up the development environment ---------------------------------- -Finally, you need to set up the shell environment in which you will execute Olympe scripts. -In the future, you will have to do this before you execute an Olympe script. +Finally, if you want to test Olympe from your development workspace, you need to set up the shell +environment in which you will execute Olympe scripts. In the future, you will have to do this before +you execute an Olympe script from your development workspace. -To setup an interactive Olympe Python environment, source the `shell` script: +To setup an interactive Olympe Python virtual environment, source the `shell` script: .. code-block:: console @@ -113,7 +123,7 @@ To setup an interactive Olympe Python environment, source the `shell` script: pip 21.3.1 from ~/code/{{ workspace }}/out/{{ olympe_product }}/pyenv_root/versions/3.9.5/lib/python3.9/site-packages/pip (python 3.9) -The shell script can be sourced from outside the workspace: +Note: this shell script can also be sourced from outside the workspace: .. code-block:: console @@ -121,7 +131,8 @@ The shell script can be sourced from outside the workspace: ~/code/some/super/cool/project/path $ source ~/code/{{ workspace }}/{{ olympe_scripts_path }}/shell -When a Python environment is active, your shell prompt should be prefixed by ```{{ python_prompt }} ```. +When a Python virtual environment is active, your shell prompt should be prefixed by +```{{ python_prompt }} ```. In this console you can now execute your Olympe script, for example: @@ -132,7 +143,7 @@ In this console you can now execute your Olympe script, for example: Once you've finished working with Olympe, just type `exit` or press `Ctrl+D` to exit the active environment and restore your previous prompt. -**Please, exit any active environment now before continuing.** +**Please, exit any active environment now before continuing with this user guide.** .. code-block:: console @@ -140,8 +151,8 @@ active environment and restore your previous prompt. $ If you need to execute a script from a non-interactive environment (for example in a CI job), -source the `setenv` or the `setenv3` scripts instead. These scripts don't spawn a new shell for you, -don't change your current prompt and just set up the environment in your current shell process. +source the `setenv` scripts instead. This script does not spawn a new shell for you, +does not change your current prompt and just sets up the environment in your current shell process. Check your development environment @@ -159,3 +170,115 @@ If your installation succeeded, the following commands shouldn't report any erro $ exit +.. _best practices: + +Python environment best practices on Debian-based distros +========================================================= + +This section of the documentation is not specific to Olympe and introduce the usage of Python +virtual environment from a beginner perspective in order to avoid Python package installation +pitfalls with pip. + +What's a Python virtual environment +----------------------------------- + +A Python virtual environment is a Python environment isolated from the system-wide Python +environment. A package installed in one virtual environment does not change anything in the +system-wide environment (or any other virtual environment). Python virtual environment can be +created by any user without any specific priviledges. A "virtual env" resides in a directory +chosen by the user and contains a "site-packages" where Python packages are installed. To use a +specific virtual environment, the user usually has to source or execute a specific script that will +activate the environment, set up environment variables and change the current shell prompt. Once a +particular environment is activated, any `python` or `pip` process executed from it will use the +virtual environment "site-packages" directory instead of the system "site-packages" directory. + +Why using a Python virtual environment is important +--------------------------------------------------- + +Using `/usr/bin/python3` the system-wide Python interpreter environment for testing & development +should generally be avoided. Creating a virtual environment per development project should be the +default instead. Here is why: + +1. Virtual environments allow users to pip install Python packages without breaking the + system-wide Python environment. **Unlike popular system package managers like `apt`, `pip` + does not manage packages dependencies once they are installed.** This means that, installing + a package "A" that depends on a package "B", and then installing a package "C" that depends + on an incompatible version of package "B" (a simple "pip install A" followed by + "pip install C") WILL break package "A". + +2. The system-wide Python environment is usually managed by the system package manager (apt) and + using pip to install packages in this environment really is asking for trouble. The two + package managers don't talk to each others and **pip will most likely break apt installed + Python packages** even without sudoing things and using the "--user" pip flag. Even if `pip` + does not mess around with files under `/usr` and stick to the user site-packages directory + `~/.local/lib/pythonX.Y/site-packages` with the "--user" flag enabled, packages installed + there will still be visible from the system Python interpreter. For example, this means you + can break `pip` or `apt` (it also depends on Python...) with just one harmless + `pip install --user ...` command. + +3. You can't `pip install --upgrade pip` (or `python get-pip.py`) in the system environment. + Doing this WILL break your environment sometime in very subtle ways. Installing just one + random package with pip can result in a pip self-upgrade (if pip is a dependency of that + package...). When you create a Python virtual environment you're able to upgrade the version + of `pip` inside it without any issue. + +4. Outside a virtual environment, you can't rely on the `python3` package provided by Debian + and/or Ubuntu via apt because Debian patches the interpreter (and `pip`) to behave + differently outside a virtual environment when installing packages. The situation is messy. + **I can't stress this enough** but the official pypa.io pip installation guide does not + provide a viable solution to install `pip` on Debian system. **Trying to follow the pypa.io + installation "supported methods" (ensurepip/get-pip.py) will break your Debian based Python + environment.** The devil is in the details, but their installation procedure suppose that you + are using an upstream Python interpreter... not the one provided by your distro. + +5. Finally, you should never have to `sudo pip install ...` to install a package. Doing so is a + beginner mistake, and you should now know why. Usually, when someone has to resort to this it + means their environment is already broken. :) + + +Using one virtual environment per project allows you to have an environment isolated from the system +environment in which you can install any package (including a recent version of `pip`) without +risking to break anything. + +Creating a Python virtual environment on a Debian-based system +-------------------------------------------------------------- + +On Debian-based distros you first need to ensure that the Python standard `venv` library is +available. + +.. code-block:: console + + $ sudo apt-get install python3-venv + +You can then create your first virtual environment: + +.. code-block:: console + + $ python3 -m venv my-virtual-env + +This will create a `my-virtual-env` virtual environment in the current directory. +To enter/activate this virtual environment in the current shell, you need to "source" its activation +script. The first thing you want to do in this environment is upgrading pip. + +.. code-block:: console + + $ . ./my-virtual-env/bin/activate + (my-virtual-env) $ python --version + Python 3.8.10 + (my-virtual-env) $ pip install --upgrade pip + ... + (my-virtual-env) $ pip --version + pip 21.3.1 from /home/user/my-virtual-env/lib/python3.8/site-packages/pip (python 3.8) + +To deactivate/exit the virtual environment, just type `deactivate`, since we are down with this +little virtual experience, we can safely remove this virtual environment from our filesystem. + +.. code-block:: console + + (my-virtual-env) $ deactivate + $ rm -rf my-virtual-env/ + +Note: On Debian-based distros, you have little to no use for the apt provided `pip` (the +`python3-pip` package). I personaly use it just to install `virtualenv +`_ (a better/faster version of `venv +`_).