1QEMU 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 6then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc). 7 8``setup.py`` is used by ``pip`` to install this tooling to the current 9environment. ``setup.cfg`` provides the packaging configuration used by 10``setup.py``. You will generally invoke it by doing one of the following: 11 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, 19 this will fail; you want the first invocation above. 20 21If 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. 26 27Installing ".[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 31Running ``make develop`` will pull in all testing dependencies and 32install QEMU in editable mode to the current environment. 33(It is a shortcut for ``pip3 install -e .[devel]``.) 34 35See `Installing packages using pip and virtual environments 36<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_ 37for more information. 38 39 40Using 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 62``> PYTHONPATH=~/src/qemu/python python3 -m qemu.aqmp.qmp_shell`` 63 64The mappings between console script name and python module path can be 65found in ``setup.cfg``. 66 67 68Files in this directory 69----------------------- 70 71- ``qemu/`` Python 'qemu' namespace package source directory. 72- ``tests/`` Python package tests directory. 73- ``avocado.cfg`` Configuration for the Avocado test-runner. 74 Used by ``make check`` et al. 75- ``Makefile`` provides some common testing/installation invocations. 76 Try ``make help`` to see available targets. 77- ``MANIFEST.in`` is read by python setuptools, it specifies additional files 78 that should be included by a source distribution. 79- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. 80- ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``. 81- ``Pipfile.lock`` is a set of pinned package dependencies that this package 82 is tested under in our CI suite. It is used by ``make check-pipenv``. 83- ``README.rst`` you are here! 84- ``VERSION`` contains the PEP-440 compliant version used to describe 85 this package; it is referenced by ``setup.cfg``. 86- ``setup.cfg`` houses setuptools package configuration. 87- ``setup.py`` is the setuptools installer used by pip; See above. 88