Add a .github/bin/before-submit.sh script
A little convenience script to run all the diagnostics the
CI would also do.
Also update some developer resources documentation.
diff --git a/.github/bin/before-submit.sh b/.github/bin/before-submit.sh
new file mode 100755
index 0000000..cdb07ed
--- /dev/null
+++ b/.github/bin/before-submit.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+#
+# A wrapper for all the things to do before a submit.
+
+BANT=$($(dirname $0)/get-bant-path.sh)
+
+PROJECT_ROOT=$(dirname $0)/../../
+cd ${PROJECT_ROOT}
+
+RUN_CLANG_TIDY=1
+while [ $# -ne 0 ]; do
+ case $1 in
+ --skip-clang-tidy) RUN_CLANG_TIDY=0;;
+ *)
+ echo "Unknown option $1"
+ exit 1
+ ;;
+ esac
+ shift 1
+done
+
+if [ -t 1 ]; then
+ BOLD=$'\033[7m'
+ NORM=$'\033[0m'
+else
+ BOLD=""
+ NORM=""
+fi
+
+echo "${BOLD}-- Run build cleaner --${NORM}"
+. <(${BANT} dwyu ...)
+
+echo "${BOLD}-- Run all tests --${NORM}"
+bazel test -c opt ...
+
+if [ "${RUN_CLANG_TIDY}" -eq 1 ]; then
+ # Run clang-tidy; needs a compilation DB first
+ .github/bin/make-compilation-db.sh
+ echo "${BOLD}-- Running clang-tidy and cache results --${NORM}"
+ echo "This will take a while if run the first time and no cache has"
+ echo "been created yet. Can't wait ? Skip with "
+ echo " $0 --skip-clang-tidy"
+ .github/bin/run-clang-tidy-cached.cc
+fi
+
+echo "${BOLD}-- Format code and BUILD files --${NORM}"
+.github/bin/run-format.sh
+
+echo "${BOLD}-- Check for potential problems --${NORM}"
+.github/bin/check-potential-problems.sh
+
+echo "Done. Check output above for any issues."
diff --git a/.github/bin/generate-coverage-html.sh b/.github/bin/generate-coverage-html.sh
index 2f3e496..baffdd2 100755
--- a/.github/bin/generate-coverage-html.sh
+++ b/.github/bin/generate-coverage-html.sh
@@ -45,4 +45,5 @@
fi
genhtml --ignore-errors inconsistent -o ${OUTPUT_DIR} ${COVERAGE_DATA}
-echo "Output in $(realpath ${OUTPUT_DIR}/index.html)"
+echo
+echo "Output in file://$(realpath ${OUTPUT_DIR}/index.html)"
diff --git a/.github/bin/get-bant-path.sh b/.github/bin/get-bant-path.sh
new file mode 100755
index 0000000..3df2d5a
--- /dev/null
+++ b/.github/bin/get-bant-path.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Copyright 2025 The Verible Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Print path to a bant binary. Can be provided by an environment variable
+# or built from our dependency.
+
+BAZEL=${BAZEL:-bazel}
+BANT=${BANT:-needs-to-be-compiled-locally}
+
+# Bant not given, compile from bzlmod dep.
+if [ "${BANT}" = "needs-to-be-compiled-locally" ]; then
+ "${BAZEL}" build -c opt --cxxopt=-std=c++20 @bant//bant:bant 2>/dev/null
+ BANT=$(realpath bazel-bin/external/bant*/bant/bant | head -1)
+fi
+
+echo $BANT
diff --git a/.github/bin/make-compilation-db.sh b/.github/bin/make-compilation-db.sh
index a0a41e1..d0c37b3 100755
--- a/.github/bin/make-compilation-db.sh
+++ b/.github/bin/make-compilation-db.sh
@@ -18,16 +18,7 @@
# Which bazel and bant to use can be chosen by environment variables
BAZEL=${BAZEL:-bazel}
-BANT=${BANT:-needs-to-be-compiled-locally}
-
-if [ "${BANT}" = "needs-to-be-compiled-locally" ]; then
- # Bant not given, compile from bzlmod dep. We need to do that before
- # we run other bazel rules below as we change the cxxopt flags. Remember
- # the full realpath of the resulting binary to be immune to symbolic-link
- # switcharoo by bazel.
- ${BAZEL} build -c opt --cxxopt=-std=c++20 @bant//bant:bant >/dev/null 2>&1
- BANT=$(realpath bazel-bin/external/bant*/bant/bant | head -1)
-fi
+BANT=$($(dirname $0)/get-bant-path.sh)
BAZEL_OPTS="-c opt --noshow_progress"
# Bazel-build all targets that generate files, so that they can be
diff --git a/.github/bin/run-build-cleaner.sh b/.github/bin/run-build-cleaner.sh
index 0ec053f..b8d1af5 100755
--- a/.github/bin/run-build-cleaner.sh
+++ b/.github/bin/run-build-cleaner.sh
@@ -16,17 +16,7 @@
set -u
set -e
-# Which bazel and bant to use can be chosen by environment variables
-BAZEL=${BAZEL:-bazel}
-BANT=${BANT:-needs-to-be-compiled-locally}
-
-if [ "${BANT}" = "needs-to-be-compiled-locally" ]; then
- # Bant not given, compile from bzlmod dep.
- ${BAZEL} build -c opt --cxxopt=-std=c++20 @bant//bant:bant >/dev/null 2>&1
- BANT=$(realpath bazel-bin/external/bant*/bant/bant | head -1)
-fi
-
-DWYU_OUT="${TMPDIR:-/tmp}/dwyu.out"
+BANT=$($(dirname $0)/get-bant-path.sh)
if "${BANT}" -q dwyu ... ; then
echo "Dependencies ok." >&2
diff --git a/.github/bin/run-format.sh b/.github/bin/run-format.sh
index 24e97ee..f8f5f44 100755
--- a/.github/bin/run-format.sh
+++ b/.github/bin/run-format.sh
@@ -16,12 +16,29 @@
set -u # only use variables once assigned
set -e # error out on error.
+SHOW_DIFF=0
+
+while [ $# -ne 0 ]; do
+ case $1 in
+ --show-diff) SHOW_DIFF=1;;
+ *)
+ echo "Unknown option $1"
+ exit 1
+ ;;
+ esac
+ shift 1
+done
+
FORMAT_OUT=${TMPDIR:-/tmp}/clang-format-diff.out
CLANG_FORMAT=${CLANG_FORMAT:-clang-format}
BUILDIFIER=${BUILDIFIER:-buildifier}
-${CLANG_FORMAT} --version
+# Currently, we're using clang-format 17, as newer versions still have some
+# volatility in minor version.
+${CLANG_FORMAT} --version | grep "17\." ||
+ ( echo "-- Need clang-format 17. Currently CLANG_FORMAT=$CLANG_FORMAT --";
+ exit 1)
# Run on all files.
@@ -36,17 +53,19 @@
${BUILDIFIER} MODULE.bazel $(find . -name BUILD -o -name "*.bzl")
fi
-# Check if we got any diff
-git diff > ${FORMAT_OUT}
+if [ ${SHOW_DIFF} -eq 1 ]; then
+ # Check if we got any diff
+ git diff > ${FORMAT_OUT}
-if [ -s ${FORMAT_OUT} ]; then
- echo "Style not matching (see https://github.com/chipsalliance/verible/blob/master/CONTRIBUTING.md#style)"
- echo "Run"
- echo " .github/bin/run-clang-format.sh"
- echo "-------------------------------------------------"
- echo
- cat ${FORMAT_OUT}
- exit 1
+ if [ -s ${FORMAT_OUT} ]; then
+ echo "Style not matching (see https://github.com/chipsalliance/verible/blob/master/CONTRIBUTING.md#style)"
+ echo "Run"
+ echo " .github/bin/run-clang-format.sh"
+ echo "-------------------------------------------------"
+ echo
+ cat ${FORMAT_OUT}
+ exit 1
+ fi
fi
exit 0
diff --git a/.github/workflows/verible-ci.yml b/.github/workflows/verible-ci.yml
index c8507e0..8b52bc5 100644
--- a/.github/workflows/verible-ci.yml
+++ b/.github/workflows/verible-ci.yml
@@ -42,7 +42,7 @@
- name: Run formatting style check
run: |
echo "--- check formatting ---"
- CLANG_FORMAT=clang-format-17 ./.github/bin/run-format.sh
+ CLANG_FORMAT=clang-format-17 ./.github/bin/run-format.sh --show-diff
echo "--- check build dependencies ---"
./.github/bin/run-build-cleaner.sh
echo "--- check potential problems ---"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1a4b641..93e61c6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,6 +46,13 @@
clang-format --style=file -i <your-modified-c++-files>
```
+There is a script that runs build cleaning, formatting, clang-tidy and
+tests in one go:
+
+```
+.github/bin/before-submit.sh
+```
+
### Testing
Testing is a critical component to any code contribution. Make sure your the
@@ -59,9 +66,8 @@
#### Running Code Coverage
-Code coverage is run in each pull request and tracked on [codecov].
-Tests for any new feature should exercise all possible branches;
-pull requests should strive for 100% differential coverage.
+Coverage is a useful tool to find branches that are never exercised in any
+test, so make sure tests for new features exercise all possible branches.
To inspect coverage locally, run
diff --git a/MODULE.bazel b/MODULE.bazel
index adb123b..d3f2d0f 100644
--- a/MODULE.bazel
+++ b/MODULE.bazel
@@ -22,4 +22,4 @@
bazel_dep(name = "googletest", version = "1.14.0.bcr.1", dev_dependency = True)
# To build compilation DB and run build-cleaning
-bazel_dep(name = "bant", version = "0.1.13", dev_dependency = True)
+bazel_dep(name = "bant", version = "0.2.0", dev_dependency = True)
diff --git a/doc/development.md b/doc/development.md
index 3705166..0508487 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -6,8 +6,8 @@
## Searching and Navigating Verible's Source Code
https://cs.opensource.google/verible/verible is a search-indexed mirror of
-[Verible's source code](https://github.com/chipsalliance/verible). Expect to spend a
-lot of time here as you familiarize yourself with the codebase.
+[Verible's source code](https://github.com/chipsalliance/verible).
+Expect to spend some time here as you familiarize yourself with the codebase.
https://developers.google.com/code-search/reference provides a reference for
search syntax and more.
@@ -15,6 +15,37 @@
To learn more about how to use Kythe to
[index the source code yourself, read here](./indexing.md).
+To allow your editor to navigate the code base, make sure it uses the
+`clangd` language server. With
+
+```
+.github/bin/make-compilation-db.sh
+```
+
+You can create the compilation database it needs.
+
+### Automated tools that allow to keep things clean
+
+If you have a compilation database, you can run the clang-tidy checker:
+
+```
+.github/bin/run-clang-tidy-cached.cc
+```
+
+Note, this will take a while the first time, but it caches the result.
+
+To run all litmus diagnostics before submitting, there is this convenient
+script, run it before creating a pull request to see if you haven't missed
+anything (the Continuous Integration on github will catch it, but nice to
+run this locally):
+
+```
+.github/bin/before-submit.sh
+```
+
+This will also run `clang-tidy`, and so will take a while the first time
+you run it.
+
### Tips
* Read the test code. Most `.h` and `.cc` files come with a `_test.cc` set of
