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`` in a setuptools specific format. You will generally invoke
  11 it by doing one of the following:
  12
  13 1. ``pip3 install .`` will install these packages to your current
  14    environment. If you are inside a virtual environment, they will
  15    install there. If you are not, it will attempt to install to the
  16    global environment, which is **not recommended**.
  17
  18 2. ``pip3 install --user .`` will install these packages to your user's
  19    local python packages. If you are inside of a virtual environment,
  20    this will fail; you likely want the first invocation above.
  21
  22 If you append the ``-e`` argument, pip will install in "editable" mode;
  23 which installs a version of the package that installs a forwarder
  24 pointing to these files, such that the package always reflects the
  25 latest version in your git 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
  34 See `Installing packages using pip and virtual environments
  35 <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_
  36 for more information.
  37
  38
  39 Files in this directory
  40 -----------------------
  41
  42 - ``qemu/`` Python package source directory.
  43 - ``tests/`` Python package tests directory.
  44 - ``avocado.cfg`` Configuration for the Avocado test-runner.
  45   Used by ``make check`` et al.
  46 - ``Makefile`` provides some common testing/installation invocations.
  47   Try ``make help`` to see available targets.
  48 - ``MANIFEST.in`` is read by python setuptools, it specifies additional files
  49   that should be included by a source distribution.
  50 - ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org.
  51 - ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``.
  52 - ``Pipfile.lock`` is a set of pinned package dependencies that this package
  53   is tested under in our CI suite. It is used by ``make venv-check``.
  54 - ``README.rst`` you are here!
  55 - ``VERSION`` contains the PEP-440 compliant version used to describe
  56   this package; it is referenced by ``setup.cfg``.
  57 - ``setup.cfg`` houses setuptools package configuration.
  58 - ``setup.py`` is the setuptools installer used by pip; See above.