Getting Started
pre-commit git hooks
It is recommended to use the pre-commit hook manager to enforce coding conventions, perform static code analysis, and manage MPQC-specific infrastructure. Simply install pre-commit as described here. Then run pre-commit install in the MPQC source directory. File .pre-commit-config.yaml describes the hook configuration used by MPQC; feel free to PR additional hooks.
Each time you try to commit a changeset in a repo in which pre-commit hooks have been installed each hook will be executed on each file added or changed in the changeset. Some hooks are designed to simply prevent nonconformant source code, documentation, infrastructure files, etc. from being committed, whereas other hooks will change the files to make them conformant. In either case, the commit will fail if any changes are needed. You will need to update the changeset (by amending the commit with the changes performed by the hooks and/or any changes you performed manually) and try again.
N.B. Changes in files performed by the pre-commit hooks are not instantly "seen" by the IDE, so it is recommended to manually run git status after a failed commit.
Among the 2 most important use cases for pre-commit hooks are:
- invoking clang-format automatically on each file added or changed in a commit, and
- keeping IDs (versions, git tags, etc.) of dependencies syncronized across MPQC source.
pre-commit git hook: clang-format
This hook runs clang-format to enforce the MPQC code formatting conventions. See Enforcing code style for more information.
pre-commit git hook: dependency-version-update
Whenever the ID of a dependency changes there are several places in the source tree where it needs to be updated: CMake code, documentation, and potentially even in the source code itself. This used to be done manually or even not done at all, i.e. we assumed that the user provided the appropriate version of TiledArray, with only minimal sufficiency checks via the CMake code located in cmake/modules ).
This hook will perform propagate any changes to the dependency IDs automatically whenever the IDs are changed in external/versions.cmake. Thus, whenever dependency IDs need to be changed you should only* change them in this file and then let the hook handle the rest.
versions.cmake file encodes dependency IDs as follows:
When you need to change the required version of Libint you should replace the previous version with the current version and update the current version with the new value, e.g. to update the required version to 2.7.0-beta.5 change these variables to
When you try to commit the updated versions.cmake file the pre-commit hook will update the necessary files with the new Libint version and block the commit. You will need to add the updated files to the index and try again.
N.B. The hook code is located in bin/admin/dependency-versions-update-hook.py. It updates git revision numbers directly, without checking context, since revision numbers have high entropy. Replacement of dependency versions is more error prone and must be done in a context-sensitive manner. Significant changes to the files that include dependency versions (e.g. INSTALL.md) may require changes to the hook script.
Development
Using IDE
Development of any substantial C++ program, like MPQC, should utilize an Integrated Development Environment (IDE). There are many C++ IDEs available; some are free (Eclipse, KDevelop, VS Code, XCode) and some are commercial (CLion). It is also possible to set up "editors" like VIM and Emacs to serve as an IDE. An IDE will make many tasks easier: from navigating and editing the code to interacting with the version control system.
Since MPQC uses CMake as its metabuild system, many IDEs will be able to initialize the project files for MPQC automatically. For this reason MPQC does not include IDE-specific project files.
