41c1d81cf2
pipenv is a tool used for managing virtual environments with pinned, explicit dependencies. It is used for precisely recreating python virtual environments. pipenv uses two files to do this: (1) Pipfile, which is similar in purpose and scope to what setup.cfg lists. It specifies the requisite minimum to get a functional environment for using this package. (2) Pipfile.lock, which is similar in purpose to `pip freeze > requirements.txt`. It specifies a canonical virtual environment used for deployment or testing. This ensures that all users have repeatable results. The primary benefit of using this tool is to ensure *rock solid* repeatable CI results with a known set of packages. Although I endeavor to support as many versions as I can, the fluid nature of the Python toolchain often means tailoring code for fairly specific versions. Note that pipenv is *not* required to install or use this module; this is purely for the sake of repeatable testing by CI or developers. Here, a "blank" pipfile is added with no dependencies, but specifies Python 3.6 for the virtual environment. Pipfile will specify our version minimums, while Pipfile.lock specifies an exact loadout of packages that were known to operate correctly. This latter file provides the real value for easy setup of container images and CI environments. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-id: 20210527211715.394144-15-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
47 lines
2.1 KiB
ReStructuredText
47 lines
2.1 KiB
ReStructuredText
QEMU Python Tooling
|
|
===================
|
|
|
|
This directory houses Python tooling used by the QEMU project to build,
|
|
configure, and test QEMU. It is organized by namespace (``qemu``), and
|
|
then by package (e.g. ``qemu/machine``, ``qemu/qmp``, etc).
|
|
|
|
``setup.py`` is used by ``pip`` to install this tooling to the current
|
|
environment. ``setup.cfg`` provides the packaging configuration used by
|
|
``setup.py`` in a setuptools specific format. You will generally invoke
|
|
it by doing one of the following:
|
|
|
|
1. ``pip3 install .`` will install these packages to your current
|
|
environment. If you are inside a virtual environment, they will
|
|
install there. If you are not, it will attempt to install to the
|
|
global environment, which is **not recommended**.
|
|
|
|
2. ``pip3 install --user .`` will install these packages to your user's
|
|
local python packages. If you are inside of a virtual environment,
|
|
this will fail; you likely want the first invocation above.
|
|
|
|
If you append the ``-e`` argument, pip will install in "editable" mode;
|
|
which installs a version of the package that installs a forwarder
|
|
pointing to these files, such that the package always reflects the
|
|
latest version in your git tree.
|
|
|
|
See `Installing packages using pip and virtual environments
|
|
<https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/>`_
|
|
for more information.
|
|
|
|
|
|
Files in this directory
|
|
-----------------------
|
|
|
|
- ``qemu/`` Python package source directory.
|
|
- ``MANIFEST.in`` is read by python setuptools, it specifies additional files
|
|
that should be included by a source distribution.
|
|
- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org.
|
|
- ``Pipfile`` is used by Pipenv to generate ``Pipfile.lock``.
|
|
- ``Pipfile.lock`` is a set of pinned package dependencies that this package
|
|
is tested under in our CI suite. It is used by ``make venv-check``.
|
|
- ``README.rst`` you are here!
|
|
- ``VERSION`` contains the PEP-440 compliant version used to describe
|
|
this package; it is referenced by ``setup.cfg``.
|
|
- ``setup.cfg`` houses setuptools package configuration.
|
|
- ``setup.py`` is the setuptools installer used by pip; See above.
|