7cdf8c00f8
gem5art is a utility to help manage the artifacts used in gem5 experiments, the output from those experiments, and running the experiments in parallel (artifacts, run, and tasks packages respectively). The current documentation can be found on readthedocs [1], but we are planning on migrating this to the gem5 website very soon [2]. More information on the motivation and design was discussed at the gem5 workshop last summer. See the blog post [3] for more details. The current version (v1.3.1) is already deployed on PyPI, and you can install it with `pip install gem5art-artifact gem5art-run gem5art-tasks` Once this is merged, we will update the PyPI version to match the version in gem5 (v1.4.0). The only differences are mostly documentation based (pointers to the documentation and source), but we have also updated the style to strictly match PEP8 with black [4]. gem5art is a *utility* to use with gem5. So, we expect that the versioning and release schedule will not necessarily match gem5's (hence a separate versioning structure and separate RELEASE-NOTES, etc.). [1]: https://gem5art.readthedocs.io/en/latest/ [2]: https://www.gem5.org/documentation/gem5art [3]: http://www.gem5.org/2020/05/26/gem5art.html [4]: https://github.com/psf/black Change-Id: Ic8af63edf0cb7df4693a46413f7278a3e8ac6846 Signed-off-by: Jason Lowe-Power <jason@lowepower.com> Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/42121 Reviewed-by: Daniel Carvalho <odanrc@yahoo.com.br> Reviewed-by: Bobby R. Bruce <bbruce@ucdavis.edu> Reviewed-by: Ayaz Akram <yazakram@ucdavis.edu> Reviewed-by: Jason Lowe-Power <power.jg@gmail.com> Maintainer: Jason Lowe-Power <power.jg@gmail.com> Tested-by: kokoro <noreply+kokoro@google.com>
gem5art: Artifact, reproducibility, and testing utilities for gem5
See http://www.gem5.org/documentation/gem5art for detailed documentation.
Installing gem5art
To install gem5art, simply use pip. We suggest creating a virtual environment first. Note that gem5art requires Python 3, so be sure to use a Python 3 interpreter when creating the virtual environment
virtualenv -p python3
pip install gem5art-artifact gem5art-run gem5art-tasks
It's not required to install all of the gem5art utilities (e.g., you can skip gem5art-tasks if you don't want to use the celery job server).
Running the tests
Below describes how to run the tests locally before uploading your changes.
mypy: Python static analysis
mypy is a static type checker for Python. By annotating the code with types and using a static type checker, we can have many of the benefits of a compiled language, with the benefits of Python! Before contributing any code, please add type annotations and run the type checker.
The type checker must be run for each package separately.
cd artifact
mypy -p gem5art.artifact
cd run
mypy -p gem5art.run
cd tasks
mypy -p gem5art.tasks
You should see something like the following output:
Success: no issues found in 3 source files
If you see 0 source files, then it's mostly likely that mypy has been run in the wrong directory.
If there are problems with imports, you may need to add # type: ignore after the import statement if there are third party packages without type annotations.
Running the unit tests
We currently only have a small number of unit tests. Although, we are working on adding more!
To run the unit tests, use the Python unittest module.
python -m unittest
You must run this in each package's subdirectory.
The output should be something like the following:
...
----------------------------------------------------------------------
Ran 3 tests in 0.141s
OK
If you instead see Ran 0 tests, then most likely you are in the wrong directory.
Directory structure
The directory structure is a little strange so we can distribute each Python package separately. However, they are all part of the gem5art namespace. See the Python namespace documentation for more details.
Building for distribution
- Run the setup.py. This must be done in each subdirectory to get the packages to build correctly.
python setup.py sdist
- Upload to PyPI
twine upload dist/*
These two steps must be completed for each package (e.g., artifact, run, and tasks).