Re: [docs] [PATCH v2 1/2] ref-manual/system-requirements.rst: make python3-websockets a default host requirement

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi,

On Mon Apr 20, 2026 at 12:43 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 4/20/26 11:52 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> When configuring the project through bitbake-setup we can choose the
>> "poky-with-sstate" configuration, which requires the python3-websockets
>> package.
>> 
>> Add this package as a host requirement (under different names depending
>> on the distro).
>> 
>> Alma, CentOS, and Rocky have a requirement on the buildtools tarball,
>> which already contains this package, so we don't need to add it for
>> them.
>> 
>> On Ubuntu 22.04 and Debian 11, the version of python3-websockets
>> provided by the distribution is too old compared to what we need [1].
>> Add a separate set of instructions for these.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/ref-manual/system-requirements.rst   | 28 ++++++++++++++++++++++
>>   .../host_packages_scripts/fedora_essential.sh      |  2 +-
>>   .../opensuse_essential_16.0.sh                     |  2 +-
>>   3 files changed, 30 insertions(+), 2 deletions(-)
>> 
>> diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
>> index 298832dd9..baa965573 100644
>> --- a/documentation/ref-manual/system-requirements.rst
>> +++ b/documentation/ref-manual/system-requirements.rst
>> @@ -166,6 +166,34 @@ Ubuntu and Debian
>>   
>>   .. include:: ubuntu-debian-host-packages-nodocs.rst
>>   
>> +Additionally, on distributions other than Debian 11 and Ubuntu 22.04 (otherwise
>> +see note below), install the following package:
>> +
>> +.. code-block:: console
>> +
>> +   $ sudo apt install python3-websockets
>> +
>
> Maybe use apt-get here? I know we have one or the other across the 
> code-base. For some reason, I can't bring myself to use apt, it always 
> results in weird behaviors I don't have using apt-get on servers (I 
> don't run Debian-based on my own machines).

Yes, that's better to use here and also aligns with the rest, thanks!

>> +.. note::
>> +
>> +   On Debian 11 and Ubuntu 22.04, the requirement on the version of
>
> A bit awkward wording to me, would
>
> the minimum version for ``python3-websockets`` is not satisfied...
>
> work better?

Indeed, will rephrase

>> +   ``python3-websockets`` is not satisfied by the host distribution. This
>> +   package is used for fetching pre-built :ref:`shared state
>> +   <overview-manual/concepts:shared state>` artifacts from upstream Yocto Project
>> +   servers (see :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` for more
>> +   information).
>> +
>> +   In order to use this feature, you can get the correct version of
>> +   ``python3-websockets`` by either:
>> +
>> +   -  Using a :term:`buildtools` tarball by following the
>> +      :ref:`system-requirements-buildtools` section below.
>> +
>> +   -  Installing ``python3-websockets`` using `Pip <https://pip.pypa.io/en/stable/>`__:
>> +
>> +      .. code-block:: console
>> +
>> +         $ pip install websockets
>> +
>
> websockets 9.1 supports Python 3.9 which is available in Debian 11 and 
> Ubuntu 22.04 so it'll get at least that version (it's not because a 
> newer version of a package is available on PyPI that your system can 
> install it; and the opposite is true, you may have a too new Python 
> version for the last package version available (e.g. tensorflow-lite 
> isn't compatible with Python 3.14)). Can you check what happens if the 
> user already has python3-websockets installed on the system and runs 
> this command? My hunch is it'll not get updated to >=9.1 without 
> -U/--upgrade. Also, running -U will likely break their system if any of 
> the hsot packages depend on that older version of websockets... Maybe we 
> should only be using Python packages from a virtualenv?

Maybe I can state that this it is advised to install it in a virtual environment
and avoid the possible gotchas you stated?

>>   Here are the packages needed to build Project documentation manuals:
>>   
>>   .. literalinclude:: ../tools/host_packages_scripts/ubuntu_docs.sh
>> diff --git a/documentation/tools/host_packages_scripts/fedora_essential.sh b/documentation/tools/host_packages_scripts/fedora_essential.sh
>> index 99e5d2c0b..55b8b704b 100644
>> --- a/documentation/tools/host_packages_scripts/fedora_essential.sh
>> +++ b/documentation/tools/host_packages_scripts/fedora_essential.sh
>> @@ -1 +1 @@
>> -sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd $([ $(rpm -E %fedora) -ge 42 ] && echo "util-linux-script")
>> +sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip python3-websockets rpcgen socat tar texinfo unzip wget which xz zstd $([ $(rpm -E %fedora) -ge 42 ] && echo "util-linux-script")
>> diff --git a/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh b/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
>> index e557ae4fb..96bdd9317 100644
>> --- a/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
>> +++ b/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
>> @@ -1 +1 @@
>> -sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python3 python3-GitPython python3-Jinja2 python3-curses python3-pexpect python3-pip python3-xml rpcgen socat tar wget which xz zstd
>> +sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python3 python3-GitPython python3-Jinja2 python3-curses python3-pexpect python3-pip python313-websockets python3-xml rpcgen socat tar wget which xz zstd
>
> Can you rather use python3-websockets here? 
> https://opensuse.pkgs.org/16.0/opensuse-oss/python313-websockets-14.2-160000.2.2.aarch64.rpm.html 
> says it provides and replaces python3-websockets. That should make the 
> upgrade to the next Leap version easier since I'm assuming it may switch 
> to Python 3.14 by then?

Ah good point, I did not spot that it was a provider of python3-websockets. I'll
correct that.

Thanks,
Antonin