python/README.rst

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