blob: d62e71528d246a3ac19ed45001822be3da04ab82 [file] [log] [blame]
John Snow93128812021-05-27 17:16:56 -04001QEMU Python Tooling
2===================
3
4This directory houses Python tooling used by the QEMU project to build,
5configure, and test QEMU. It is organized by namespace (``qemu``), and
John Snow37094b62022-03-30 13:28:10 -04006then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc).
John Snow93128812021-05-27 17:16:56 -04007
8``setup.py`` is used by ``pip`` to install this tooling to the current
9environment. ``setup.cfg`` provides the packaging configuration used by
John Snow4176dbd2021-06-29 17:43:13 -040010``setup.py``. You will generally invoke it by doing one of the following:
John Snow93128812021-05-27 17:16:56 -040011
121. ``pip3 install .`` will install these packages to your current
13 environment. If you are inside a virtual environment, they will
14 install there. If you are not, it will attempt to install to the
15 global environment, which is **not recommended**.
16
172. ``pip3 install --user .`` will install these packages to your user's
18 local python packages. If you are inside of a virtual environment,
John Snow4176dbd2021-06-29 17:43:13 -040019 this will fail; you want the first invocation above.
John Snow93128812021-05-27 17:16:56 -040020
John Snow4176dbd2021-06-29 17:43:13 -040021If you append the ``--editable`` or ``-e`` argument to either invocation
22above, pip will install in "editable" mode. This installs the package as
23a forwarder ("qemu.egg-link") that points to the source tree. In so
24doing, the installed package always reflects the latest version in your
25source tree.
John Snow93128812021-05-27 17:16:56 -040026
John Snowdbe75f52021-05-27 17:17:10 -040027Installing ".[devel]" instead of "." will additionally pull in required
28packages for testing this package. They are not runtime requirements,
29and are not needed to simply use these libraries.
30
John Snow65603792021-05-27 17:17:12 -040031Running ``make develop`` will pull in all testing dependencies and
32install QEMU in editable mode to the current environment.
John Snow4176dbd2021-06-29 17:43:13 -040033(It is a shortcut for ``pip3 install -e .[devel]``.)
John Snow65603792021-05-27 17:17:12 -040034
John Snow93128812021-05-27 17:16:56 -040035See `Installing packages using pip and virtual environments
36<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_
37for more information.
38
39
John Snowd2ae9422021-06-29 17:43:14 -040040Using these packages without installing them
41--------------------------------------------
42
43These packages may be used without installing them first, by using one
44of two tricks:
45
461. Set your PYTHONPATH environment variable to include this source
47 directory, e.g. ``~/src/qemu/python``. See
48 https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
49
502. Inside a Python script, use ``sys.path`` to forcibly include a search
51 path prior to importing the ``qemu`` namespace. See
52 https://docs.python.org/3/library/sys.html#sys.path
53
54A strong downside to both approaches is that they generally interfere
55with static analysis tools being able to locate and analyze the code
56being imported.
57
58Package installation also normally provides executable console scripts,
59so that tools like ``qmp-shell`` are always available via $PATH. To
60invoke them without installation, you can invoke e.g.:
61
John Snow37094b62022-03-30 13:28:10 -040062``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell``
John Snowd2ae9422021-06-29 17:43:14 -040063
64The mappings between console script name and python module path can be
65found in ``setup.cfg``.
66
67
John Snow93128812021-05-27 17:16:56 -040068Files in this directory
69-----------------------
70
John Snow4176dbd2021-06-29 17:43:13 -040071- ``qemu/`` Python 'qemu' namespace package source directory.
John Snow31622b22021-05-27 17:17:11 -040072- ``tests/`` Python package tests directory.
73- ``avocado.cfg`` Configuration for the Avocado test-runner.
John Snow65603792021-05-27 17:17:12 -040074 Used by ``make check`` et al.
75- ``Makefile`` provides some common testing/installation invocations.
76 Try ``make help`` to see available targets.
John Snoweae4e442021-05-27 17:16:57 -040077- ``MANIFEST.in`` is read by python setuptools, it specifies additional files
78 that should be included by a source distribution.
John Snow93128812021-05-27 17:16:56 -040079- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org.
John Snow93128812021-05-27 17:16:56 -040080- ``README.rst`` you are here!
81- ``VERSION`` contains the PEP-440 compliant version used to describe
82 this package; it is referenced by ``setup.cfg``.
83- ``setup.cfg`` houses setuptools package configuration.
84- ``setup.py`` is the setuptools installer used by pip; See above.