C / C++

Qodana for C/C++ lets you analyze C and C++ projects containing compilation databases. This linter is based on the Clang-Tidy linter and works on the AMD64 and ARM64 architectures.

Qodana for C/C++ extends the existing Clang-Tidy inspections by supplying the Clang-Tidy and MISRA checks inspections provided by CLion.

Qodana for C/C++ is available under the Community, Ultimate, and Ultimate Plus licenses. However, the Clang-Tidy and MISRA checks inspections from CLion are available only under the Ultimate and Ultimate Plus licenses.

To see the list of supported features, navigate to the Supported features section.

How it works

The Docker image of Qodana for C/C++ employs Clang 16.0.0 and LLVM 16. You can see the Dockerfile for the detailed description of all software employed by the linter.

The linter searches for the compilation database file contained in the build/compile_commands.json file of the project directory and reads this file, analyzes the project, generates analysis reports, and saves them locally or uploads to Qodana Cloud.

Before you start

Prepare your project

Make sure that Clang-Tidy is deployed on your system. If necessary, install it using the LLVM website.
You can configure inspections in the .clang-tidy file, see the configuration example on the GitHub website. After configuring, save this file under the project root.
You can get the list of all available Clang-Tidy inspections using the following command:
clang-tidy -list-checks -checks="*"
./clang-tidy.exe -list-checks -checks="*"
To obtain the list of all inspections enabled in Clang-Tidy by default, you can run the following command:
clang-tidy -list-checks
./clang-tidy.exe -list-checks
Open the .clang-tidy file and configure the list of files and paths that will be analyzed by Qodana for C/C++.
If you already have the compile_commands.json file, you can also configure files and paths in this file.
Generate the compile_commands.json file as explained in the CLion documentation portal, and save it to the build directory under the project root.
If you use CMake, you can also generate a compilation database by specifying the following bootstrap option in the qodana.yaml file, for example:
bootstrap: mkdir -p build; cd build;cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .. || true
If your project requires specific packages not previously mentioned in the Dockerfile, add the following bootstrap command to your qodana.yaml file to install the required packages:
bootstrap: sudo apt-get update; sudo apt-get install -y <list of required packages> | rm -rf build; mkdir -p build; cd build;cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .. || true

Qodana Cloud

Because the Qodana for C/C++ linter may require a Qodana Cloud project token for identifying and verifying a license, follow these steps to obtain it:

Navigate to Qodana Cloud and create an account there.
In Qodana Cloud, create an organization, a team, and a project.
On the project card, you can find the project token that you will be using further in this section.

Prepare your software

On the Settings tab of the GitHub UI, create the QODANA_TOKEN encrypted secret and save the project token as its value.
On the Actions tab of the GitHub UI, set up a new workflow and save the following workflow configuration to the .github/workflows/code_quality.yml file:
name: Qodana on: workflow_dispatch: pull_request: push: branches: - main jobs: qodana: runs-on: ubuntu-latest permissions: contents: write pull-requests: write checks: write steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # to check out the actual pull request commit, not the merge commit fetch-depth: 0 # a full history is required for pull request analysis - name: 'Qodana Scan' uses: JetBrains/qodana-action@v2024.2 with: args: --linter,jetbrains/qodana-clang:2024.2-eap env: QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
This configuration sample will be modified throughout the section.

In Jenkins, make sure that these plugins are up and running:
- Docker and Docker Pipeline are required for running Docker images,
- Git is required for Git operations in Jenkins projects.
Make sure that Docker is installed and accessible to Jenkins.
If applicable, make sure that Docker is accessible to the jenkins user as described in the Manage Docker as a non-root user section of the Docker documentation.
In Jenkins, create the qodana-token credential and save the project token as its value.
In Jenkins, create a Multibranch Pipeline project as described on the Jenkins documentation portal.

Make sure that your project repository is accessible to GitLab CI/CD.
In GitLab CI/CD, create the $qodana_token variable and save the project token as its value.

In TeamCity, Create a project and a build configuration.

Install Docker on the machine you are going to run Qodana.

If you are using Linux, you should be able to run Docker under your current non-root user.

Follow the instructions from the Qodana CLI page on GitHub.

Run this command to pull the Docker image of the Qodana for C/C++ linter:

docker pull jetbrains/qodana-clang:2024.2-eap

Run Qodana

Based on the prerequisites, linter reads the build/compile_commands.json file and runs the Clang-Tidy tool.

