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>
105 lines
2.9 KiB
Markdown
105 lines
2.9 KiB
Markdown
<img alt="gem5art logo" src="/gem5art.svg" width=150>
|
|
|
|
# gem5art: Artifact, reproducibility, and testing utilities for gem5
|
|
|
|
|
|
[](https://gem5art.readthedocs.io/en/latest/?badge=latest)
|
|
|
|
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
|
|
|
|
```sh
|
|
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](http://mypy-lang.org/) 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.
|
|
|
|
```sh
|
|
cd artifact
|
|
mypy -p gem5art.artifact
|
|
```
|
|
|
|
```sh
|
|
cd run
|
|
mypy -p gem5art.run
|
|
```
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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](https://packaging.python.org/guides/packaging-namespace-packages/) for more details.
|
|
|
|
## Building for distribution
|
|
|
|
1. Run the setup.py. This must be done in each subdirectory to get the packages to build correctly.
|
|
|
|
```sh
|
|
python setup.py sdist
|
|
```
|
|
|
|
2. Upload to PyPI
|
|
|
|
```sh
|
|
twine upload dist/*
|
|
```
|
|
|
|
These two steps must be completed for each package (e.g., artifact, run, and tasks).
|