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

1. Run the setup.py. This must be done in each subdirectory to get the packages to build correctly.

python setup.py sdist

2. Upload to PyPI

twine upload dist/*

These two steps must be completed for each package (e.g., artifact, run, and tasks).