To analyze the main branch, release branches and the pull requests coming to your repository, save this workflow configuration to the .github/workflows/code_quality.yml file:

              name: Qodana
              on:
                workflow_dispatch:
                pull_request:
                push:
                  branches: # Specify your branches here
                    - main # The 'main' branch
                    - 'releases/*' # The release branches
              jobs:
                qodana:
                  runs-on: ubuntu-latest
                  permissions:
                    contents: write
                    pull-requests: write
                    checks: write
                  steps:
                    - uses: actions/checkout@v3
                      with:
                        ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                        fetch-depth: 0  # a full history is required for pull request analysis
                    - name: 'Qodana Scan'
                      uses: JetBrains/qodana-action@v2024.2
                      with:
                        args: --linter,jetbrains/qodana-clang:2024.2-eap
                      env:
                        QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
          

Here, fetch-depth: 0 is required for checkout in case Qodana works in pull request mode (reports issues that appeared only in that pull request).

To override the location of a compilation command database, you can specify the location for the compile_commands.json file relatively to the project root, so the configuration will look like:

              name: Qodana
              on:
                workflow_dispatch:
                pull_request:
                push:
                  branches: # Specify your branches here
                    - main # The 'main' branch
                    - 'releases/*' # The release branches
              jobs:
                qodana:
                  runs-on: ubuntu-latest
                  permissions:
                    contents: write
                    pull-requests: write
                    checks: write
                  steps:
                    - uses: actions/checkout@v3
                      with:
                        ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                        fetch-depth: 0  # a full history is required for pull request analysis
                    - name: 'Qodana Scan'
                      uses: JetBrains/qodana-action@v2024.2
                      with:
                        args: --linter,jetbrains/qodana-clang:2024.2-eap,--compile-commands,<path-to-compile_commands.json>
                      env:
                        QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
          

More configuration examples are available in the GitHub Actions section.

Save this snippet to the Jenkinsfile:

            pipeline {
                environment {
                    QODANA_TOKEN=credentials('qodana-token')
                }
                agent {
                    docker {
                        args '''
                          -v "${WORKSPACE}":/data/project
                          --entrypoint=""
                          '''
                        image 'jetbrains/qodana-clang:2024.2-eap'
                    }
                }
                stages {
                    stage('Qodana') {
                        steps {
                            sh '''qodana'''
                        }
                    }
                }
            }
        

To override the location of a compilation command database, you can specify the location for the compile_commands.json file relatively to the project root, so the configuration will look like:

            pipeline {
                environment {
                    QODANA_TOKEN=credentials('qodana-token')
                }
                agent {
                    docker {
                        args '''
                          -v "${WORKSPACE}":/data/project
                          --entrypoint=""
                          '''
                        image 'jetbrains/qodana-clang:2024.2-eap'
                    }
                }
                stages {
                    stage('Qodana') {
                        steps {
                            sh '''
                            qodana \
                            --compile-commands <path-to-compile_commands.json>
                            '''
                        }
                    }
                }
            }
        

More configuration examples are available in the Jenkins section.

In the root directory of your project, save this snippet to the .gitlab-ci.yml file:

            qodana:
               image:
                  name: jetbrains/qodana-clang:2024.2-eap 
                  entrypoint: [""]
               cache:
                  - key: qodana-2024.2-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
                    fallback_keys:
                       - qodana-2024.2-$CI_DEFAULT_BRANCH-
                       - qodana-2024.2-
                    paths:
                       - .qodana/cache
               variables:
                  QODANA_TOKEN: $qodana_token           - 
               script:
                  - qodana --cache-dir=$CI_PROJECT_DIR/.qodana/cache
        

In this snippet:

The cache keyword configures GitLab CI/CD caches to store the Qodana cache, so subsequent runs will be faster,
The script keyword runs the qodana command and enumerates the Qodana configuration options described in the Shell commands section,
The variables keyword defines the QODANA_TOKEN variable referring to the project token.

To override the location of a compilation command database, you can specify the location for the compile_commands.json file relatively to the project root, so the configuration will look like:

            qodana:
               image:
                  name: jetbrains/qodana-clang:2024.2-eap 
                  entrypoint: [""]
               cache:
                  - key: qodana-2024.2-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
                    fallback_keys:
                       - qodana-2024.2-$CI_DEFAULT_BRANCH-
                       - qodana-2024.2-
                    paths:
                       - .qodana/cache
               variables:
                  QODANA_TOKEN: $qodana_token           - 
               script:
                  - qodana --cache-dir=$CI_PROJECT_DIR/.qodana/cache --compile-commands <path-to-compile_commands.json>
        

