python: update README.rst to reflect qemu.qmp's removal
It is no longer simply possible to just use this directory as if it were an installed package now that it has dependencies, so update the README to reflect this. Reviewed-by: Thomas Huth <thuth@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20260218213416.674483-20-jsnow@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com>
John Snow committed
Feb 18, 2026 at 16:34 UTC
c676f6cd7867d37fd9a133f580bad0a934f7465c
1 file changed
+45
-7
python/README.rst
+45
-7
@@ -3,7 +3,17 @@ QEMU Python Tooling
3
4
This directory houses Python tooling used by the QEMU project to build,
5
configure, and test QEMU. It is organized by namespace (``qemu``), and
6
-then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc).
6
+then by package (e.g. ``qemu/machine``, ``qemu/utils``, etc).
7
+
8
+These tools and libraries are installed to the QEMU configure-time
9
+Python virtual environment by default (see qemu.git/pythondeps.toml
10
+"tooling" group), and are available for use by any Python script
11
+executed by the build system. To have these libraries available for
12
+manual invocations of scripts, use of the "run" script in your build
13
+directory is recommended.
14
+
15
+General structure
16
+-----------------
17
18
``setup.py`` is used by ``pip`` to install this tooling to the current
19
environment. ``setup.cfg`` provides the packaging configuration used by
@@ -20,9 +30,9 @@ environment. ``setup.cfg`` provides the packaging configuration used by
30
31
If you append the ``--editable`` or ``-e`` argument to either invocation
32
above, pip will install in "editable" mode. This installs the package as
23
-a forwarder ("qemu.egg-link") that points to the source tree. In so
24
-doing, the installed package always reflects the latest version in your
25
-source tree.
33
+a forwarder that points to the source tree. In so doing, the installed
34
+package always reflects the latest version in your source tree. This is
35
+the mode used to install these packages at configure time.
36
37
Installing ".[devel]" instead of "." will additionally pull in required
38
packages for testing this package. They are not runtime requirements,
@@ -40,8 +50,18 @@ for more information.
50
Using these packages without installing them
51
--------------------------------------------
52
43
-These packages may be used without installing them first, by using one
44
-of two tricks:
53
+It is no longer recommended to try to use these packages without
54
+installing them to a virtual environment, but depending on your use
55
+case, it may still be possible to do.
56
+
57
+The "qemu.qmp" library is now hosted outside of the qemu.git repository,
58
+and the "qemu.machine" library that remains in-tree here has qemu.qmp as
59
+a dependency. It is possible to install "qemu.qmp" independently and
60
+then use the rest of these packages without installing them, but be
61
+advised that if future dependencies are introduced, bypassing the
62
+installation phase may introduce breakages to your script in the future.
63
+
64
+That said, you can use these packages without installing them by either:
65
66
1. Set your PYTHONPATH environment variable to include this source
67
directory, e.g. ``~/src/qemu/python``. See
@@ -61,8 +81,26 @@ invoke them without installation, you can invoke e.g.:
81
82
``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
83
84
+**It is strongly advised to just use the configure-time venv instead.**
85
+After running configure, simply use the run script available in the QEMU
86
+build directory:
87
+
88
+``> $builddir/run qmp-shell``
89
+
90
The mappings between console script name and python module path can be
65
-found in ``setup.cfg``.
91
+found in ``setup.cfg``, but the console scripts available are listed
92
+here for reference:
93
+
94
+* ``qemu-ga-client``
95
+* ``qmp-shell``
96
+* ``qmp-shell-wrap``
97
+* ``qmp-tui`` (prototype urwid interface for async QMP)
98
+* ``qom``
99
+* ``qom-fuse`` (requires fusepy to be installed!)
100
+* ``qom-get``
101
+* ``qom-list``
102
+* ``qom-set``
103
+* ``qom-tree``
104
105
106
Files in this directory