Corsa

Set up your project for metric visualization

This guide helps you generate and provide the data required by the CORSA Software Sustainability Metric Visualizer. You can upload local clang-tidy output or connect metrics from a CDash build.

Open metric visualizer Back to main page ←

Prerequisites

  • A C/C++ project with source code
  • CMake build system configured
  • clang-tidy installed and accessible
  • CTest configured CDash path only
  • CDash account or build URL CDash path only
  • A modern browser (Chrome or Firefox recommended)
Note: clang-tidy is commonly distributed with LLVM/Clang packages. Some systems may install it as a separate package. See the clang-tidy docs for installation details.

Setting up your project

The visualizer needs metric data produced from your project. The fastest path is uploading a local metrics file. For recurring builds or CI workflows, connect a CDash build.

Local file upload

Best for: Quick testing, one-time analysis, local experimentation

  1. Generate clang-tidy output
  2. Save the metrics file
  3. Upload it to the visualizer

CDash integration

Best for: Recurring builds, CI workflows, persistent project dashboards

  1. Configure CMake/CTest
  2. Submit results to CDash
  3. Connect the CDash build URL

Option A: Local file upload

Best for quick testing or one-time analysis.

1

Build or configure your project

Prepare your C/C++ project using your usual build workflow.

cmake -S . -B build
cmake --build build
2

Generate clang-tidy output

Run clang-tidy or your configured analysis workflow to generate metrics output.

clang-tidy path/to/file.cpp -- -Iinclude

For whole-project analysis, use run-clang-tidy with your compile commands database:

run-clang-tidy -p build/ 2>&1 | tee metrics.out
3

Save the output file

Save the generated output as a .out or .txt file. This is the file you will upload to the visualizer.

4

Upload to the visualizer

Open the Metric Visualizer, choose I have metrics file, and drag-and-drop or select your output file. Metrics will render immediately — no data leaves your browser.

Option B: CDash integration

Best for recurring builds and CI workflows.

1

Set up a CDash project

Create a project on my.cdash.org (or self-host). From your project's settings page, download the CTest config file — it becomes the base of your dashboard script.

2

Configure CMake/CTest

Download the submission template and append it to your dashboard client script, replacing the @@TOKEN@@ placeholders with your project values.

# Run your CTest dashboard script
ctest -S dashboard.cmake
3

Submit results to CDash

Run the dashboard script to configure, build, and upload clang-tidy results to your CDash instance. Confirm the build appears in your CDash project dashboard.

4

Connect the CDash build URL

Open the Metric Visualizer, choose I have CDash URL, and paste the URL of your CDash build. The visualizer will fetch and render any attached clang-tidy metrics.

Generate clang-tidy output

The visualizer expects clang-tidy analysis output that includes project, file, or function-level metrics enabled by the readability-function-cognitive-complexity and readability-function-size checks.

Warning: Large projects may take longer to analyze depending on the number of files and build configuration. Consider running analysis on a subset of files first.
Tip: If you want results to persist over time and be comparable across builds, use the CDash workflow instead of one-time file upload.

Using the Metric Visualizer

Providing Data

The visualizer supports three data input methods:

  • Local file upload — Drag and drop or select your clang-tidy output file. No data is sent to any server.
  • CDash build URL — Paste the URL of a specific CDash build. The visualizer fetches and renders any clang-tidy metrics attached to that build.
  • CDash project URL — Provide your CDash project's landing page URL and select a date range. All builds with clang-tidy output in that period are loaded.

Using the Dashboard

Once data is loaded, metrics are displayed per file (default), sorted by worst cognitive complexity score descending. Each entry is a collapsible row — click any row to see a breakdown of sub-metrics.

  • File view / Function view — Toggle between per-file and per-function displays using the View control.
  • Filters — Use the include/exclude filters to show only files or functions matching a name or path fragment.
  • Sort — Sort by cognitive complexity or any sub-metric, ascending or descending.

Data Alternatives

For a permanent deep-link to a specific CDash build's metrics, use query parameters to construct a direct URL:

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

Use bid to specify a CDash build ID and cdash to specify your CDash instance hostname. This is useful for embedding CI pipeline results in a README or release page.

Next steps

Once your data is ready, open the visualizer to explore project summary metrics, charts, and detailed file or function results.

Open metric visualizer Back to main page