On 10/28/20 4:13 AM, Thomas Huth wrote:
On 27/10/2020 23.38, John Snow wrote:
Ignore build and package output (build, dist, qemu.egg-info);
effectively these are "in-tree" builds of a kind.
Since we recently moved away from in-tree builds, could these also be made
out-of-tree only?
Thomas
# Summary
This wound up being controversial, so let's go over exactly what
artifacts I have ignored here, and why I have done so. This email gets
long, but please stick with me for at least this first Summary section.
One thing I would like to immediately clear up is that these artifacts
are not related to a "QEMU build" in any way, shape or form; i.e.,
building QEMU does not cause these artifacts to exist.
For clarity: neither "make" nor "make check" from the root nor the build
root will cause any changes to the ./python source tree. These artifacts
come from explicit actions taken during manual testing/development in
the ./python directory.
I use a Makefile in the ./python directory to canonize the expected
invocations for a few common operations I anticipate developers wanting
to take; these actions occur outside of "the QEMU build".
Those actions, and the expected artifacts they create, are:
- Running 'make check' inside ./python; AKA
running 'pytest' (no arguments.)
(.mypy_cache, .pytest_cache, __pycache__, possibly *.pyc)
- Running 'make venv' inside ./python; AKA
running PIPENV_VENV_IN_PROJECT=1 pipenv sync --dev --keep-outdated
(.venv, qemu.egg-info/, build/)
- Running 'make venv-check' inside ./python; AKA
running 'make venv; pipenv run make check'
(All of the above from both categories)
- Running various PyPI distribution commands; not in the Makefile
(e.g. python3 setup.py sdist bdist_wheel)
(build/, dist/)
- Using the Pycharm IDE to edit, run, or test python files:
(.idea/)
While these do not happen during a (QEMU) make/make check, they DO
happen as a result of my gitlab job, which simply does the dumbest
possible thing and navigates to the source ./python directory and runs
"make venv-check".
This was presumed "safe", because the gitlab output is not committed
back into the container, does not affect the subsequent build, and has
its output discarded after the job completes.
Read on below for more detailed information on what each file is, what
creates it, what it's useful for, and why you might come to have these
files in your source tree during development.
# make check
running "make check" here simply invokes "pytest". This causes
.pytest_cache to exist where you ran it. The tests located in tests/
will run mypy (.mypy_cache), flake8, pylint and isort.
The act of running or importing files here may or may not cause
__pycache__ and *.pyc files to exist based on the caller's environment.
All of the files created by running the linter are normal confetti you
might expect to incur from running such programs; i.e. if you run mypy
or pytest separately, of your own volition, you will encounter these
files being made for you.
It is normal and expected for developers to want to run the linters
during development to ensure adherence to the coding standards, so it is
normal and expected to see these files being created in the source tree
-- not during a build, but during development.
We ignore __pycache__ and *.pyc in the root tree too, this is just
extending the concept to more python tooling that may litter the tree.
# make venv
This is an alias for "pipenv sync --dev", which uses the pipenv tool to
actualize a very specific virtual environment based on the contents in
Pipfile.lock.
It normally creates a virtual environment somewhere like:
/home/jsnow/.local/share/virtualenvs/python-Z09Et8eW
but you can configure it to look in $CWD/.venv instead. There are no
other options I am aware of! Your $CWD must include the Pipfile.lock file.
Let's assume that we will want to create a venv in two distinct contexts:
(1) For the purposes of iterative development; as an object we want to
keep long-term (conjured explicitly by the developer), and
(2) For the purposes of a continuous integration check; a build check,
or some other automatic invocation not explicitly conjured by the developer.
For the first, it's okay to store in ~/.local/share/ etc, and it's okay
to store it in the source tree too -- in both cases, you'll have one
venv per source tree. No problem. (And reminder, because this python
virtual environment is tied to the python *source* and has no
relationship whatsoever to a configuration of a QEMU build, a 1:1
relationship from venv:source is OK. We do not need (or want) a 1:1
relationship with configurations.)
For the second, it would be best if we didn't taint the user's
environment. In this case, constraining it to where the the venv was
requested is the best choice available. There are no hooks in this patch
series that will invoke the creation of this venv in the source tree
when a user types "make" or "make check" in their root or their build root.
So: ignoring .venv is for the sake of the python developer, but does not
imply this file will exist for those not developing python.
Lastly, The qemu.egg-info file is an artifact of installing the source
package itself into the virtual environment in "editable" mode. This is
an expected artifact of development, but won't occur during a build.
A trick I explicitly support is `cd ~/src/qemu/python; pip install -e .`
-- this installs a python package to your current environment (wherever
it is; It can be one of your explicit creation) that simply installs
symlinks to your git source tree -- this is a feature -- so that while
updating the python source, your installed package always reflects the
latest version without having to "re-install" the package to test it.
Therefore, it's reasonable and expected to have a 'qemu.egg-info/'
folder in your source tree: it means you've installed this package
somewhere. This doesn't happen by accident!
# make venv-check
This is a hook that runs both things: it creates a venv, then runs the
tests inside that venv. It will create all of the confetti from both
above processes.
If you made a build directory and configured QEMU, the configuration
script will have copied the python directory into the build directory.
You can run "make venv-check" from in there to avoid disturbing your
source tree.
However, since running configure isn't necessary to check the python
code, you can just run it straight from the source tree.
# .idea
This is the pycharm IDE folder for managing project settings. If you use
pycharm to edit the Python code (and I encourage you to try if you wish
to contribute Python code), you will see this directory created.
# build
This directory will be created as a result of engaging with pipenv.
It will show up under any of the following:
pipenv sync
pipenv lock
pipenv install
I believe this happens as a side-effect of installing the qemu package
in editable mode, however:
`pip install -e .` does not create such a directory. I'm not sure which
step is creating it and what it's used for, to be crassly honest. It
appears safe to delete afterwards.
Actually, you can even create a read-only build directory owned by root,
and pipenv will ... work the same, and never write into that directory.
What's going on? Someone else's bug, I guess.
(It also shows up if you were to type "python3 setup.py bdist_wheel",
which is a packaging step you would only type if you were preparing to
build and package this code to upload it to PyPI.)
# dist
Only shows up if you type 'python3 setup.py sdist'. No reason to do this
unless you're building a source distribution of the Python package alone
to upload to somewhere else. Intentional developer action.
So ... long story short: I think these files are legitimate; I am sorry
to have alarmed people by calling it an "in-tree build", they're not
related to the QEMU build.
--js