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