From d377a4a3c9d8481a1ac866aad75d597f35f15727 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 13 Nov 2026 06:11:46 +0000 Subject: [PATCH] docs: explain version requirements and where clang tools come from The `version` input still pointed at clang-tools-pip and only listed major versions. v3 passes it to cpp-linter v2 as a semantic version requirement, so `18.1.8` means 18.1.8 or a newer 18.x release and `=18.1.8` means exactly that version. Also list the sources v3 tries, in order, for every runner (installed tool, cache, system package manager, PyPI, static binaries). --- action.yml | 8 ++++++-- cspell.config.yml | 2 ++ docs/required-tools.md | 33 ++++++++++++--------------------- 3 files changed, 20 insertions(+), 23 deletions(-) diff --git a/action.yml b/action.yml index 84b4b533..343a826d 100644 --- a/action.yml +++ b/action.yml @@ -38,9 +38,13 @@ inputs: default: '.' version: description: | - The desired version of the [clang-tools](https://github.com/cpp-linter/clang-tools-pip) to use. - Accepted options are strings which can be 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13 or 12. + The desired version of the clang tools (`clang-format` and `clang-tidy`) to use. + Clang tools from version 12 through 23 are supported. + - A major version, like `18`, accepts any 18.x release. + - A full version, like `18.1.8`, accepts 18.1.8 or a newer 18.x release. + Use `=18.1.8` to require exactly that version. + - Other semantic version requirements also work, like `>=17, <20`. - Set this option to a blank string (`''`) to use the platform's default installed version. - This value can also be a path to where the clang tools are installed (if using a custom install location). required: false diff --git a/cspell.config.yml b/cspell.config.yml index 06f7a894..1288369b 100644 --- a/cspell.config.yml +++ b/cspell.config.yml @@ -16,6 +16,7 @@ words: - Neta - Nextcloud - nushell + - pacman - pymdownx - pymdown - pyyaml @@ -23,6 +24,7 @@ words: - stylesheet - twemoji - venv + - winget - Zondax ignorePaths: - .gitattributes diff --git a/docs/required-tools.md b/docs/required-tools.md index b274ebf2..23aede77 100644 --- a/docs/required-tools.md +++ b/docs/required-tools.md @@ -30,32 +30,23 @@ apt-get install -y libc6 wget lsb-release software-properties-common gnupg Otherwise, [nushell] and/or the LLVM-provided bash script will fail to run. -If installing clang tools fails using the `apt` package manager, then -we alternatively try the following sources in order: +## Where clang tools come from -1. Static binaries that we built ourselves; see [cpp-linter/clang-tools-pip] project for more detail. -2. PyPI Packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] +The `version` input is resolved on every runner by trying these sources in order +(whichever succeeds first): -## On macOS runners - -The specified `version` of `clang-format` and `clang-tidy` is installed via -the following sources in order (whichever succeeds first): - -1. Homebrew -2. Static binaries that we built ourselves; see [cpp-linter/clang-tools-pip] project for more detail. -3. PyPI Packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] - -## On Windows runners - -For Windows runners, we use clang tools installed via -the following sources in order (whichever succeeds first): - -1. Static binaries that we built ourselves; see [cpp-linter/clang-tools-pip] project for more detail. -2. PyPI Packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] +1. A `clang-format`/`clang-tidy` already installed on the runner whose version satisfies `version`. +2. A version that cpp-linter downloaded earlier and kept in its cache. +3. The system package manager: + - Linux: `apt` (falling back to LLVM's official apt repository), `dnf`, `pacman`, or Homebrew + - macOS: Homebrew + - Windows: Chocolatey or winget +4. PyPI packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] +5. Static binaries that we build ourselves; see the [cpp-linter/clang-tools-static-binaries] project. [nushell]: https://www.nushell.sh/ [uv]: https://docs.astral.sh/uv/ -[cpp-linter/clang-tools-pip]: https://github.com/cpp-linter/clang-tools-pip +[cpp-linter/clang-tools-static-binaries]: https://github.com/cpp-linter/clang-tools-static-binaries [gh-container-syntax]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idcontainer [clang-tidy-wheel]: https://pypi.org/project/clang-tidy [clang-format-wheel]: https://pypi.org/project/clang-format