Merge pull request bemanproject#52 from steve-downey/precommit

Precommit

.cmake-format.json

@@ -0,0 +1,85 @@
+{
+  "parse": {
+    "additional_commands": {
+      "foo": {
+        "flags": [
+          "BAR",
+          "BAZ"
+        ],
+        "kwargs": {
+          "HEADERS": "*",
+          "SOURCES": "*",
+          "DEPENDS": "*"
+        }
+      }
+    },
+    "override_spec": {},
+    "vartags": [],
+    "proptags": []
+  },
+  "format": {
+    "disable": false,
+    "line_width": 80,
+    "tab_size": 2,
+    "use_tabchars": false,
+    "fractional_tab_policy": "use-space",
+    "max_subgroups_hwrap": 2,
+    "max_pargs_hwrap": 6,
+    "max_rows_cmdline": 2,
+    "separate_ctrl_name_with_space": false,
+    "separate_fn_name_with_space": false,
+    "dangle_parens": false,
+    "dangle_align": "prefix",
+    "min_prefix_chars": 4,
+    "max_prefix_chars": 10,
+    "max_lines_hwrap": 2,
+    "line_ending": "unix",
+    "command_case": "canonical",
+    "keyword_case": "unchanged",
+    "always_wrap": [],
+    "enable_sort": true,
+    "autosort": false,
+    "require_valid_layout": false,
+    "layout_passes": {}
+  },
+  "markup": {
+    "bullet_char": "*",
+    "enum_char": ".",
+    "first_comment_is_literal": false,
+    "literal_comment_pattern": null,
+    "fence_pattern": "^\\s*([`~]{3}[`~]*)(.*)$",
+    "ruler_pattern": "^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$",
+    "explicit_trailing_pattern": "#<",
+    "hashruler_min_length": 10,
+    "canonicalize_hashrulers": true,
+    "enable_markup": true
+  },
+  "lint": {
+    "disabled_codes": [],
+    "function_pattern": "[0-9a-z_]+",
+    "macro_pattern": "[0-9A-Z_]+",
+    "global_var_pattern": "[A-Z][0-9A-Z_]+",
+    "internal_var_pattern": "_[A-Z][0-9A-Z_]+",
+    "local_var_pattern": "[a-z][a-z0-9_]+",
+    "private_var_pattern": "_[0-9a-z_]+",
+    "public_var_pattern": "[A-Z][0-9A-Z_]+",
+    "argument_var_pattern": "[a-z][a-z0-9_]+",
+    "keyword_pattern": "[A-Z][0-9A-Z_]+",
+    "max_conditionals_custom_parser": 2,
+    "min_statement_spacing": 1,
+    "max_statement_spacing": 2,
+    "max_returns": 6,
+    "max_branches": 12,
+    "max_arguments": 5,
+    "max_localvars": 15,
+    "max_statements": 50
+  },
+  "encode": {
+    "emit_byteorder_mark": false,
+    "input_encoding": "utf-8",
+    "output_encoding": "utf-8"
+  },
+  "misc": {
+    "per_command": {}
+  }
+}

.codespell_ignore

@@ -0,0 +1,4 @@
+copyable
+falsy
+pullrequest
+unexpect

.git-blame-ignore-revs

@@ -0,0 +1 @@
+907e040

.github/workflows/pre-commit.yml

@@ -0,0 +1,14 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - uses: pre-commit/action@v3.0.1

.gitignore

@@ -25,3 +25,5 @@ compile_commands.json
 /papers/**/_minted-optional_ref/
 /papers/**/_minted-optional_ref_wording/
 .update-submodules
+/.install/
+/.venv/

.pre-commit-config.yaml

@@ -0,0 +1,84 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+        exclude: '^(.*\.svg)$'
+      - id: mixed-line-ending
+        args: ['--fix=lf']
+        exclude: '^(.*\.svg)$'
+      - id: trailing-whitespace
+        exclude: '^(|.*\.svg)$'
+      - id: fix-byte-order-marker
+      - id: no-commit-to-branch
+      - id: requirements-txt-fixer
+
+  - repo: local
+    hooks:
+      - id: clang-format-fix
+        name: clang-format-fix
+        entry: clang-format-18
+        files: ^(src/|include/)
+        types_or: [c++, c]
+        language: system
+        args: ['-i']
+        stages: [manual]
+
+  - repo: https://github.com/pocc/pre-commit-hooks
+    rev: v1.3.5
+    hooks:
+      - id: clang-format
+        additional_dependencies: ['clang-format==18.1.8']
+      # - id: oclint
+      # - id: cppcheck
+      # - id: cpplint
+
+  - repo: https://github.com/pocc/pre-commit-hooks
+    rev: v1.3.5
+    hooks:
+      - id: clang-tidy
+        stages: [manual]
+        additional_dependencies: ['clang-tidy==18.1.8']
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        args: ['-I', '.codespell_ignore', '--uri-ignore-words-list']
+        exclude: |
+          (?x)^(
+            papers/.*
+          )$
+
+  # CMake formatting
+  - repo: https://github.com/cheshirekow/cmake-format-precommit
+    rev: "v0.6.13"
+    hooks:
+      - id: cmake-format
+        additional_dependencies: [pyyaml]
+      - id: cmake-lint
+
+  - repo: https://github.com/jorisroovers/gitlint
+    rev: v0.19.1
+    hooks:
+      - id: gitlint
+      - id: gitlint-ci
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+
+exclude: 'vendor'

