193128815SJohn SnowQEMU Python Tooling 293128815SJohn Snow=================== 393128815SJohn Snow 493128815SJohn SnowThis directory houses Python tooling used by the QEMU project to build, 593128815SJohn Snowconfigure, and test QEMU. It is organized by namespace (``qemu``), and 693128815SJohn Snowthen by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc). 793128815SJohn Snow 893128815SJohn Snow``setup.py`` is used by ``pip`` to install this tooling to the current 993128815SJohn Snowenvironment. ``setup.cfg`` provides the packaging configuration used by 104176dbd8SJohn Snow``setup.py``. You will generally invoke it by doing one of the following: 1193128815SJohn Snow 1293128815SJohn Snow1. ``pip3 install .`` will install these packages to your current 1393128815SJohn Snow environment. If you are inside a virtual environment, they will 1493128815SJohn Snow install there. If you are not, it will attempt to install to the 1593128815SJohn Snow global environment, which is **not recommended**. 1693128815SJohn Snow 1793128815SJohn Snow2. ``pip3 install --user .`` will install these packages to your user's 1893128815SJohn Snow local python packages. If you are inside of a virtual environment, 194176dbd8SJohn Snow this will fail; you want the first invocation above. 2093128815SJohn Snow 214176dbd8SJohn SnowIf you append the ``--editable`` or ``-e`` argument to either invocation 224176dbd8SJohn Snowabove, pip will install in "editable" mode. This installs the package as 234176dbd8SJohn Snowa forwarder ("qemu.egg-link") that points to the source tree. In so 244176dbd8SJohn Snowdoing, the installed package always reflects the latest version in your 254176dbd8SJohn Snowsource tree. 2693128815SJohn Snow 27dbe75f55SJohn SnowInstalling ".[devel]" instead of "." will additionally pull in required 28dbe75f55SJohn Snowpackages for testing this package. They are not runtime requirements, 29dbe75f55SJohn Snowand are not needed to simply use these libraries. 30dbe75f55SJohn Snow 316560379fSJohn SnowRunning ``make develop`` will pull in all testing dependencies and 326560379fSJohn Snowinstall QEMU in editable mode to the current environment. 334176dbd8SJohn Snow(It is a shortcut for ``pip3 install -e .[devel]``.) 346560379fSJohn Snow 3593128815SJohn SnowSee `Installing packages using pip and virtual environments 3693128815SJohn Snow<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_ 3793128815SJohn Snowfor more information. 3893128815SJohn Snow 3993128815SJohn Snow 40*d2ae9429SJohn SnowUsing these packages without installing them 41*d2ae9429SJohn Snow-------------------------------------------- 42*d2ae9429SJohn Snow 43*d2ae9429SJohn SnowThese packages may be used without installing them first, by using one 44*d2ae9429SJohn Snowof two tricks: 45*d2ae9429SJohn Snow 46*d2ae9429SJohn Snow1. Set your PYTHONPATH environment variable to include this source 47*d2ae9429SJohn Snow directory, e.g. ``~/src/qemu/python``. See 48*d2ae9429SJohn Snow https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH 49*d2ae9429SJohn Snow 50*d2ae9429SJohn Snow2. Inside a Python script, use ``sys.path`` to forcibly include a search 51*d2ae9429SJohn Snow path prior to importing the ``qemu`` namespace. See 52*d2ae9429SJohn Snow https://docs.python.org/3/library/sys.html#sys.path 53*d2ae9429SJohn Snow 54*d2ae9429SJohn SnowA strong downside to both approaches is that they generally interfere 55*d2ae9429SJohn Snowwith static analysis tools being able to locate and analyze the code 56*d2ae9429SJohn Snowbeing imported. 57*d2ae9429SJohn Snow 58*d2ae9429SJohn SnowPackage installation also normally provides executable console scripts, 59*d2ae9429SJohn Snowso that tools like ``qmp-shell`` are always available via $PATH. To 60*d2ae9429SJohn Snowinvoke them without installation, you can invoke e.g.: 61*d2ae9429SJohn Snow 62*d2ae9429SJohn Snow``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell`` 63*d2ae9429SJohn Snow 64*d2ae9429SJohn SnowThe mappings between console script name and python module path can be 65*d2ae9429SJohn Snowfound in ``setup.cfg``. 66*d2ae9429SJohn Snow 67*d2ae9429SJohn Snow 6893128815SJohn SnowFiles in this directory 6993128815SJohn Snow----------------------- 7093128815SJohn Snow 714176dbd8SJohn Snow- ``qemu/`` Python 'qemu' namespace package source directory. 7231622b2aSJohn Snow- ``tests/`` Python package tests directory. 7331622b2aSJohn Snow- ``avocado.cfg`` Configuration for the Avocado test-runner. 746560379fSJohn Snow Used by ``make check`` et al. 756560379fSJohn Snow- ``Makefile`` provides some common testing/installation invocations. 766560379fSJohn Snow Try ``make help`` to see available targets. 77eae4e442SJohn Snow- ``MANIFEST.in`` is read by python setuptools, it specifies additional files 78eae4e442SJohn Snow that should be included by a source distribution. 7993128815SJohn Snow- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. 8041c1d81cSJohn Snow- ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``. 8141c1d81cSJohn Snow- ``Pipfile.lock`` is a set of pinned package dependencies that this package 8241c1d81cSJohn Snow is tested under in our CI suite. It is used by ``make venv-check``. 8393128815SJohn Snow- ``README.rst`` you are here! 8493128815SJohn Snow- ``VERSION`` contains the PEP-440 compliant version used to describe 8593128815SJohn Snow this package; it is referenced by ``setup.cfg``. 8693128815SJohn Snow- ``setup.cfg`` houses setuptools package configuration. 8793128815SJohn Snow- ``setup.py`` is the setuptools installer used by pip; See above. 88