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 40Files in this directory 41----------------------- 42 43- ``qemu/`` Python 'qemu' namespace package source directory. 44- ``tests/`` Python package tests directory. 45- ``avocado.cfg`` Configuration for the Avocado test-runner. 46 Used by ``make check`` et al. 47- ``Makefile`` provides some common testing/installation invocations. 48 Try ``make help`` to see available targets. 49- ``MANIFEST.in`` is read by python setuptools, it specifies additional files 50 that should be included by a source distribution. 51- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. 52- ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``. 53- ``Pipfile.lock`` is a set of pinned package dependencies that this package 54 is tested under in our CI suite. It is used by ``make venv-check``. 55- ``README.rst`` you are here! 56- ``VERSION`` contains the PEP-440 compliant version used to describe 57 this package; it is referenced by ``setup.cfg``. 58- ``setup.cfg`` houses setuptools package configuration. 59- ``setup.py`` is the setuptools installer used by pip; See above. 60