2021-05-28 05:16:56 +08:00
|
|
|
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
|
2021-06-30 05:43:13 +08:00
|
|
|
``setup.py``. You will generally invoke it by doing one of the following:
|
2021-05-28 05:16:56 +08:00
|
|
|
|
|
|
|
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,
|
2021-06-30 05:43:13 +08:00
|
|
|
this will fail; you want the first invocation above.
|
2021-05-28 05:16:56 +08:00
|
|
|
|
2021-06-30 05:43:13 +08:00
|
|
|
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.
|
2021-05-28 05:16:56 +08:00
|
|
|
|
2021-05-28 05:17:10 +08:00
|
|
|
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.
|
|
|
|
|
2021-05-28 05:17:12 +08:00
|
|
|
Running ``make develop`` will pull in all testing dependencies and
|
|
|
|
install QEMU in editable mode to the current environment.
|
2021-06-30 05:43:13 +08:00
|
|
|
(It is a shortcut for ``pip3 install -e .[devel]``.)
|
2021-05-28 05:17:12 +08:00
|
|
|
|
2021-05-28 05:16:56 +08:00
|
|
|
See `Installing packages using pip and virtual environments
|
|
|
|
<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_
|
|
|
|
for more information.
|
|
|
|
|
|
|
|
|
2021-06-30 05:43:14 +08:00
|
|
|
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``.
|
|
|
|
|
|
|
|
|
2021-05-28 05:16:56 +08:00
|
|
|
Files in this directory
|
|
|
|
-----------------------
|
|
|
|
|
2021-06-30 05:43:13 +08:00
|
|
|
- ``qemu/`` Python 'qemu' namespace package source directory.
|
python: add avocado-framework and tests
Try using avocado to manage our various tests; even though right now
they're only invoking shell scripts and not really running any
python-native code.
Create tests/, and add shell scripts which call out to mypy, flake8,
pylint and isort to enforce the standards in this directory.
Add avocado-framework to the setup.cfg development dependencies, and add
avocado.cfg to store some preferences for how we'd like the test output
to look.
Finally, add avocado-framework to the Pipfile environment and lock the
new dependencies. We are using avocado >= 87.0 here to take advantage of
some features that Cleber has helpfully added to make the test output
here *very* friendly and easy to read for developers that might chance
upon the output in Gitlab CI.
[Note: ALL of the dependencies get updated to the most modern versions
that exist at the time of this writing. No way around it that I have
seen. Not ideal, but so it goes.]
Provided you have the right development dependencies (mypy, flake8,
isort, pylint, and now avocado-framework) You should be able to run
"avocado --config avocado.cfg run tests/" from the python folder to run
all of these linters with the correct arguments.
(A forthcoming commit adds the much easier 'make check'.)
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Cleber Rosa <crosa@redhat.com>
Tested-by: Cleber Rosa <crosa@redhat.com>
Message-id: 20210527211715.394144-28-jsnow@redhat.com
Signed-off-by: John Snow <jsnow@redhat.com>
2021-05-28 05:17:11 +08:00
|
|
|
- ``tests/`` Python package tests directory.
|
|
|
|
- ``avocado.cfg`` Configuration for the Avocado test-runner.
|
2021-05-28 05:17:12 +08:00
|
|
|
Used by ``make check`` et al.
|
|
|
|
- ``Makefile`` provides some common testing/installation invocations.
|
|
|
|
Try ``make help`` to see available targets.
|
2021-05-28 05:16:57 +08:00
|
|
|
- ``MANIFEST.in`` is read by python setuptools, it specifies additional files
|
|
|
|
that should be included by a source distribution.
|
2021-05-28 05:16:56 +08:00
|
|
|
- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org.
|
2021-05-28 05:16:58 +08:00
|
|
|
- ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``.
|
|
|
|
- ``Pipfile.lock`` is a set of pinned package dependencies that this package
|
2021-06-30 05:43:15 +08:00
|
|
|
is tested under in our CI suite. It is used by ``make check-pipenv``.
|
2021-05-28 05:16:56 +08:00
|
|
|
- ``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.
|