More configuration examples are available in the GitLab CI/CD section.

In the TeamCity UI, navigate to the configuration page of a build where you would like to run Qodana.
On the Build Configuration Settings page, navigate to the Build steps page.
On the Build steps page, click the Add build step button.
On the page that opens, select the Qodana runner.
On the New Build Step: Qodana page, click Show advanced options and configure the Qodana runner:
- Step name uniquely identifies this step among other build steps.
- Step ID uniquely identifies this step among other build steps.
- Execute step configures the build condition that will trigger this build step.
- Working directory sets the directory for the build process, see the TeamCity documentation for details. You can leave this field empty if the Checkout directory parameter is specified on the Version Control Settings tab.
- Report ID uniquely identifies the report to let you distinguish between multiple reports when several inspection steps are configured within a single build.
- The Forward reports to TeamCity tests checkbox configures Qodana report availability in the Test tab of the TeamCity UI. Using this option, you can view codebase problems along with other problems detected.
- Linter configures the Qodana linter.
  Here, select Custom and in the field below specify the Qodana for C/C++ linter.
- Version is by default set to Latest.
- Inspection profile defines an inspection profile:
  - Recommended (default) is one of the default profiles.
  - Embedded profile lets you select a default profile, see the Existing Qodana profiles section for details.
  - Path to the IntelliJ profile lets you specify the path to your custom profile. To use this option, make sure that you also configure the custom profile in the qodana.yaml file.
- Cloud Token configures a project token generated in Qodana Cloud.
- Additional Docker arguments configures the arguments accepted by a Docker image, see the Shell commands section for details.
- Additional Qodana arguments lets you extend the default Qodana functionality, see the Options section for details.
  To override the location of a compilation command database, specify the location relatively to the project root using the --compile-commands <path-to-compile_commands.json> command.
Click the Save button.

More configuration examples are available in the TeamCity section.

Run this command:

            docker run \
               -v <source-directory>/:/data/project/ \
               -v <output-directory>/:/data/results/ \
               -e QODANA_TOKEN="<cloud-project-token>" \
               jetbrains/qodana-clang:2024.2-eap
        

In this command, source-directory and output-directory are full local paths to the project source code directory and the analysis result directory, respectively. The QODANA_TOKEN variable refers to the project token required by the Ultimate and Ultimate Plus linters. If you omit the QODANA_TOKEN variable, the inspection results will be available in the qodana.sarif.json file saved in the output-directory of your project root.

To override the location of a compilation command database, you can specify the location for the compile_commands.json file relatively to the project root, so the Docker command will look like:

            docker run \
               -v <source-directory>/:/data/project/ \
               -v <output-directory>/:/data/results/ \
               -e QODANA_TOKEN="<cloud-project-token>" \
               jetbrains/qodana-clang:2024.2-eap \
               --compile-commands <path-to-compile_commands.json>
        

In your browser, open Qodana Cloud to examine the analysis results and reconfigure the analysis. See the Inspection report section of the documentation for full details.

If you run the analysis several times in a row, make sure you've cleaned the results directory before using it in docker run again.

Explore analysis results

Once Qodana analyzed your project and uploaded the analysis results to Qodana Cloud, in Qodana Cloud navigate to your project and review the analysis results report.

To learn more about Qodana report UI, see the Inspection report section.

Extend Qodana configuration

Adjusting the scope of analysis

Qodana recognizes the qodana.yaml file for the analysis configuration, so that you don't need to pass any additional parameters. For Qodana for C/C++, you can configure:

Inspections using the include and exclude options. See the YAML file section for details.
Commands that will run before the linter using the boostrap option.
Baseline and quality gate features.

Enabling the baseline feature

You can skip analysis for specific problems by using the baseline feature. Information about a baseline is contained in a SARIF-formatted file.

Save this snippet to the .github/workflows/code_quality.yml file:

          name: Qodana
          on:
            workflow_dispatch:
            pull_request:
            push:
              branches: # Specify your branches here
                - main # The 'main' branch
                - master # The 'master' branch
                - 'releases/*' # The release branches
          jobs:
            qodana:
              runs-on: ubuntu-latest
              permissions:
                contents: write
                pull-requests: write
                checks: write
              steps:
                - uses: actions/checkout@v3
                  with:
                    ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
                    fetch-depth: 0  # a full history is required for pull request analysis
                - name: 'Qodana Scan'
                  uses: JetBrains/qodana-action@v2024.2
                  with:
                    args: --linter,jetbrains/qodana-clang:2024.2-eap,--baseline,<path/to/qodana.sarif.json>
                  env:
                    QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
      

