Setup your project for metric visualization

• A C/C++ project
• CMake
• run-clang-tidy

Note: run-clang-tidy is typically distributed as part of clang-tidy for use on compliation databases

Note: A CMake build system is assumed for use with CTest, CDash, and to obtain the compile_commands.json file run-clang-tidy consumes. However clang-tidy can be invoked on projects using any build system if care is taken to produce a compatible clang tidy analysis output file.

Producing Metrics

The files required for this software metric visualization are produced by running clang-tidy on a codebase (or single file). This can be done numerous ways, of which we will cover two here but so long as a compatible clang-tidy output file is produced, the mechanism by which that file is generated is immaterial with regard to using this dashboard.

CTest && CDash

CTest is one of the easiest ways to drive the production of a clang-tidy analysis output file.
If you're not currently using CTest with your CMake system, no problem, you can configure a CTest dashboard client setup without needing to define any tests. This template contains CML code that can be copy and pasted into an existing CTest dashboard client script to produce clang-tidy output. If you're not already using CDash for your CMake projects, follow the instructions below to set that up.
Download that gist, replace the boilerplate entries that need replacing (should be denoted by @@ on either side of the token that needs replacing) append it to your dashboard script, and run `ctest -S <script name>. This should upload a compatible clang-tidy output file to your CDash instance, and you're ready to use the dashboard.

CMake Script Mode/Manual

If you do not have an existing CTest/CDash configuration, you can easily produce the required clang-tidy output file by simply downloading the gist linked above, running the CMake Language Code as a standalone script via `cmake -p` (after following the environmental setup instructions) and produce a compatible clang-tidy output file, which can be uploaded to the dashboard manually.

Similarly, if you do not use CMake at all, you can run clang-tidy as you see fit, compose the output into a single file, and that should be compatible with this dashboard.

CDash instances can be self hosted a number of ways, but we will only cover using my.cdash.org here, as it is a publically available CDash instance

To create an account and initial project on CDash, follow the getting started instructions here.
Once complete, you now have an established CDash project! Lets get some builds on there. To configure your CMake project to work with CDash, we create what is called a CTest Dashboard client script, this is just a CMake Language script that CTest will execute and submit the results of to your CDash instance.
For a very detailed description of what that entails, you can visit the CMake Docs, but for the purposes of this guide, we'll just be creating a very basic driver script.
From the landing page for your CDash project, click the setting tab in the upper right hand corner, and select the "project" dropdown option. From the project settings page, click the "Miscellaneous" tab. The first "setting" should be one that says "Download CTest Config", and to the right should be a file url. Download that CML file, it will form the base of your dashboard submission script. You'll then want to download the gist linked above, and incorporate the rest of the CML code from that gist into your dasboard client script. Once that is done, you can simply run `ctest -S <script name>` and you should see CTest drive the configure, build, and upload to CDash from your project.

Providing Data

The landing page of the visualizer contains a UI to provide the visualizer with the software analysis output it will use to create the visualization. There are two options for uploading this information to the visualizer:

• Local File Upload
• CDash Build URL

You can also provide the dashboard a CDash project url (the url for the CDash landing page for a project). The visualizer will then provide a calendar to select a range, or single date. The dashboard will then fetch all available clang-tidy build metrics from those dates and render the data for each build within the given date range that has a valid clang-tidy output file.

Using the Dashboard

Once the data has been loaded, you can begin to view it. To begin, the metrics are displayed per file, starting with the worst metric score, and descending to the best. Each data entry in the UI is a clickable dropdown. Clicking the item will display a breakdown of sub-metrics that compose the larger score. The top of the UI will contain the averages of each of these sub-metrics for the entirety of the project data that was uploaded.

There are two views, by file, and by function. By file is the default and will display the metrics for each file. The function view can be toggled via the "view" UI, and displays the metrics for each function, and associates the function with its file.

The displayed functions/files can be filtered via the include and exclude filters. Including a string in one of these filters will display either only file names or function signatures containing that string or only those not containing said string dependent on the selected filter.

The data can also be sorted, by default this is done on the cognitive-complexity metric, but can be switched to any of the available sub-metrics. The displayed sort order can also be toggled between ascending and descending.

Data Alternatives

If you would like a dashboard that permanently points to your clang-tidy results, as they are available in CDash, you can simply use query parameters to construct the url to the dashboard like so

https://corsa.center/dashboard/explore/project-metrics/metrics/index.html?bid=3127130&cdash=my.cdash.org

bid

cdash