Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
python: add directory structure README.rst files
Add short readmes to python/, python/qemu/, python/qemu/machine, python/qemu/qmp, and python/qemu/utils that explain the directory hierarchy. These readmes are visible when browsing the source on e.g. gitlab/github and are designed to help new developers/users quickly make sense of the source tree. They are not designed for inclusion in a published manual. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Cleber Rosa <crosa@redhat.com> Message-id: 20210527211715.394144-13-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
- Loading branch information
Showing
5 changed files
with
74 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
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. | ||
- ``PACKAGE.rst`` is used as the README file that is visible on PyPI.org. | ||
- ``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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
QEMU Python Namespace | ||
===================== | ||
|
||
This directory serves as the root of a `Python PEP 420 implicit | ||
namespace package <https://www.python.org/dev/peps/pep-0420/>`_. | ||
|
||
Each directory below is assumed to be an installable Python package that | ||
is available under the ``qemu.<package>`` namespace. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
qemu.machine package | ||
==================== | ||
|
||
This package provides core utilities used for testing and debugging | ||
QEMU. It is used by the iotests, vm tests, acceptance tests, and several | ||
other utilities in the ./scripts directory. It is not a fully-fledged | ||
SDK and it is subject to change at any time. | ||
|
||
See the documentation in ``__init__.py`` for more information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
qemu.qmp package | ||
================ | ||
|
||
This package provides a library used for connecting to and communicating | ||
with QMP servers. It is used extensively by iotests, vm tests, | ||
acceptance tests, and other utilities in the ./scripts directory. It is | ||
not a fully-fledged SDK and is subject to change at any time. | ||
|
||
See the documentation in ``__init__.py`` for more information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
qemu.utils package | ||
================== | ||
|
||
This package provides miscellaneous utilities used for testing and | ||
debugging QEMU. It is used primarily by the vm and acceptance tests. | ||
|
||
See the documentation in ``__init__.py`` for more information. |