# Add Cppcheck to CI for a CMake Project

Yes. An agent adds a Cppcheck job to your CMake project's CI, driven by compile_commands.json, with suppressions for vendored headers and a failing exit code.

[Run this on Rush](https://cloud.getrush.ai/run/add-cppcheck-to-ci/cmake/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the project is built in CI before adding an analyser to it. In a library laid out like jarro2783/cxxopts, `CMakeLists.txt` requires CMake 3.5 and declares `cxxopts` as an `INTERFACE` library whose single header, `include/cxxopts.hpp`, is 3,192 lines; the options `CXXOPTS_BUILD_EXAMPLES`, `CXXOPTS_BUILD_TESTS` and `CXXOPTS_ENABLE_WARNINGS` default to on for a standalone build, `cmake/cxxopts.cmake` sets C++11 with extensions off and a `-Wall -Werror -Wextra -Wshadow -Weffc++ -Wconversion` set for GCC and Clang, and `test/CMakeLists.txt` builds `options_test` and `options_test_noregex` from `main.cpp` and `options.cpp` against the vendored `catch.hpp`, plus no-exception smoke tests, a fuzzer under Clang, and find-package, add-subdirectory and pkg-config tests. `.github/workflows/cmake.yml` builds on Ubuntu 22.04 and 24.04 with `g++-9`, `g++-10` and `clang++`, on macOS with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`, and on Windows with ClangCL; `build.yml` is a plain `cmake ..` and `make`, `meson.yml` covers the Meson build, and `cifuzz.yml` runs OSS-Fuzz. The warnings-as-errors flags are the only static checking.

The job the agent adds to `cmake.yml`, `cppcheck`, runs on `ubuntu-24.04`, whose `apt` package is Cppcheck 2.13, installs it, configures the project with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` as the macOS job already does, and runs `cppcheck --project=build/compile_commands.json`. The compilation database is the right input for a header-only library: Cppcheck checks headers through the translation units that include them, so `include/cxxopts.hpp` is analysed as `test/options.cpp`, `src/example.cpp` and the other test sources see it, with the include paths and defines CMake recorded, including `CXXOPTS_NO_REGEX` for the second test binary. The flags are `--enable=warning,style,performance,portability`, leaving out `unusedFunction`, which is wrong for a library and for Catch's registration macros, and `missingInclude`; `--std=c++11` to match `cxxopts_set_cxx_standard`; `--inline-suppr` so a `// cppcheck-suppress` comment in the header works; `--error-exitcode=1` so a finding fails the job; and `-j` set to the runner's cores.

Suppressions keep the job about the library's code. `--suppress=*:*/catch.hpp` silences everything in the vendored test framework, which is not this project's to fix, with the `[id]:[file]` wildcard form the manual gives; `-i build` keeps the configure tree out; and a `.cppcheck-suppressions` file read with `--suppressions-list` holds any per-line entry with a comment saying why, so the workflow line stays short. The agent runs the job's command in its sandbox on the real tree first, reads every finding in `cxxopts.hpp`, `options.cpp` and `example.cpp`, fixes what is a real issue, adds an inline suppression with the check id for a pattern the library uses on purpose, such as a constructor the style check wants `explicit` where implicit conversion is the API, and records each decision in the pull request. `--check-level=exhaustive` is left as a documented option, since the normal level is the default and the exhaustive one costs minutes on a 3,000-line header.

A second configuration covers the `CXXOPTS_NO_EXCEPTIONS` builds, because the no-exception smoke tests compile the header with a different define and Cppcheck checks one preprocessor configuration per file by default; the job runs a second time with `-DCXXOPTS_NO_EXCEPTIONS` added through `--project` on a build configured that way, rather than `--force`, which would walk every `#ifdef` combination. The workflow uploads the `--xml` output as an artifact on failure so a finding can be read without re-running, and `README.md` gets the two commands under a Static analysis heading so a contributor can run the same check locally before pushing.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Cppcheck to CI for this CMake project. Read CMakeLists.txt, cmake/cxxopts.cmake, include/CMakeLists.txt, src/CMakeLists.txt, test/CMakeLists.txt and every workflow under .github/workflows first. Add a cppcheck job to the CMake workflow on ubuntu-24.04 that installs Cppcheck from apt, configures with CMAKE_EXPORT_COMPILE_COMMANDS on, and runs cppcheck with --project on the compilation database, --enable=warning,style,performance,portability, --std matching the project's standard, --inline-suppr, --error-exitcode=1, -j, a suppression for everything in the vendored catch.hpp, -i for the build directory, and a suppressions list file for per-line entries with reasons. Run it in the sandbox on the real tree, fix real findings, add inline suppressions with the check id and a reason for patterns the library uses on purpose, and list each decision. Add a second run on a build configured with the no-exceptions define. Upload the XML output as an artifact on failure and document the local command in the README. Run the existing tests after your fixes and open a pull request quoting the Cppcheck output before and after.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `.cppcheck-suppressions` and changes `.github/workflows/cmake.yml`, `README.md`, and whichever of `include/cxxopts.hpp`, `test/options.cpp` and `src/example.cpp` had a finding worth fixing or an inline suppression. Its description quotes the Cppcheck output from the first run on the untouched tree, a table with one row per finding naming the check id, the file and line and what was done, the clean run after the changes for both configurations, and the `ctest` result showing the test binaries still pass under the project's `-Werror` flags.

A reviewer reads the fixes as ordinary code changes, checks each suppression's reason, and decides whether `unusedFunction` or `--check-level=exhaustive` is worth the extra time on their runners. They also decide whether the job should block merging, which is a branch-protection setting the pull request names but does not change.

The compiler matrix, the macOS and Windows jobs, the Meson workflow and the fuzzing job are untouched, and Cppcheck adds no dependency to the library itself.

## Run it on every C++ repository without static analysis

An organisation with several CMake projects can send this body once per repository from a short script on its own server: list what the GitHub App reaches with `GET /o/{org}/github`, keep the repositories whose default branch has a `CMakeLists.txt` and no `cppcheck` in `.github/workflows`, and give each request a `request_id` that is a UUID v5 of the repository's full name so a rerun returns the runs it already started. Each run opens one pull request fitted to that project's standard, defines and vendored headers, and the key's `webhook_url` receives `run.completed` for each.

Once the job is in, an automation on the Project with a `github` trigger on `workflow_run.failure` can run read-only with a prompt that reads the failed job's Cppcheck XML artifact and comments on the pull request with each finding's file, line and check id. The trigger adds the event after the prompt; it fills in no placeholder.

## Why run it on Rush?

Cppcheck on a header-only library is mostly about what to feed it and what to ignore: the compilation database so the header is seen through real translation units with the right defines, a suppression for the vendored test framework, a second configuration for the define that changes the header's shape, and a first run whose findings someone has to read. The agent reads the CMake files and the workflow matrix, runs the analyser on the real tree in its sandbox before writing the job, and handles each finding with a fix or a reasoned suppression, with the output kept in the run's record.

The job that lands is one a contributor can reproduce with two commands from the README, which is what makes a static-analysis gate something people fix rather than disable.

## Frequently asked questions

### Why use compile_commands.json for a header-only library?

Cppcheck analyses a header through the source files that include it, so pointing it at `include/` alone finds nothing. The compilation database lists `test/options.cpp`, `src/example.cpp` and the other test sources with their include paths and defines, so `cxxopts.hpp` is checked in each context it is compiled in.

### Will catch.hpp findings fail the job?

No. `--suppress=*:*/catch.hpp` silences every check id in that file, using the wildcard form Cppcheck's manual gives for suppressions. `-i` would not do it, because an ignored path only skips translation units, and a header included from a checked source is still analysed.

### What about the no-exceptions build?

Cppcheck checks one preprocessor configuration per file by default, so the `CXXOPTS_NO_EXCEPTIONS` branches of the header would go unchecked. The job configures the project a second time with that define and runs `--project` on its database, which covers those branches without `--force` walking every `#ifdef` combination.

### Why not --enable=all?

`all` includes `unusedFunction`, which reports every public function of a library nobody calls inside the repository, and `missingInclude`, which reports system headers. The job enables `warning`, `style`, `performance` and `portability`, and the README shows how to add the rest locally.

### Does the job block merging?

It fails on a finding because of `--error-exitcode=1`, and whether a failed check blocks a merge is a branch-protection rule on the repository. The pull request names the job so it can be required, and leaves that setting to the maintainers.

## More CMake jobs

- [Add Dependabot to a CMake C++ Project](https://getrush.ai/run/add-dependabot/cmake/)
- [Add Doxygen API Docs to a CMake C++ Library](https://getrush.ai/run/add-doxygen-docs/cmake/)
- [Add libFuzzer Fuzz Tests to a CMake Project](https://getrush.ai/run/add-fuzz-tests/cmake/)

## More jobs like this: Hand off a long task

- [Add Crash Reporting to an Electron App](https://getrush.ai/run/add-crash-reporting/electron/)
- [Add Crash Reporting to an Expo App](https://getrush.ai/run/add-crash-reporting/expo/)
- [Add Crash Reporting to a Flutter App](https://getrush.ai/run/add-crash-reporting/flutter/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
