| Message ID | 20201020193555.1493936-5-jsnow@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | python: create installable package | expand |
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 > tree. > > 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". > +See `Installing packages using pip and virtual environments > +<https://packaging.python.org/guides/installing-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. - Cleber.
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 >> tree. >> >> 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 >> +<https://packaging.python.org/guides/installing-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. > Thanks!
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. + +See `Installing packages using pip and virtual environments +<https://packaging.python.org/guides/installing-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. + +See the documentation in ``__init__.py`` for more information. diff --git a/python/qemu/qmp/README.rst b/python/qemu/qmp/README.rst new file mode 100644 index 0000000000..f35dffe582 --- /dev/null +++ b/python/qemu/qmp/README.rst @@ -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, 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.
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 tree. 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