diff --git a/README.md b/README.md index 94ce7525..d33cca2f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + [file-annotations]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#file-annotations [thread-comments]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#thread-comments @@ -10,7 +10,7 @@ [recipes-doc]: https://cpp-linter.github.io/cpp-linter-action/examples [permissions-doc]: https://cpp-linter.github.io/cpp-linter-action/permissions [app-token-doc]: https://cpp-linter.github.io/cpp-linter-action/permissions/#github-app-token -[skip-doc]: https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs +[tools-doc]: https://cpp-linter.github.io/cpp-linter-action/required-tools [format-annotations-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-format.png [tidy-annotations-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-tidy.png @@ -22,31 +22,26 @@ -# C/C++ Linter Action | clang-format & clang-tidy - -![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/cpp-linter/cpp-linter-action) -[![GitHub marketplace](https://img.shields.io/badge/marketplace-C%2FC%2B%2B%20Linter-blue?logo=github)](https://github.com/marketplace/actions/c-c-linter) -[![cpp-linter](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml) -[![MkDocs Deploy](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/mkdocs-deploy.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/mkdocs-deploy.yml) -[![cpp-linter hub](https://img.shields.io/badge/%F0%9F%8F%A0_cpp--linter_hub-%E2%86%90_home-22863a)](https://cpp-linter.github.io/) +# cpp-linter-action -A Github Action for linting C/C++ code integrating clang-tidy and clang-format -to collect feedback provided in the form of -[`file-annotations`][file-annotations], [`thread-comments`][thread-comments], -workflow [`step-summary`][step-summary], and Pull Request reviews (with -[`tidy-review`][tidy-review] or [`format-review`][format-review]). +[![release](https://img.shields.io/github/v/release/cpp-linter/cpp-linter-action?label=release&labelColor=454a63&color=007ec6)](https://github.com/cpp-linter/cpp-linter-action/releases) +[![ci](https://img.shields.io/github/actions/workflow/status/cpp-linter/cpp-linter-action/self-test.yml?branch=main&label=ci&labelColor=454a63)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/self-test.yml) +[![part of cpp-linter](https://img.shields.io/badge/part%20of-cpp--linter-ffc20a?labelColor=454a63)](https://cpp-linter.github.io/) -> [!TIP] -> Prefer pre-commit hooks over GitHub Actions? Check out -> [**cpp-linter-hooks**](https://github.com/cpp-linter/cpp-linter-hooks) — -> a pre-commit hook repository that runs `clang-format` and `clang-tidy` -> consistently on developer machines and in CI, with no manual LLVM installs. +A GitHub Action that checks the C and C++ files a pull request changes with clang-format and +clang-tidy, and reports the findings as [`file-annotations`][file-annotations], +[`thread-comments`][thread-comments], a workflow [`step-summary`][step-summary] and pull request +reviews (with [`tidy-review`][tidy-review] or [`format-review`][format-review]). -## Usage +[Website](https://cpp-linter.github.io/) · +[Documentation](https://cpp-linter.github.io/cpp-linter-action/) · +[Marketplace](https://github.com/marketplace/actions/c-c-linter) · +[Get started](https://cpp-linter.github.io/getting-started/#on-every-pull-request) · +[Discussions](https://github.com/orgs/cpp-linter/discussions) -Create a new GitHub Actions workflow in your project, e.g. at [.github/workflows/cpp-linter.yml](https://github.com/cpp-linter/cpp-linter-action/blob/main/.github/workflows/cpp-linter.yml) +## Quick start -The content of the file should be in the following format. +Save this as `.github/workflows/cpp-linter.yml`: ```yaml name: cpp-linter @@ -57,7 +52,7 @@ jobs: runs-on: ubuntu-latest permissions: contents: read - pull-requests: write # to post the thread comment + pull-requests: write steps: - uses: actions/checkout@v7 - uses: cpp-linter/cpp-linter-action@v2 @@ -65,21 +60,50 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: - style: 'file' # Use .clang-format config file - tidy-checks: '' # Use .clang-tidy config file - # only 'update' a single comment in a pull request thread. - # Pull requests from forks get a read-only token, so skip the comment there. - thread-comments: ${{ github.event.pull_request.head.repo.full_name == github.repository && 'update' }} - - name: Fail fast?! + version: '21' + style: file + tidy-checks: '' + format-review: true + - name: Fail on lint errors if: steps.linter.outputs.checks-failed > 0 run: exit 1 ``` +- `style: file` and `tidy-checks: ''` use your `.clang-format` and `.clang-tidy`. `version` takes + an LLVM major from 12 to 23; `21` is the default. +- Annotations in the diff view are on by default. `format-review`, `tidy-review` and + `thread-comments` are opt-in and need `pull-requests: write`; turn on one of the two reviews, not + both. `auto-fix` commits the clang-format fixes to the branch and needs `contents: write`. +- The action does not fail the job by itself; the last step does, using the `checks-failed` + output. +- Pull requests from forks get a read-only token: annotations still appear, but reviews are not + posted, and `thread-comments` would fail the step. Draft pull requests get no review. + +## Usage + For all explanations of our available input parameters and output variables, see our [Inputs and Outputs document][io-doc]. See also our [example recipes][recipes-doc]. +### Post a thread comment + +Set `thread-comments` to post the findings as a comment in the pull request thread. With +`update`, the action updates its existing comment instead of posting a new one: + +```yaml + - uses: cpp-linter/cpp-linter-action@v2 + id: linter + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + style: 'file' # Use .clang-format config file + tidy-checks: '' # Use .clang-tidy config file + # only 'update' a single comment in a pull request thread. + # Pull requests from forks get a read-only token, so skip the comment there. + thread-comments: ${{ github.event.pull_request.head.repo.full_name == github.repository && 'update' }} +``` + ### Auto-fix clang-format issues Set `auto-fix: 'true'` and the action applies `clang-format -i` to the files with style @@ -123,35 +147,6 @@ there is no server or webhook handling to host. See [GitHub App token][app-token-doc] for the setup steps. -## Used By - -

