Skip to content

WORKFLOW.md

Latest commit

 

History

History
58 lines (42 loc) · 5.68 KB

WORKFLOW.md

File metadata and controls

58 lines (42 loc) · 5.68 KB

Naming Conventions

  • Variables should use camel casing
  • Compile time constants should use capital casing
  • Member variables should be suffixed with _m

Math

Mathematical constants should be obtained from Kokkos::numbers (moved out of experimental in Kokkos 4). Any instance of a mathematical function in host-only code should use symbols from the standard library, e.g. std::sqrt. Any instances occurring in device-code or code that might be run on a device (such as those marked with KOKKOS_INLINE_FUNCTION) should use the symbols from Kokkos, e.g. Kokkos::sqrt, to ensure performance and portability on GPUs.

Other Formatting Conventions

IPPL uses clang-format for automatic formatting. For explanations of the available settings, refer to the clang documentation. IPPL's settings are available in the repository root. For more information about the formatting, refer to the workflow below.

Automatic Code Formatting

IPPL uses clang-format to automatically format the codebase to maintain a consistent code style. When modifying IPPL, the changes can be reformatted automatically by using a git hook. A git hook is a script that is executed by git before completing certain actions. The hooks/ top-level directory includes a pre-commit script and a shell script for setting up the git hook. Git hooks are stored in .git/hooks; the shell script creates a symbolic link in .git/hooks pointing to the pre-commit script, effectively creating a pre-commit hook for the local repository. A pre-commit hook is run automatically before every commit.

The provided script automatically runs clang-format on all files with staged changes, i.e. files that have been added to the commit, then re-stages these files to include the reformatted changes in the commit. The result is that, even if the code is not properly formatted when you run git commit, the code is automatically reformatted before the commit is created, so all committed code will always have the proper formatting.

Caveats

  • clang-format must be available to use the automatic formatting; Beware of the order in which modules are loaded, as the presence of clang can affect project configuration. If you newly configure a project and clang has higher priority in your $PATH than gcc (or another desired compiler), the project may become configured to compile with clang instead of your desired compiler. In general, it is advisable to only load the clang module once the project is configured, or to load clang before your desired compiler such that it has lower priority in your $PATH.
  • To avoid misconfigurations due to the Clang module, a simple workaround is to create a symbolic link to clang-format in a folder that is always in your $PATH. To locate clang-format, run which clang-format while the module is loaded. Create a symbolic link with ln -s "$(which clang-format)" /path/to/link, where /path/to is included in your $PATH. Conventional paths include ~/.local/bin (this folder may need to be created). If this is not already in your $PATH, you can modify your ~/.bash_profile to add this to your path: PATH=$PATH:~/.local/bin.
  • The pre-commit script always reformats and re-stages entire files. If you used git add -i to only stage a subset of the changes in a file, the pre-commit script will render the interactive staging moot by staging the entire file. To prevent this, use the --no-verify flag when committing; this makes git skip the pre-commit script. Note that this means that your changes will not be reformatted before committing. If you would like to commit only a subset of the changes made to a file but still want to run the formatter, you can stash the changes you don't want to commit by stashing in patch mode (git stash save -p) and shelving the other changes. After committing, run git stash pop to restore the uncommitted changes.
  • The pre-commit script only reformats staged files. It does not affect unstaged or unmodified files. To reformat unchanged files, you will have to run the formatter manually. This is also true if you stage a subset of modified files; the staged files will be reformatted, but unstaged files will not be reformatted even if they have modifications.

Refer to our git introduction if the git-related terms on this page are unclear.

Git brief introduction

For those in need of a refresher or an introduction, here is a glossary of Git terms relevant to the workflow caveats, as well as some useful commands and flags:

  • A file is tracked if it is under version control. A file that has never been committed is untracked and will show up under "untracked files" when running git status.
  • Files whose names match patterns in a .gitignore file will be ignored by git and do not show up as untracked. To start tracking an ignored file, use the -f flag when staging it.
  • The working tree is the current state of the repository, excluding untracked files. Changes to the working tree are shown by git diff.
  • Before committing, changes have to be staged. This is done by running git add to stage the changes that need to be committed. You can view the staged changes using git diff --staged. This represents the changes that will be recorded by running git commit.
  • You can stage any subset of the changes to the working tree. You can also stage only a subset of changes to a file by using interactive staging with git add -i and choosing "patch" at the interactive prompt.
  • A commit is a set of changes that constitute a fixed point in the repository history. Running git commit creates a new commit out of the staged changes. Unstaged changes are untouched.