[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v3 04/15] python: add directory structure README.rst files

From: John Snow
Subject: Re: [PATCH v3 04/15] python: add directory structure README.rst files
Date: Wed, 28 Oct 2020 19:53:32 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.3.1

On 10/28/20 6:05 PM, Cleber Rosa wrote:
On Tue, Oct 20, 2020 at 03:35:44PM -0400, John Snow wrote:
Add short readmes to python/, python/qemu/, python/qemu/machine, and
python/qemu/machine 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

They are not designed for inclusion in a published manual.

Signed-off-by: John Snow <jsnow@redhat.com>
  python/README.rst              | 27 +++++++++++++++++++++++++++
  python/qemu/README.rst         |  8 ++++++++
  python/qemu/machine/README.rst |  9 +++++++++
  python/qemu/qmp/README.rst     |  9 +++++++++
  4 files changed, 53 insertions(+)
  create mode 100644 python/README.rst
  create mode 100644 python/qemu/README.rst
  create mode 100644 python/qemu/machine/README.rst
  create mode 100644 python/qemu/qmp/README.rst

diff --git a/python/README.rst b/python/README.rst
new file mode 100644
index 0000000000..ff40e4c931
--- /dev/null
+++ b/python/README.rst
@@ -0,0 +1,27 @@
+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 (``qemu/machine``, ``qemu/qmp``).
+``setup.py`` is used by ``pip`` to install this tooling to the current
+environment. 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.
+If you amend the ``-e`` argument, pip will install in "editable" mode;
+which installs a version of the package that uses symlinks to these
+files, such that the package always reflects the latest version in your
+git tree.

It actually uses *egg-link* files, which are not what people will
understand by "symlinks".

Ehm, good point; I don't want to *lie* here. I think I do want to avoid the jargon though.

"that installs a forwarder pointing to these files" -- better?

+See `Installing packages using pip and virtual environments
+for more information.
diff --git a/python/qemu/README.rst b/python/qemu/README.rst
new file mode 100644
index 0000000000..31209c80a5
--- /dev/null
+++ b/python/qemu/README.rst
@@ -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.
diff --git a/python/qemu/machine/README.rst b/python/qemu/machine/README.rst
new file mode 100644
index 0000000000..73ad23c501
--- /dev/null
+++ b/python/qemu/machine/README.rst
@@ -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, and several other utilities
+in the ./scripts directory. It is not a fully-fledged SDK and it is
+subject to change at any time.

I'm not sure if you intend to list all test types that use this, but
the acceptance tests also do use them.

Wasn't a conscious omission, but didn't necessarily mean to make it comprehensive; I can add it while fixing the above feedback item too.

- Cleber.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]