- Apache - Apache   - Samsung - Samsung   - Bloomberg - Bloomberg   - Qualcomm - Qualcomm   - Nextcloud - Nextcloud   - CachyOS - CachyOS   -
- Jupyter - Jupyter   - NNStreamer - NNStreamer   - Zondax - Zondax   - AppNeta - AppNeta   - Chocolate Doom - Chocolate Doom   - and many more. -

- ## Example ### Annotations @@ -194,86 +189,41 @@ Using [`format-review`][format-review]: ![sample format-suggestion][format-suggestion-preview] -## Add C/C++ Linter Action badge in README - -You can show C/C++ Linter Action status with a badge in your repository README - -Example - -```markdown -[![cpp-linter](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml) -``` - -[![cpp-linter](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml) - -## Have question or feedback? - -To provide feedback (requesting a feature or reporting a bug) please post to [issues](https://github.com/cpp-linter/cpp-linter-action/issues). - -## Required tools installed +## Supported runners -As of v2.16.0, this action uses +Linux, macOS and Windows runners are supported. On Linux, we only support a Debian-based Linux OS +(like Ubuntu and many others), because we first try to use the `apt` package manager to install +clang tools. Linux workflows that use a specific [`container`][gh-container-syntax] need a few +packages installed first. [Required tools][tools-doc] lists them and the sources each runner +installs the clang tools from. -- [nushell] for cross-platform compatible scripting -- [uv] for driving a Python virtual environment +## Used by -This action installs [nushell] and [uv] automatically. -Only [nushell] is added to the PATH environment variable. -[uv], and any standalone Python distribution it downloads, are not added to the PATH environment variable. +Projects from these organizations run cpp-linter-action on their default branch: -### On Linux runners +[ Apache](https://github.com/apache) · +[ Samsung](https://github.com/samsung) · +[ Bloomberg](https://github.com/bloomberg) · +[ Qualcomm](https://github.com/qualcomm) · +[ Nextcloud](https://github.com/nextcloud) · +[ CachyOS](https://github.com/CachyOS) · +[ Jupyter Xeus](https://github.com/jupyter-xeus) · +[ NNStreamer](https://github.com/nnstreamer) · +[ Zondax](https://github.com/Zondax) · +[ AppNeta](https://github.com/AppNeta) · +[ Chocolate Doom](https://github.com/chocolate-doom) -We only support Linux runners using a Debian-based Linux OS (like Ubuntu and many others). -This is because we first try to use the `apt` package manager to install clang tools. +The [showcase](https://cpp-linter.github.io/showcase/) lists more projects that use it. -Linux workflows that use a specific [`container`][gh-container-syntax] should ensure that -the following are installed: +## Contributing -- GLIBC (v2.32 or later) -- `wget` or `curl` -- `lsb-release` (required by LLVM-provided install script) -- `software-properties-common` (required by LLVM-provided install script) -- `gnupg` (required by LLVM-provided install script) - -```shell -apt-get update -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: - -1. PyPI Packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] -2. Static binaries that we built ourselves; see [cpp-linter/clang-tools-pip] project for more detail. - -### 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. PyPI Packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] -3. Static binaries that we built ourselves; see [cpp-linter/clang-tools-pip] project for more detail. - -### On Windows runners - -For Windows runners, we use clang tools installed via -the following sources in order (whichever succeeds first): - -1. PyPI Packages [clang-tidy][clang-tidy-wheel] and/or [clang-format][clang-format-wheel] -2. Static binaries that we built ourselves; see [cpp-linter/clang-tools-pip] project for more detail. +Read [CONTRIBUTING.md](https://github.com/cpp-linter/cpp-linter-action/blob/main/CONTRIBUTING.md) before you open a pull request, and report bugs or request features in [issues](https://github.com/cpp-linter/cpp-linter-action/issues). ## License The scripts and documentation in this project are released under the [MIT License](https://github.com/cpp-linter/cpp-linter-action/blob/main/LICENSE) -[nushell]: https://www.nushell.sh/ -[uv]: https://docs.astral.sh/uv/ -[cpp-linter/clang-tools-pip]: https://github.com/cpp-linter/clang-tools-pip [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 +[skip-doc]: https://docs.github.com/en/actions/how-tos/manage-workflow-runs/skip-workflow-runs diff --git a/docs/index.md b/docs/index.md index d5ecfe83..dbc0e3d8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,6 +8,7 @@ [recipes-doc]: examples/index.md [permissions-doc]: permissions.md [app-token-doc]: permissions.md#github-app-token +[tools-doc]: required-tools.md [format-annotations-preview]: images/annotations-clang-format.png [tidy-annotations-preview]: images/annotations-clang-tidy.png diff --git a/docs/required-tools.md b/docs/required-tools.md new file mode 100644 index 00000000..b274ebf2 --- /dev/null +++ b/docs/required-tools.md @@ -0,0 +1,61 @@ +# Required Tools + +As of v2.16.0, this action uses + +- [nushell] for cross-platform compatible scripting +- [uv] for driving a Python virtual environment + +This action installs [nushell] and [uv] automatically. +Only [nushell] is added to the PATH environment variable. +[uv], and any standalone Python distribution it downloads, are not added to the PATH environment variable. + +## On Linux runners + +We only support Linux runners using a Debian-based Linux OS (like Ubuntu and many others). +This is because we first try to use the `apt` package manager to install clang tools. + +Linux workflows that use a specific [`container`][gh-container-syntax] should ensure that +the following are installed: + +- GLIBC (v2.32 or later) +- `wget` or `curl` +- `lsb-release` (required by LLVM-provided install script) +- `software-properties-common` (required by LLVM-provided install script) +- `gnupg` (required by LLVM-provided install script) + +```shell +apt-get update +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: + +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] + +## 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] + +[nushell]: https://www.nushell.sh/ +[uv]: https://docs.astral.sh/uv/ +[cpp-linter/clang-tools-pip]: https://github.com/cpp-linter/clang-tools-pip +[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 diff --git a/mkdocs.yml b/mkdocs.yml index df40bf12..4401284a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ nav: - inputs-outputs.md - pr-review-caveats.md - permissions.md + - required-tools.md - examples/index.md - contributing-guidelines.md - "← cpp-linter hub": https://cpp-linter.github.io/