]>
Commit | Line | Data |
---|---|---|
93128815 JS |
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 | |
37094b6d | 6 | then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc). |
93128815 JS |
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 | |
4176dbd8 | 10 | ``setup.py``. You will generally invoke it by doing one of the following: |
93128815 JS |
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, | |
4176dbd8 | 19 | this will fail; you want the first invocation above. |
93128815 | 20 | |
4176dbd8 JS |
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. | |
93128815 | 26 | |
dbe75f55 JS |
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 | ||
6560379f JS |
31 | Running ``make develop`` will pull in all testing dependencies and |
32 | install QEMU in editable mode to the current environment. | |
4176dbd8 | 33 | (It is a shortcut for ``pip3 install -e .[devel]``.) |
6560379f | 34 | |
93128815 JS |
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 | ||
d2ae9429 JS |
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 | ||
37094b6d | 62 | ``> PYTHONPATH=~/src/qemu/python python3 -m qemu.qmp.qmp_shell`` |
d2ae9429 JS |
63 | |
64 | The mappings between console script name and python module path can be | |
65 | found in ``setup.cfg``. | |
66 | ||
67 | ||
93128815 JS |
68 | Files in this directory |
69 | ----------------------- | |
70 | ||
4176dbd8 | 71 | - ``qemu/`` Python 'qemu' namespace package source directory. |
31622b2a JS |
72 | - ``tests/`` Python package tests directory. |
73 | - ``avocado.cfg`` Configuration for the Avocado test-runner. | |
6560379f JS |
74 | Used by ``make check`` et al. |
75 | - ``Makefile`` provides some common testing/installation invocations. | |
76 | Try ``make help`` to see available targets. | |
eae4e442 JS |
77 | - ``MANIFEST.in`` is read by python setuptools, it specifies additional files |
78 | that should be included by a source distribution. | |
93128815 | 79 | - ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. |
41c1d81c JS |
80 | - ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``. |
81 | - ``Pipfile.lock`` is a set of pinned package dependencies that this package | |
6f84d726 | 82 | is tested under in our CI suite. It is used by ``make check-pipenv``. |
93128815 JS |
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. |