.shellcheckrc

@@ -1,3 +1,4 @@
 # shellcheck
 # allow for non-alphanumeric filenames
-disable=SC2038 
+disable=SC2038
+external-sources=true

CMakeLists.txt

@@ -54,3 +54,13 @@ install(
   FILES ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}Config.cmake
         ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_PROJECT_NAME}ConfigVersion.cmake
   DESTINATION ${INSTALL_CONFIGDIR})
+
+# Coverage
+configure_file("cmake/gcovr.cfg.in" gcovr.cfg @ONLY)
+
+add_custom_target(
+  process_coverage
+  WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+  COMMENT "Running gcovr to process coverage results"
+  COMMAND mkdir -p coverage
+  COMMAND gcovr --config gcovr.cfg .)

Makefile

@@ -27,12 +27,12 @@ export
 ifeq ($(strip $(TOOLCHAIN)),)
 	_build_name?=build-system/
 	_build_dir?=.build/
-	_configuration_types?="RelWithDebInfo;Debug;Tsan;Asan"
+	_configuration_types?="RelWithDebInfo;Debug;Tsan;Asan;Gcov"
 	_cmake_args=-DCMAKE_TOOLCHAIN_FILE=$(CURDIR)/etc/toolchain.cmake
 else
 	_build_name?=build-$(TOOLCHAIN)
 	_build_dir?=.build/
-	_configuration_types?="RelWithDebInfo;Debug;Tsan;Asan"
+	_configuration_types?="RelWithDebInfo;Debug;Tsan;Asan;Gcov"
 	_cmake_args=-DCMAKE_TOOLCHAIN_FILE=$(CURDIR)/etc/$(TOOLCHAIN)-toolchain.cmake
 endif
 
@@ -66,10 +66,10 @@ install: $(_build_path)/CMakeCache.txt ## Install the project
 	DESTDIR=$(abspath $(DEST)) ninja -C $(_build_path) -k 0  install
 
 ctest: $(_build_path)/CMakeCache.txt ## Run CTest on current build
-	cd $(_build_path) && ctest --output-on-failure
+	cd $(_build_path) && ctest --output-on-failure -C $(CONFIG)
 
 ctest_ : compile
-	cd $(_build_path) && ctest -C $(CONFIG) --output-on-failure
+	cd $(_build_path) && ctest --output-on-failure -C $(CONFIG)
 
 test: ctest_ ## Rebuild and run tests
 
@@ -89,9 +89,82 @@ env:
 
 .PHONY: papers
 papers:
-	$(MAKE) -C papers papers
+	$(MAKE) -C papers/P2988 papers
+
+PYEXECPATH ?= $(shell which python3.12 || which python3.11 || which python3.10 || which python3.9 || which python3.8 || which python3.7 || which python3)
+PYTHON ?= $(shell basename $(PYEXECPATH))
+VENV := .venv
+ACTIVATE := . $(VENV)/bin/activate &&
+PYEXEC := $(ACTIVATE) $(PYTHON)
+MARKER=.initialized.venv.stamp
+
+PIP := $(PYEXEC) -m pip
+PIP_SYNC := $(PYEXEC) -m piptools sync
+PIPTOOLS_COMPILE := $(PYEXEC) -m piptools compile --no-header --strip-extras
+
+PRE_COMMIT := $(ACTIVATE) pre-commit
+
+PHONY: venv
+venv: ## Create python virtual env
+venv: $(VENV)/$(MARKER)
+
+.PHONY: clean-venv
+clean-venv:
+clean-venv: ## Delete python virtual env
+	-rm -rf $(VENV)
+
+realclean: clean-venv
+
+.PHONY: show-venv
+show-venv: venv
+show-venv: ## Debugging target - show venv details
+	$(PYEXEC) -c "import sys; print('Python ' + sys.version.replace('\n',''))"
+	$(PIP) --version
+	@echo venv: $(VENV)
+
+requirements.txt: requirements.in
+	$(PIPTOOLS_COMPILE) --output-file=$@ $<
+
+requirements-dev.txt: requirements-dev.in
+	$(PIPTOOLS_COMPILE) --output-file=$@ $<
+
+$(VENV):
+	$(PYEXECPATH) -m venv $(VENV)
+	$(PIP) install --upgrade pip setuptools wheel
+	$(PIP) install pip-tools
+
+$(VENV)/$(MARKER): requirements.txt requirements-dev.txt | $(VENV)
+	$(PIP_SYNC) requirements.txt
+	$(PIP_SYNC) requirements-dev.txt
+	touch $(VENV)/$(MARKER)
+
+.PHONY: dev-shell
+dev-shell: venv
+dev-shell: ## Shell with the venv activated
+	$(ACTIVATE) $(notdir $(SHELL))
+
+.PHONY: bash zsh
+bash zsh: venv
+bash zsh: ## Run bash or zsh with the venv activated
+	$(ACTIVATE) exec $@
+
+.PHONY: lint
+lint: venv
+lint: ## Run all configured tools in pre-commit
+	$(PRE_COMMIT) run -a
+
+.PHONY: lint-manual
+lint-manual: venv
+lint-manual: ## Run all manual tools in pre-commit
+	$(PRE_COMMIT) run --hook-stage manual -a
+
+.PHONY: coverage
+coverage: ## Build and run the tests with the GCOV profile and process the results
+coverage: venv
+	$(MAKE) CONFIG=Gcov test
+	$(ACTIVATE) cmake --build $(_build_path) --config Gcov --target process_coverage
 
 # Help target
 .PHONY: help
 help: ## Show this help.
