codechecker-analysis-action/README.md

# [CodeChecker](http://github.com/Ericsson/CodeChecker/) C++ static analysis action

GitHub Action to execute static analysis over C-family projects (C, C++,
Objective-C) using the [Clang](http://clang.llvm.org/) infrastructure and
[CodeChecker](http://github.com/Ericsson/CodeChecker/) as its driver.

## Overview

⚠️ **CAUTION! This action has been written with commands that target Ubuntu-based distributions!**

This single action composite script encompasses the following steps:

  1. Obtain a package of the LLVM Clang suite's analysers, and CodeChecker.

ℹ️ **Note:** Static analysis can be a time-consuming process.
It's recommended that the static analysis step is not sequential with the rest of a CI execution, but either runs as its own job in a workflow, or a completely distinct workflow altogether.

Please ensure that your project is completely configured for a build before executing this action.

ℹ️ **Note:** Static analysers can rely on additional information that is optimised out in a true release build.
Hence, it's recommended to configure your project in a **`Debug`** configuration.

Add the job into your CI as follows.
The two versions are mutually exclusive — you either can give a compilation database, or you instruct CodeChecker to create one.

### Project can generate a [JSON Compilation Database](http://clang.llvm.org/docs/JSONCompilationDatabase.html) and build cleanly (no generated code)

Some projects are trivial enough in their build configuration that no additional steps need to be taken after executing `configure.sh`, `cmake`, or similar tools.
If you are able to generate a *compilation database* from your build system **without** running the build itself, you can save some time, and go to the analysis immediately.

You can specify the generated compilation database in the `logfile` variable 

~~~{.yml}
runs:
  steps:
    # Check YOUR project out!
    - name: "Check out repository"
      uses: actions/checkout@v2

    # Prepare a build
    - name: "Prepare build"
      run: |
        mkdir -pv Build
        cd Build
        cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

    # Run the analysis
    - uses: whisperity/codechecker-analysis-action
      with:
        logfile: ${{ github.workspace }}/Build/compile_commands.json
~~~

### Projects that need to self-creating a *JSON Compilation Database* or require generated code

Other kinds of projects might rely heavily on *generated code*.
When looking at the source code of these projects **without** a build having been executed beforehand, they do not compile — as such, analysis cannot be executed either.

In this case, you will need to instruct CodeChecker to log a build (and spend time doing the build) just before analysis.

You can specify the build to execute in the `build-command` variable.

~~~{.yml}
runs:
  steps:
    # Check YOUR project out!
    - name: "Check out repository"
      uses: actions/checkout@v2

    # Prepare a build
    - name: "Prepare build"
      run: |
        mkdir -pv Build
        cd Build
        cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=OFF

    # Run the analysis
    - uses: whisperity/codechecker-analysis-action
      with:
        build-command: "cd ${{ github.workspace }}/Build; cmake --build ."
~~~


## Action configuration

| Variable | Default                             | Description                                                                                                                                                                                                                                                                                                                                                  |
|----------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `config` | `$(project-root)/.codechecker.json` | The configuration file containing flags to be appended to the analysis commands. It is recommended that most of the analysis configuration is versioned with the project. 🔖 Read more about the [`codechecker.json`](http://codechecker.readthedocs.io/en/latest/analyzer/user_guide/#configuration-file) configuration file in the official documentation. |

### Versions to install

| Variable       | Default                                                          | Description                                                                                                                                                                                                    |
|----------------|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `repository`   | [`Ericsson/CodeChecker`](http://github.com/Ericsson/CodeChecker) | The CodeChecker repository to check out and build                                                                                                                                                              |
| `version`      | `master`                                                         | The branch, tag, or commit SHA in the `repository` to use.                                                                                                                                                     |
| `llvm-version` | `latest`                                                         | The major version of LLVM to install and use. LLVM is installed from [PPA](http://apt.llvm.org/). If `latest`, automatically gather the latest version. If `ignore`, don't install anything. (Not recommended) |

### Build log configuration

🔖 Read more about [`CodeChecker log`](http://codechecker.readthedocs.io/en/latest/analyzer/user_guide/#log) in the official documentation.

| Variable        | Default | Description                                                                                                                                                                                                                          |
|-----------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `logfile`       |         | The location of the JSON Compilation Database which describes how the project is built. This flag is used if the build system can pre-generate the file for us.                                                                      |
| `build-command` |         | The build command to execute. CodeChecker is capable of executing and logging the build for itself. This flag is used if the build-system can not generate the information by itself, or the project relies on other generated code. |