John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 1 | QEMU Python Tooling |
| 2 | =================== |
| 3 | |
| 4 | This directory houses Python tooling used by the QEMU project to build, |
| 5 | configure, and test QEMU. It is organized by namespace (``qemu``), and |
John Snow | 37094b6 | 2022-03-30 13:28:10 -0400 | [diff] [blame] | 6 | then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc). |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 7 | |
| 8 | ``setup.py`` is used by ``pip`` to install this tooling to the current |
| 9 | environment. ``setup.cfg`` provides the packaging configuration used by |
John Snow | 4176dbd | 2021-06-29 17:43:13 -0400 | [diff] [blame] | 10 | ``setup.py``. You will generally invoke it by doing one of the following: |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 11 | |
| 12 | 1. ``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 | |
| 17 | 2. ``pip3 install --user .`` will install these packages to your user's |
| 18 | local python packages. If you are inside of a virtual environment, |
John Snow | 4176dbd | 2021-06-29 17:43:13 -0400 | [diff] [blame] | 19 | this will fail; you want the first invocation above. |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 20 | |
John Snow | 4176dbd | 2021-06-29 17:43:13 -0400 | [diff] [blame] | 21 | If you append the ``--editable`` or ``-e`` argument to either invocation |
| 22 | above, pip will install in "editable" mode. This installs the package as |
| 23 | a forwarder ("qemu.egg-link") that points to the source tree. In so |
| 24 | doing, the installed package always reflects the latest version in your |
| 25 | source tree. |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 26 | |
John Snow | dbe75f5 | 2021-05-27 17:17:10 -0400 | [diff] [blame] | 27 | Installing ".[devel]" instead of "." will additionally pull in required |
| 28 | packages for testing this package. They are not runtime requirements, |
| 29 | and are not needed to simply use these libraries. |
| 30 | |
John Snow | 6560379 | 2021-05-27 17:17:12 -0400 | [diff] [blame] | 31 | Running ``make develop`` will pull in all testing dependencies and |
| 32 | install QEMU in editable mode to the current environment. |
John Snow | 4176dbd | 2021-06-29 17:43:13 -0400 | [diff] [blame] | 33 | (It is a shortcut for ``pip3 install -e .[devel]``.) |
John Snow | 6560379 | 2021-05-27 17:17:12 -0400 | [diff] [blame] | 34 | |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 35 | See `Installing packages using pip and virtual environments |
| 36 | <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_ |
| 37 | for more information. |
| 38 | |
| 39 | |
John Snow | d2ae942 | 2021-06-29 17:43:14 -0400 | [diff] [blame] | 40 | Using these packages without installing them |
| 41 | -------------------------------------------- |
| 42 | |
| 43 | These packages may be used without installing them first, by using one |
| 44 | of two tricks: |
| 45 | |
| 46 | 1. 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 | |
| 50 | 2. 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 | |
| 54 | A strong downside to both approaches is that they generally interfere |
| 55 | with static analysis tools being able to locate and analyze the code |
| 56 | being imported. |
| 57 | |
| 58 | Package installation also normally provides executable console scripts, |
| 59 | so that tools like ``qmp-shell`` are always available via $PATH. To |
| 60 | invoke them without installation, you can invoke e.g.: |
| 61 | |
John Snow | 37094b6 | 2022-03-30 13:28:10 -0400 | [diff] [blame] | 62 | ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell`` |
John Snow | d2ae942 | 2021-06-29 17:43:14 -0400 | [diff] [blame] | 63 | |
| 64 | The mappings between console script name and python module path can be |
| 65 | found in ``setup.cfg``. |
| 66 | |
| 67 | |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 68 | Files in this directory |
| 69 | ----------------------- |
| 70 | |
John Snow | 4176dbd | 2021-06-29 17:43:13 -0400 | [diff] [blame] | 71 | - ``qemu/`` Python 'qemu' namespace package source directory. |
John Snow | 31622b2 | 2021-05-27 17:17:11 -0400 | [diff] [blame] | 72 | - ``tests/`` Python package tests directory. |
| 73 | - ``avocado.cfg`` Configuration for the Avocado test-runner. |
John Snow | 6560379 | 2021-05-27 17:17:12 -0400 | [diff] [blame] | 74 | Used by ``make check`` et al. |
| 75 | - ``Makefile`` provides some common testing/installation invocations. |
| 76 | Try ``make help`` to see available targets. |
John Snow | eae4e44 | 2021-05-27 17:16:57 -0400 | [diff] [blame] | 77 | - ``MANIFEST.in`` is read by python setuptools, it specifies additional files |
| 78 | that should be included by a source distribution. |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 79 | - ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. |
John Snow | 9312881 | 2021-05-27 17:16:56 -0400 | [diff] [blame] | 80 | - ``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. |