This snippet has the args: --baseline,<path/to/qodana.sarif.json> line that specifies the path to the SARIF file containing a baseline.

The stages block contains the --baseline <path/to/qodana.sarif.json> line that specifies the path to the SARIF-formatted baseline file:

        pipeline {
            environment {
                QODANA_TOKEN=credentials('qodana-token')
            }
            agent {
                docker {
                    args '''
                      -v "${WORKSPACE}":/data/project
                      --entrypoint=""
                      '''
                    image 'jetbrains/qodana-clang:2024.2-eap'
                }
            }
            stages {
                stage('Qodana') {
                    steps {
                        sh '''
                        qodana \
                        --baseline <path/to/qodana.sarif.json>
                        '''
                    }
                }
            }
        }
      

The --baseline <path/to/qodana.sarif.json> line in the script block invokes the baseline feature.

        qodana:
           image:
              name: jetbrains/qodana-clang:2024.2-eap 
              entrypoint: [""]
           cache:
              - key: qodana-2024.2-$CI_DEFAULT_BRANCH-$CI_COMMIT_REF_SLUG
                fallback_keys:
                   - qodana-2024.2-$CI_DEFAULT_BRANCH-
                   - qodana-2024.2-
                paths:
                   - .qodana/cache
           variables:
              QODANA_TOKEN: $qodana_token           - 
           script:
              - qodana --baseline <path/to/qodana.sarif.json> --results-dir=$CI_PROJECT_DIR/.qodana/results
                 --cache-dir=$CI_PROJECT_DIR/.qodana/cache
      

In the TeamCity UI, navigate to the configuration page of a build where you would like to run Qodana.
On the Build Configuration Settings page, navigate to the Build steps page.
On the Build steps page, click the Add build step button.
On the page that opens, select the Qodana runner.
On the New Build Step: Qodana page, click Show advanced options and configure the Qodana runner:
- Step name uniquely identifies this step among other build steps.
- Step ID uniquely identifies this step among other build steps.
- Execute step configures the build condition that will trigger this build step.
- Working directory sets the directory for the build process, see the TeamCity documentation for details. You can leave this field empty if the Checkout directory parameter is specified on the Version Control Settings tab.
- Report ID uniquely identifies the report to let you distinguish between multiple reports when several inspection steps are configured within a single build.
- The Forward reports to TeamCity tests checkbox configures Qodana report availability in the Test tab of the TeamCity UI. Using this option, you can view codebase problems along with other problems detected.
- Linter configures the Qodana linter.
  Here, select Custom and in the field below specify the Qodana for C/C++ linter.
- Version is by default set to Latest.
- Inspection profile defines an inspection profile:
  - Recommended (default) is one of the default profiles.
  - Embedded profile lets you select a default profile, see the Existing Qodana profiles section for details.
  - Path to the IntelliJ profile lets you specify the path to your custom profile. To use this option, make sure that you also configure the custom profile in the qodana.yaml file.
- Cloud Token configures a project token generated in Qodana Cloud.
- Additional Docker arguments configures the arguments accepted by a Docker image, see the Shell commands section for details.
- Additional Qodana arguments lets you extend the default Qodana functionality, see the Options section for details.
  In this field, specify the baseline feature using the --baseline <path/to/qodana.sarif.json> option.
Click the Save button.

Run this command invoking the --baseline option:

              docker run \
                 -v <source-directory>/:/data/project/ \
                 -v <path_to_baseline>:/data/base/ \
                 -e QODANA_TOKEN="<cloud-project-token>" \
                 jetbrains/qodana-clang:2024.2-eap \
                 --baseline /data/base/<path-relative-to-project-dir>/qodana.sarif.json
          

Enabling the quality gate

You can configure quality gates for:

The total number of project problems,
Multiple quality gates for problem severities.

Save this snippet to the qodana.yaml file:

failureConditions:
  severityThresholds:
    any: 50 # Total number of problems in all severities
    critical: 1 # Severities
    high: 2
    moderate: 3
    low: 4
    info: 5

Supported features

The Qodana for C/C++ linter provides the following Qodana features:

Feature	Available under licenses
Baseline	Community, Ultimate and Ultimate Plus
Quality gate	Community, Ultimate and Ultimate Plus

Usage statistics

According to the JetBrains EAP user agreement, we can use third-party services to analyze the usage of our features to further improve the user experience. All data is collected anonymously. To disable the statistics, use the --no-statistics=true CLI option.

Last modified: 25 September 2024