1.6.0
|
git
First of all, configure git
with your real name and email address, as already described here:
Note: the settings above must be formatted properly, i.e. names and surname(s) should start with an uppercase letter and be separated by a (single) space character.
Note: please make sure that these settings are consistent on all computers you are using
lifex
on.
Invalid author
errorsOne of the most common problems experienced by lifex
developers is the check indentation
job failing for your branch with the following error.
This is because you probably skipped the git
configuration steps.
The recommended way to solve the issue consists of:
git config [...]
commands reported above;git filter-branch
command. It allows you to batch-process all commits in your branch with a script. Run the below sample script on your branch (filling in real values for the old and new email and name).WARNING: the following procedure rewrites the history of your branch, creating new commit objects along the way! Use it with extreme care and only if you're aware of the side effects. Make sure to create a backup of your branch modifications before proceeding.
Then the remote branch must be overwritten:
If that branch is being used on other machines, the usual git pull origin my_branch_name
won't work to properly fetch the updates. Run the following commands instead.
Here are a few steps to remember before you start to code.
main
branch by running git pull origin main
.Run make doc
from your build folder to generate the documentation to the doc
subdirectory (requires Doxygen
and graphviz
). Please check that make doc
runs without warnings or errors and open /path/to/lifex/build/doc/html/index.html
with a web browser to check that the documentation you wrote is typeset and displayed correctly.
Stall branches, i.e. those that are not ready to merge and show no activity within 4 months, will be archived and deleted.
Archived branches can be fetched and inspected with:
lifex
coding rules.hpp
or .cpp
files).int *
) or the keyword new
. For memory handling use std::unique_ptr
(with std::make_unique
) or std::shared_ptr
(with std::make_shared
), instead.fun(const type& ...)
, unless needed otherwise.MPI
communicator, rank and size, a parallel standard output object, a parallel error output object and a timer output. Additionally, the CoreModel class provides a common interface for parameter handling. If your class needs any of such functionalities it should publicly inherit from Core or CoreModel.declare_parameters()
method should set the verbosity of parameters and sections (as explained in lifex::VerbosityParam and lifex::Core::prm_verbosity_param), e.g.: parse_parameters()
method should parse all parameters declared above, as well as to verify the correctness and meaningfulness of the input parameters (possibly throwing proper exceptions): prm_
and enclosed in a Doxygen
group named Parameters read from file.
.Doxygen
comments should start with a @
rather than with a \
(e.g. @param
).main()
function with lifex
initialization: clang-format
clang-format
is required to automatically indent and properly format the source files. The corresponding style file is /path/to/lifex/.clang-format
.
In order to install clang-format-14.0.0
, run the /path/to/lifex/scripts/format/download_clang-format
script.
This will download a statically-linked binary of clang-format-14.0.0
and install it under /path/to/lifex/scripts/format/clang-14.0.0/bin
.
It is recommended to add the previous folder to your PATH
environment variable, e.g. by adding the following line to your ${HOME}/.bashrc
file (or equivalent).
Note: in case of binary incompatibility with your system, use the
/path/to/lifex/scripts/format/compile_clang-format
script instead.
lifex
coding stylelifex
follows the deal.II coding conventions: please read them carefully before coding./path/to/lifex/scripts/format/static_analysis
from lifex
source directory before any commit to perform a static analysis of the code, relying upon the cppcheck
and cpplint
tools./path/to/lifex/scripts/format/indent_all
from lifex
source directory before any commit to indent all files (or /path/to/lifex/scripts/format/indent
to process only new files or files that have changed since last merge commit). Two equivalent build targets make indent_all
and make indent
are available.cp ./scripts/format/pre-commit .git/hooks/pre-commit && chmod u+x .git/hooks/pre-commit
from your /path/to/lifex
directory.Note: the automatic indentation script makes use of the
clang-format
package.
When a merge request is open, the copyright notice and its formatting are also checked. Please run /path/to/lifex/scripts/format/update_copyright
from lifex
source directory to update the copyright notice.
clang-format
Different plugins and extensions are available to configure your favorite editor for formatting the code you write using clang-format
:
Emacs
:clang-format.el
.~/.emacs
file (toggle comments on one of the two define-key
lines depending on your needs): <TAB>
to format the current selection or file.Vim
(clang-format.py
)Atom
Sublime Text
:Clang Format
via Package Control
.Preferences -> Package Settings -> Clang Format -> Settings - User
) as follows: <CTRL+ALT+A>
to format the current selection or <CTRL+S>
to save and format the current file.Eclipse
VSCode
Different plugins and extensions are available to configure your favorite editor for indenting or highlighting deal.II
parameter (.prm
) files, which are used throughout lifex
:
Emacs
:prm-mode.el
.~/.emacs
file: Vim
Atom
: syntax highlighter, tree viewSublime Text