-	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'  $(MAKEFILE_LIST) targets.mk | sort
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'  $(MAKEFILE_LIST) | sort

README.md

@@ -43,7 +43,7 @@ Documentation and associated papers are licensed with the Creative Commons Attri
 
 The intent is that the source and documentation are available for use by people implementing their own optional types as well as people using the optional presented here as-is.
 
-The README itself is licesed with CC0 1.0 Universal. Copy the contents and incorporate in your own work as you see fit.
+The README itself is licensed with CC0 1.0 Universal. Copy the contents and incorporate in your own work as you see fit.
 
 // SPDX-License-Identifier: CC0-1.0
 
@@ -237,6 +237,36 @@ Test project /path/to/Beman.Optional26/.build
 No tests were found!!!
 ```
 
+#### Pre-Commit for Linting
+Various linting tools are configured and installed via the [pre-commit](https://pre-commit.com/) framework. This requires a working python environment, but also allows the tools, such as clang-format and cmake-lint, to be versioned on a per project basis rather than being installed globally. Version changes in lint checks often means differences in success or failure between the versions in CI and the versions used by a developer. By using the same configurations, this problem is avoided.
+
+In order to set up a python environment, using a python virtual environment can simplify maintaining different configurations between projects. There is no particular dependency on a particular python3 version.
+
+##### Creating and configuring a venv
+```shell
+python3 -m venv .venv
+. .venv/bin/activate && python3 -m pip install --upgrade pip setuptools wheel
+. .venv/bin/activate && python3 -m pip install pip-tools
+. .venv/bin/activate && python3 -m piptools sync requirements.txt
+. .venv/bin/activate && python3 -m piptools sync requirements-dev.txt
+. .venv/bin/activate && exec bash
+```
+
+This will create the venv, install the python and python development tools, and run bash with the PATH and other environment variables set to use the venv preferentially.
+
+##### Running the linting tools
+```shell
+pre-commit run -a
+```
+
+This will download and configure the lint tools specified in .pre-commit-config.yaml.
+
+There is also a Makefile that will automate this process and keep everything up to date.
+
+```shell
+make lint
+```
+
 ## Papers
 
 Latest revision(s) of the papers can be built / found at:

cmake/gcovr.cfg.in

@@ -0,0 +1,11 @@
+root = @CMAKE_SOURCE_DIR@
+cobertura = @CMAKE_BINARY_DIR@/coverage/cobertura.xml
+sonarqube = @CMAKE_BINARY_DIR@/coverage/sonarqube.xml
+html-details = @CMAKE_BINARY_DIR@/coverage/coverage.html
+gcov-executable = @GCOV_EXECUTABLE@
+gcov-parallel = yes
+html-theme = github.dark-blue
+html-self-contained = yes
+print-summary = yes
+filter = .*/Beman/Optional26/.*
+exclude = .*\.t\.cpp

docs/debug-ci.md

@@ -18,7 +18,7 @@ Setup and tutorial on [nektosact.com/](https://nektosact.com/).
 ```shell
 # Check available jobs
 $ sudo act --container-architecture linux/amd64 --list
-Stage  Job ID  Job name                   Workflow name  Workflow file  Events           
+Stage  Job ID  Job name                   Workflow name  Workflow file  Events
 0      build   ${{ matrix.config.name }}  CI Tests       ci.yml         pull_request,push
 
 # Run all CI jobs