build: introduce clang-format in the code base, enforce via CI

Individual developers should execute "make reformat-code" or equivalent at each
commit; they can use a pre-commit hook if they want.

The commit also adds a CI workflow that verifies that the tip of a PR (or of
main) respects the clang-format rules.

.clang-format

@@ -0,0 +1,11 @@
+# Copyright (c) 2023 Bank of Italy
+# Distributed under the GNU AGPLv3 software license, see the accompanying COPYING file.
+
+---
+Language: Cpp
+BasedOnStyle: LLVM
+ColumnLimit: 110
+# LineEnding: LF            # requires clang-format >= 16, and ubuntu 22.04 has clang-format 15 at best
+# InsertNewlineAtEOF: true  # requires clang-format >= 16, and ubuntu 22.04 has clang-format 15 at best
+PointerAlignment: Left
+...

.github/workflows/check-code-formatting.yml

@@ -0,0 +1,27 @@
+name: Check code formatting
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  check_format:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Setup clang-format 15 (we'd like 16, but as of 2023-09-29 it's not there)
+        run: |
+          # TODO: once clang-16 becomes available, please enable the rules that
+          # are currently commented in <BASE>/.clang_format
+          sudo update-alternatives --install /usr/bin/clang-format clang-format /usr/bin/clang-format-15 10
+          sudo update-alternatives --set clang-format /usr/bin/clang-format-15
+      - name: Checkout itcoin-fbft
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+      - name: check code formatting
+        run: |
+          make check-code-formatting

Makefile

@@ -0,0 +1,50 @@
+# Copyright (c) 2023 Bank of Italy
+# Distributed under the GNU AGPLv3 software license, see the accompanying COPYING file.
+
+.DEFAULT_GOAL := help
+
+# source: https://stackoverflow.com/questions/18136918/how-to-get-current-relative-directory-of-your-makefile#73509979
+MAKEFILE_ABS_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+
+define PRINT_HELP_PYSCRIPT
+import re, sys
+
+for line in sys.stdin:
+	match = re.match(r'^([0-9a-zA-Z_-]+):.*?## (.*)$$', line)
+	if match:
+		target, help = match.groups()
+		print("%-20s %s" % (target, help))
+endef
+export PRINT_HELP_PYSCRIPT
+
+# source: https://stackoverflow.com/questions/5618615/check-if-a-program-exists-from-a-makefile#25668869
+#
+# please note that there should not be any tabs before the "ifeq/endif"
+# statement
+.PHONY: verify-prerequisites
+verify-prerequisites:
+ifeq (, $(shell command -v clang-format 2> /dev/null))
+	$(error ERROR: please install clang-format)
+endif
+
+.PHONY: check-code-formatting
+# - globstar: enable recursive globbing via "**" in bash >= 4 (equivalent to
+#             shopt -s globstar)
+# - nullglob: when a glob does not match anything, return "" instead of the
+#             literal glob text (equivalent to shopt -s globstar)
+SHELL = /usr/bin/env bash -O globstar -O nullglob
+check-code-formatting: verify-prerequisites ## Check if the code base is correctly formatted. Do not touch the files
+	clang-format --Werror --style=file:.clang-format --ferror-limit=20 --dry-run "${MAKEFILE_ABS_DIR}"/src/*/*.{h,hpp,c,cpp}
+
+.PHONY: reformat-code
+# - globstar: enable recursive globbing via "**" in bash >= 4 (equivalent to
+#             shopt -s globstar)
+# - nullglob: when a glob does not match anything, return "" instead of the
+#             literal glob text (equivalent to shopt -s globstar)
+SHELL = /usr/bin/env bash -O globstar -O nullglob
+reformat-code: verify-prerequisites ## Reformat the code base in the src directory. Can be used as pre-commit hook
+	clang-format --Werror --style=file:.clang-format -i --verbose "${MAKEFILE_ABS_DIR}"/src/**/*.{h,hpp,c,cpp}
+
+.PHONY: help
+help:
+	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)

README.md

@@ -14,6 +14,8 @@ Please note that this software is solely intended for testing and experimentatio
 
 1. Install build and dev dependencies with apt (system-wide):
 
+TODO: add documentation about clang-format in this file
+
 ```
 sudo apt install --no-install-recommends -y \
     autoconf \