mirror of
https://github.com/qemu/qemu.git
synced 2025-07-24 10:00:21 +00:00

The way editable installs work has changed at some point since Fedora 40 was released. Generally, we should be opting to use pyproject.toml installs (PEP517/518) - but those are not fully supported until v61 of setuptools, and CentOS Stream 9 ships v53. Until that time, we can make use of a transitional feature in pip/setuptools to use "legacy" editable installs, which is enough to fix "make check-dev" on modern local workstations for now. By using the environment variable approach to configure pip, we avoid any problems for older versions of pip that don't recognize this option, so it's harmless. The config-settings option first appeared in v23 of pip. editable_mode was first supported by setuptools in v64. (I'm not currently precisely aware of when the default behavior of '-e' switched away from 'compat', but it appears to be a joint effect between setuptools and pip versions.) Version information for supported build platforms: distro python3 pip setuptools sphinx -------------------------------------------------------- centos_stream_9 3.9.23 21.3.1 53.0.0 3.4.3 ubuntu_22_04 3.10.12 22.0.2 59.6.0 4.3.2 ** pyproject.toml installs supported as of here ** freebsd 3.11.13 23.3.2 63.1.0 5.3.0 debian_12 3.11.2 23.0.1 66.1.1 5.3.0 ubuntu_24_04 3.12.3 24.0 68.1.2 7.2.6 centos_stream_10 3.12.11 23.3.2 69.0.3 7.2.6 fedora_41 3.13.5 24.2 69.2.0 7.3.7 alpine_3_19 3.11.13 23.3.1 70.3.0 6.2.1 alpine_3_20 3.12.11 24.0 70.3.0 7.2.6 alpine_3_21 3.12.11 24.3.1 70.3.0 8.1.3 ubuntu_24_10 3.12.7 24.2 74.1.2 7.4.7 fedora_42 3.13.5 24.3.1 74.1.3 8.1.3 ubuntu_25_04 3.13.3 25.0 75.8.0 8.1.3 macports 3.13.5 25.1.1 78.1.1 8.2.3 openbsd 3.12.11 25.1.1 79.0.1 8.2.3 alpine_3_22 3.12.11 25.1.1 80.9.0 8.2.3 homebrew 3.13.5 --- 80.9.0 8.2.3 pkgsrc_current 3.12.11 25.1.1 80.9.0 8.2.3 Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250715222548.198888-1-jsnow@redhat.com> Tested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
QEMU Python Tooling =================== This directory houses Python tooling used by the QEMU project to build, configure, and test QEMU. It is organized by namespace (``qemu``), and then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc). ``setup.py`` is used by ``pip`` to install this tooling to the current environment. ``setup.cfg`` provides the packaging configuration used by ``setup.py``. You will generally invoke it by doing one of the following: 1. ``pip3 install .`` will install these packages to your current environment. If you are inside a virtual environment, they will install there. If you are not, it will attempt to install to the global environment, which is **not recommended**. 2. ``pip3 install --user .`` will install these packages to your user's local python packages. If you are inside of a virtual environment, this will fail; you want the first invocation above. If you append the ``--editable`` or ``-e`` argument to either invocation above, pip will install in "editable" mode. This installs the package as a forwarder ("qemu.egg-link") that points to the source tree. In so doing, the installed package always reflects the latest version in your source tree. Installing ".[devel]" instead of "." will additionally pull in required packages for testing this package. They are not runtime requirements, and are not needed to simply use these libraries. Running ``make develop`` will pull in all testing dependencies and install QEMU in editable mode to the current environment. (It is a shortcut for ``pip3 install -e .[devel]``.) See `Installing packages using pip and virtual environments <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_ for more information. Using these packages without installing them -------------------------------------------- These packages may be used without installing them first, by using one of two tricks: 1. Set your PYTHONPATH environment variable to include this source directory, e.g. ``~/src/qemu/python``. See https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH 2. Inside a Python script, use ``sys.path`` to forcibly include a search path prior to importing the ``qemu`` namespace. See https://docs.python.org/3/library/sys.html#sys.path A strong downside to both approaches is that they generally interfere with static analysis tools being able to locate and analyze the code being imported. Package installation also normally provides executable console scripts, so that tools like ``qmp-shell`` are always available via $PATH. To invoke them without installation, you can invoke e.g.: ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell`` The mappings between console script name and python module path can be found in ``setup.cfg``. Files in this directory ----------------------- - ``qemu/`` Python 'qemu' namespace package source directory. - ``tests/`` Python package tests directory. - ``avocado.cfg`` Configuration for the Avocado test-runner. Used by ``make check`` et al. - ``Makefile`` provides some common testing/installation invocations. Try ``make help`` to see available targets. - ``MANIFEST.in`` is read by python setuptools, it specifies additional files that should be included by a source distribution. - ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. - ``README.rst`` you are here! - ``VERSION`` contains the PEP-440 compliant version used to describe this package; it is referenced by ``setup.cfg``. - ``setup.cfg`` houses setuptools package configuration. - ``setup.py`` is the setuptools installer used by pip; See above.