diff --git a/.travis.yml b/.travis.yml index 86f1ae5..6f1eac5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,22 +1,32 @@ language: bash +branches: + only: + - master script: echo "Nothing to do" after_success: | set -e curl -L https://github.com/github/hub/releases/download/v2.6.0/hub-linux-amd64-2.6.0.tgz | tar xz MESSAGE="Align Clang Format to upstream" - REPOS=Common + REPOS="Common ReadoutCard AliceO2 InfoLogger QualityControl Monitoring Readout Configuration" ORG=${TRAVIS_REPO_SLUG%%/*} - for REPO in $REPOS; do - git clone git://github.com/$ORG/$REPO - cp .clang-format $REPO - pushd $REPO - git remote - git config user.email ${TRAVIS_SECURE_EMAIL} - git config user.name ${TRAVIS_SECURE_USER} - git add .clang-format - git commit -m "${MESSAGE}" - git push "https://${TRAVIS_SECURE_TOKEN_NAME}@github.com/$ORG/$REPO" HEAD:refs/heads/coding-guidelines-update > /dev/null 2>&1 - GITHUB_TOKEN=${TRAVIS_SECURE_TOKEN_NAME} ../hub-linux-amd64-2.6.0/bin/hub pull-request -h coding-guidelines-update -b master -m "Coding Guidelines update of $(date +%Y-%m-%d)" - popd - done + # We only build if the change involves .clang-format or .travis.yml. The latter + # is to make sure that when we add new repositories we resync. + if git diff --name-only $TRAVIS_COMMIT_RANGE | grep -e "\(.clang-format\|.travis.yml\)" ; then + for REPO in $REPOS; do + echo Processing $REPO + git clone git://github.com/$ORG/$REPO + cp .clang-format $REPO + pushd $REPO + git config user.email ${TRAVIS_SECURE_EMAIL} + git config user.name ${TRAVIS_SECURE_USER} + if git add .clang-format && git commit -m "${MESSAGE}"; then + git push "https://${TRAVIS_SECURE_TOKEN_NAME}@github.com/$ORG/$REPO" HEAD:refs/heads/coding-guidelines-update -f > /dev/null 2>&1 + GITHUB_TOKEN=${TRAVIS_SECURE_TOKEN_NAME} ../hub-linux-amd64-2.6.0/bin/hub pull-request -h coding-guidelines-update -b master -m "Coding Guidelines update of $(date +%Y-%m-%d)" || true + fi + popd + done + fi +branches: + only: + - master diff --git a/README.md b/README.md index a637915..a15e310 100644 --- a/README.md +++ b/README.md @@ -9,17 +9,111 @@ Coding guidelines for the ALICE O2 project. * [Naming and formatting conventions](https://rawgit.com/AliceO2Group/CodingGuidelines/master/naming_formatting.html) * [Comments guidelines](https://rawgit.com/AliceO2Group/CodingGuidelines/master/comments_guidelines.html) -### ClangFormat +### Formatting tool +The ALICE O2 projects use `clang-format` to push for a common code formatting. The rules are defined in +the `clang-format` configuration file in this repository (which is propagated to other AliceO2Group repositories). With an adiabatic +approach, all changes have to follow the formatting rules. A script, described below, can be +used to integrate the formatting into `git` and suggest formatting only for +changed lines. -ClangFormat can be used to format your source code. See instructions in the [AliceO2 repo README](https://github.com/AliceO2Group/AliceO2/). +#### Install `clang-format` and git integration + +Note : The installation of clang using aliBuild is not necessary on Mac. + +1. Build clang (to be done once) +```bash +aliBuild build --defaults o2 Clang +``` +2. Load clang and clang-format +```bash +alienv enter Clang/latest +``` +3. Install git-clang-format +```bash +cd $HOME +mkdir -p bin +cd bin +wget https://raw.githubusercontent.com/llvm/llvm-project/main/clang/tools/clang-format/git-clang-format +chmod u+x git-clang-format +``` + +#### Check commits' formatting +`git clang-format` invokes `clang-format` on the changes in current files +or a specific commit. E.g. for the last commit +``` +git clang-format HEAD~1 +``` + +Or for all commits done with respect to the remote branch state +``` +git clang-format origin/dev +``` + +#### Check files' formatting + +The commands below rely on the [.clang-format](.clang-format) file located in one of the parent +directories of the source files. + +Please note that for technical reasons, there are slight differences between `clang-format` and `git-clang-format` (see above). All pull requests are checked with `git-clang-format` as described in the previous bullet. Thus make sure that before pushing code, correct the formatting with `git-clang-format`. The instructions for `clang-format` are left here only for reference. + +Show correctly formatted version of a file : +``` +clang-format -style=file SOURCEFILE +``` + +Directly apply the style to a file : +``` +clang-format -style=file -i SOURCEFILE +``` + +Apply the style to all the source and header files in a directory (recursive) : + +``` +find . -iname "*.h" -o -iname "*.cpp" | xargs clang-format -style=file -i +``` + +Display what needs to be fixed in a file : +``` +clang-format -style=file | diff - +``` + +#### Using an IDE +A number of config files are available [here](https://github.com/AliceO2Group/CodingGuidelines) for various IDEs. + +### O2 code checker +All the AliceO2 pull requests are subject to be tested with [O2 CodeChecker](https://github.com/AliceO2Group/O2CodeChecker#readme) during `build/O2/fullCI` check. It is a bit stricter tool than `clang-format`. Contributors are encouraged to run the codecheck locally before creating a pull request in order to save checking time and CPU resources of the testing facilities. Try to run it in the root directory of your installation: +``` +aliBuild build o2checkcode --defaults o2 +``` +In case of success you'll be informed of it: +``` +==> Build of o2checkcode successfully completed on `your-pc-name'. +``` +Otherwise an ERROR messages will appear: +``` +==> Building o2checkcode@1.0 +==> o2checkcode is being built (use --debug for full output): failed +ERROR: Error while executing /your/path/sw/SPECS/ubuntu2004_x86-64/o2checkcode/1.0-local1/build.sh on `your-pc-name'. +ERROR: Log can be found in /your/path/sw/BUILD/o2checkcode-latest/log +``` +You'll find details of the problem at the __end__ of logfile: `/your/path/sw/BUILD/o2checkcode-latest/log`. For example: +``` +========== List of errors found ========== +/sw/SOURCES/O2/7084-slc8_x86-64/0/Detectors/CPV/calib/include/CPVCalibration/PedestalCalibrator.h:78:3: error: use '= default' to define a trivial destructor [modernize-use-equals-default] +``` +There could be other errors before `========== List of errors found ==========` but they are not relevant. Important ones go after the mentioned line. + +The use of o2checkcode is tested at CC8/CS8 and Ubuntu 20.04.3 LTS. People reported failure of successful running o2checkcode on other systems. Alternative ways to run code checker are following: +1. Try above mentioned way in a Docker container used for CI tests, namely `alisw/slc8-gpu-builder`; +2. Run O2CodeChecker manually in build directory of O2 project. The instructions can be found [here](https://github.com/AliceO2Group/O2CodeChecker#usage). ### Configuration files for editors #### CLion 1. [Download](https://github.com/AliceO2Group/CodingGuidelines/raw/master/settings-o2-codestyle-clion.jar), -2. Go to File -> Import Settings. +2. Go to File -> Import Settings. ## FAQ * __Q__ I strongly disagree with rule X ! * __A__ Feel free to contact the WP3 (alice-o2-wp3@cern.ch) to share your concern(s). Rules have already been amended, abandoned or added based on the users feedback. However, please comply with the rules until a change is agreed by CWG11. - + diff --git a/coding_guidelines.html b/coding_guidelines.html index b6f9604..63a878b 100644 --- a/coding_guidelines.html +++ b/coding_guidelines.html @@ -335,6 +335,7 @@

The #define Guard

<PROJECT>_<PATH>_<FILE>_H_. + Avoid using #pragma once.