Developer information

Contributions in the form of GitHub pull requests are always welcome. Pull requests will be reviewed carefully, and changes may be requested if they do not adhere to the guidelines below.

Any given pull request should deliver a single small feature or bug fix. Large pieces of new functionality should be broken up into multiple pull requests that incrementally build up the desired functionality, in order to expedite the code review process and minimise disruption for other people working on the codebase. Please discuss large functionality changes with the core development team before starting to work on them, to ensure that the new code will align with the overall direction of SimEng and to avoid duplicated work.

Coding style

New contributions should always adhere to the SimEng coding style. It should generally be possible to glean the coding style from the existing code, but there is also a .clang_format file that helps automate the process of checking the formatting. The recommendation is to run git-clang-format after staging changes to ensure the changes will match the SimEng coding style. Please avoid commits that solely change formatting; use git commit --amend or git commit --fixup to fold formatting changes into the commit that introduced the code.

Code should be well commented. New class and method declarations should use Doxygen /** */ syntax to allow documentation to be generated automatically.

Tests

SimEng has an internal test suite that should be run before any pull request is opened to ensure that there are no regressions. Changes that add new functionality or fix serious bugs should almost always be accompanied by new tests (or additions to existing tests where appropriate).

Further information about the internal test suite and guidance on adding new, or appending to existing, test cases can be found in the Testing section of the developer documentation.

Currently, there are CircleCI and Jenkins configurations that will automatically test that each pull request builds and passes the test suite for multiple compilers before being merged. Those compilers include:

• GCC 7/8/9/10

• ARMCLANG 22

Todo

Define testing processes for accuracy and performance

Contributions

To contribute to the SimEng framework, you should either open a pull request for new code contributions or submit an issue for raising bugs and requesting help.

For pull requests (PR), the description should contain a summary of what work was done within the PR to help the reviewers understand the changes made. Please select one of the labels provided to denote the nature of the PR also.

For issues, in conjunction with choosing a label, the description should outline the problem that has occurred. Additionally, any relevant system or build information should also be included as it may be of use when identifying or solving the problem at hand.

Commit style

Commits should be atomic, with each commit introducing a single, self-contained change.

Please use meaningful commit messages.

Please avoid merge commits; the git history should be linear. Rebase your local work onto the current main branch regularly to keep it up to date.

Directory structure

configs/

Pre-generated config files for specific processors

docs/

Documentation for users and developers

src/include/simeng/

Header files for publicly visible SimEng APIs

src/lib/

Source code for core SimEng library

src/tools/

Source code for SimEng executables

sst/

Source code for SimEng’s integration with the Structural Simulation Toolkit (SST)

test/regression/

Regression test suite covering end-to-end simulator functionality

test/unit/

Unit tests for core SimEng library

Documentation

Significant new features should generally also be accompanied by documentation provided using Sphinx. These docs are built and deployed to a GitHub Pages site.

Building the documentation locally requires a few Sphinx packages, which are simplest to install via pip:

pip install --user Sphinx m2r2 sphinx-rtd-theme

To build the docs, run cmake <path_to_docs_root> from the build directory to generate the associate Makefile followed by make docs. This will generate HTML documentation which can be found in <build_directory>/sphinx/index.html.

Todo

Doxygen documentation.