| 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 |
| 6 | then by package (e.g. ``qemu/machine``, ``qemu/utils``, etc). |
| 7 | |
| 8 | These tools and libraries are installed to the QEMU configure-time |
| 9 | Python virtual environment by default (see qemu.git/pythondeps.toml |
| 10 | "tooling" group), and are available for use by any Python script |
| 11 | executed by the build system. To have these libraries available for |
| 12 | manual invocations of scripts, use of the "run" script in your build |
| 13 | directory is recommended. |
| 14 | |
| 15 | General structure |
| 16 | ----------------- |
| 17 | |
| 18 | ``setup.py`` is used by ``pip`` to install this tooling to the current |
| 19 | environment. ``setup.cfg`` provides the packaging configuration used by |
| 20 | ``setup.py``. You will generally invoke it by doing one of the following: |
| 21 | |
| 22 | 1. ``pip3 install .`` will install these packages to your current |
| 23 | environment. If you are inside a virtual environment, they will |
| 24 | install there. If you are not, it will attempt to install to the |
| 25 | global environment, which is **not recommended**. |
| 26 | |
| 27 | 2. ``pip3 install --user .`` will install these packages to your user's |
| 28 | local python packages. If you are inside of a virtual environment, |
| 29 | this will fail; you want the first invocation above. |
| 30 | |
| 31 | If you append the ``--editable`` or ``-e`` argument to either invocation |
| 32 | above, pip will install in "editable" mode. This installs the package as |
| 33 | a forwarder that points to the source tree. In so doing, the installed |
| 34 | package always reflects the latest version in your source tree. This is |
| 35 | the mode used to install these packages at configure time. |
| 36 | |
| 37 | Installing ".[devel]" instead of "." will additionally pull in required |
| 38 | packages for testing this package. They are not runtime requirements, |
| 39 | and are not needed to simply use these libraries. |
| 40 | |
| 41 | Running ``make develop`` will pull in all testing dependencies and |
| 42 | install QEMU in editable mode to the current environment. |
| 43 | (It is a shortcut for ``pip3 install -e .[devel]``.) |
| 44 | |
| 45 | See `Installing packages using pip and virtual environments |
| 46 | <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_ |
| 47 | for more information. |
| 48 | |
| 49 | |
| 50 | Using these packages without installing them |
| 51 | -------------------------------------------- |
| 52 | |
| 53 | It is no longer recommended to try to use these packages without |
| 54 | installing them to a virtual environment, but depending on your use |
| 55 | case, it may still be possible to do. |
| 56 | |
| 57 | The "qemu.qmp" library is now hosted outside of the qemu.git repository, |
| 58 | and the "qemu.machine" library that remains in-tree here has qemu.qmp as |
| 59 | a dependency. It is possible to install "qemu.qmp" independently and |
| 60 | then use the rest of these packages without installing them, but be |
| 61 | advised that if future dependencies are introduced, bypassing the |
| 62 | installation phase may introduce breakages to your script in the future. |
| 63 | |
| 64 | That said, you can use these packages without installing them by either: |
| 65 | |
| 66 | 1. Set your PYTHONPATH environment variable to include this source |
| 67 | directory, e.g. ``~/src/qemu/python``. See |
| 68 | https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH |
| 69 | |
| 70 | 2. Inside a Python script, use ``sys.path`` to forcibly include a search |
| 71 | path prior to importing the ``qemu`` namespace. See |
| 72 | https://docs.python.org/3/library/sys.html#sys.path |
| 73 | |
| 74 | A strong downside to both approaches is that they generally interfere |
| 75 | with static analysis tools being able to locate and analyze the code |
| 76 | being imported. |
| 77 | |
| 78 | Package installation also normally provides executable console scripts, |
| 79 | so that tools like ``qmp-shell`` are always available via $PATH. To |
| 80 | invoke them without installation, you can invoke e.g.: |
| 81 | |
| 82 | ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell`` |
| 83 | |
| 84 | **It is strongly advised to just use the configure-time venv instead.** |
| 85 | After running configure, simply use the run script available in the QEMU |
| 86 | build directory: |
| 87 | |
| 88 | ``> $builddir/run qmp-shell`` |
| 89 | |
| 90 | The mappings between console script name and python module path can be |
| 91 | found in ``setup.cfg``, but the console scripts available are listed |
| 92 | here for reference: |
| 93 | |
| 94 | * ``qemu-ga-client`` |
| 95 | * ``qmp-shell`` |
| 96 | * ``qmp-shell-wrap`` |
| 97 | * ``qmp-tui`` (prototype urwid interface for async QMP) |
| 98 | * ``qom`` |
| 99 | * ``qom-fuse`` (requires fusepy to be installed!) |
| 100 | * ``qom-get`` |
| 101 | * ``qom-list`` |
| 102 | * ``qom-set`` |
| 103 | * ``qom-tree`` |
| 104 | |
| 105 | |
| 106 | Files in this directory |
| 107 | ----------------------- |
| 108 | |
| 109 | - ``qemu/`` Python 'qemu' namespace package source directory. |
| 110 | - ``tests/`` Python package tests directory. |
| 111 | - ``Makefile`` provides some common testing/installation invocations. |
| 112 | Try ``make help`` to see available targets. |
| 113 | - ``MANIFEST.in`` is read by python setuptools, it specifies additional files |
| 114 | that should be included by a source distribution. |
| 115 | - ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. |
| 116 | - ``README.rst`` you are here! |
| 117 | - ``VERSION`` contains the PEP-440 compliant version used to describe |
| 118 | this package; it is referenced by ``setup.cfg``. |
| 119 | - ``setup.cfg`` houses setuptools package configuration. |
| 120 | - ``setup.py`` is the setuptools installer used by pip; See above. |