Developing & Contributing

Common Development-Oriented Tasks

Create Development Environment

Except CMake and other dependencies specified in Install, the development scripts also require other dependencies. Install Pixi, and then execute:

pixi s

Testing

Some individual modules can be tested using CMake’s CTest system. Execute ctest in your building directory to test them.

Run make testsmall or make testsmall-release to run the integration tests using executables produced in make debug and make release.

Profiling

We have ./profile.sh ${PROFILER} to profile the software with profiler ${PROFILER}. Profilers may include:

  • intel-advisor for Intel Advisor. Intel compilers with -mtune=native and -O3 with RelWithDebInfo mode will be used.

  • intel-vtune for Intel VTune Profiler. Intel compilers with -mtune=native and -O3 with RelWithDebInfo mode will be used.

  • valgrind for Valgrind Callgrind. GCC with Debug mode will be used since optimization may produce instructions that are not supported by Valgrind.

  • amd-uprof for AMD uProf. AMD compilers with -mtune=native and -O3 with RelWithDebInfo mode will be used.

Building Documentations

Create the development environment and make the documentation through:

make doc
make doc PYTHON=python SHELL=bash # under Windows

And the built documentations (HTML and PDF) should be in doc/sphinx.d/_build/html and doc/sphinx.d/_build/latex respectively. Note that for PDF output, you may need latexmk and a working up-to-date LaTeX distribution (e.g., TeXLive, MiKTeX, MacTeX) installed.

Release Cycle

  • Feature freeze: All new features merged into the devel branch.

  • Code freeze: All production code changes (including bug fixes) merged into the devel branch. Run make fmt to format the code. Ensure that the integration test passes.

  • Integration test: make testbuild and make testbuild-mpi are executed using GCC, pure LLVM/Clang, and Intel OneAPI C++/DPC++ toolchain to ensure compatibility. Ensure make packing passes without errors.

  • Documentation freeze: All documentation changes merged into the devel branch. Note:

    • Update News.md.

    • Update version number in CMakeLists.txt.

    • Ensure make cleandoc passes without errors.

  • Release: The devel branch is merged into the main branch, tagged with a new version number.

  • Generate artifacts: Run make packing and make cleandoc.

Get Engaged

Issues

You’re welcome to submit issues on GitHub if you’ve encountered any problems while using this software. You’re recommended to use the bug report templates to help us better understand your problems. You may also submit issues if you’re unclear about the docs or have some ideas for improving the software itself.

Pull Requests (PRs)

You’re welcome to send pull requests (PRs) to this project using the standard fork-and-pull-request workflow. However, please send an issue first to discuss the changes you’re going to make (except spelling & punctuation & grammar issues). Otherwise, we may not be able to accept your PR.

Before you send a PR, please make sure that:

  • You’ve run make fmt to format the code.

  • All CTest passes.

  • make clean testsmall-release testsmall-release-mpi passes. This test usually requires 6 to 8 minutes.

  • make clean testsmall testsmall-mpi passes. This test usually requires 12 to 18 minutes. Here, the additional tests that are not enabled in release mode will be activated.

  • make testbuild testbuild-mpi passes. This test usually requires 1 to 2 hours.

  • make testbuild-small testbuild-small-mpi passes. This test usually requires 4 to 6 hours.

You may also:

  • Use Valgrind to check for memory leaks.

  • Run the profilers.

Miscellaneous Developer-Oriented Documentation