Skip to content

Code development

Please follow these guidelines when developing new code for MPTRAC.

Compilation

To remove old binaries, backup files, etc., and to clean up the source code directory:

    make clean

For faster compilation, you can use parallel compilation with make:

    make -j

To compile a specific binary (e.g., trac):

    make trac

You can change Makefile variables at the command line:

    make DEFINES="-DNP=100000" GPU=1 STATIC=0

Testing

Always run the full test suite to verify your code changes:

    make check

Do not run tests in parallel (i.e., avoid using the -j option with make check), as this may cause test failures to be missed.

You can run only selected tests, e.g.:

    make trac_test

If a test fails, please carefully compare the test results with the reference data. The Linux tool xxdiff can be used to compare test data and reference data number by number. The graphing utility gnuplot can be used to visualize any differences. The reference data of a test should only be updated if the new test results are considered correct.

Static code analysis

You can use static code analysis to automatically detect potential problems in the code:

    make cppcheck
    make lizard

Coverage testing

You can perform a coverage analysis to determine which parts of the code are covered by tests:

    make COV=1
    make coverage

If you find that parts of the code are not covered by the coverage analysis, please consider adding a new test.

Automated testing and code analysis

After committing revised code to the GitHub repository, please check the GitHub Actions page to see if the automated tests were successfully passed.

Please also check the Codacy and Codecov websites for test results.

Please check the nightly build website to see if the tests passed on the Juelich supercomputers, especially for the GPU code.

Users at the Jülich Supercomputing Centre can also check the test results at the ESM Buildbot.

Code formatting

On Linux, use the indent tool to apply a selected formatting style to the source code:

    make indent

Only use indent if the code has been compiled correctly. You may need to run the indent command 2-3 times to achieve the desired formatting.

Documentation

Please update the README file as needed.

To update the user manual, use:

    make mkdocs

To update the Doxygen manual, use:

    make doxygen

Installation

To copy the executables from the source directory to the DESTDIR directory (default ../bin/):

    make install

To remove the executables from the installation directory:

    make uninstall

To package the current repository state into a zip file, including the compiled binaries, run:

    make dist

Releases

A new release of MPTRAC is usually created every six months.

To create a new release, first define a version tag ("vX.Y") in the local repository:

    gitk

Next, push the local tags to the remote repository on GitHub:

    git push --tags

Get a list of short log messages from the previous to the current version of the code:

    git log v1.1..v1.2 --oneline

Using the log messages, draft a new release on GitHub using the newly created tag.

Check the Zenodo website to publish the new release and to get a DOI.

Use the DOI to submit an entry to the JuSER publication database.

Cleaning the git repository

Always test the following procedures on a fresh copy of the repository!

You can completely remove files from the Git repository using git-filter-repo: https://github.com/newren/git-filter-repo

Analyze the current git repository:

    git filter-repo --analyze
    cd .git/filter-repo/analysis/
    ls

Remove all files except for those that currently exist:

    git ls-files >../paths-i-want.txt
    git filter-repo --paths-from-file ../paths-i-want.txt

Further reading