[llvm] [Docs][TestSuite] Document additional debugify option for test suite (PR #206454)

[Stephen Tozer via llvm-commits]

https://github.com/SLTozer updated https://github.com/llvm/llvm-project/pull/206454

>From e9cc2efe890360a736f739d2c4753e7f2cc2f691 Mon Sep 17 00:00:00 2001
From: Stephen Tozer <stephen.tozer at sony.com>
Date: Fri, 26 Jun 2026 17:33:55 +0100
Subject: [PATCH 1/5] [Docs][TestSuite] Document additional debugify option for
 llvm-test-suite

This patch adds documentation for the changes at:
https://github.com/llvm/llvm-test-suite/pull/432

The llvm-test-suite changes add a new CMake flag that enables the collection
of Debugify location coverage stats using the coverage+origin tracking
feature. When enabled, a wrapper script will be invoked that runs a
coverage-tracking build for all compile commands, and then follows with a
second origin-tracking build if any coverage failures are detected,
accumulating the results into a single report file at
`<build-dir>/debugify-report.json`. For more information on the
implementation, see the above PR.
---
 llvm/docs/TestSuiteGuide.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md
index cdd5ae72204ab..220bbc99a68df 100644
--- a/llvm/docs/TestSuiteGuide.md
+++ b/llvm/docs/TestSuiteGuide.md
@@ -281,6 +281,19 @@ benchmarks. CMake can print a list of them:
   more information about expected versions or usage in the README files in the
   `External` directory (such as `External/SPEC/README`)
 
+- `TEST_SUITE_COLLECT_DEBUGIFY_LOC_COVERAGE`
+
+  If this is set to `ON` then LLVM will use DebugLoc coverage and origin
+  tracking to produce a report of unexpectedly missing debug locations,
+  accumulating bugs from all C/C++ compilations in the file
+  `<build-dir>/debugify-report.json`; this report can be prettified by using the
+  `llvm/utils/llvm-original-di-preservation.py` script (documented
+  [here](project:HowToUpdateDebugInfo.md#test-original-debug-info-preservation-in-optimizations)).
+  This requires the C and C++ compilers to be a version of Clang built with the
+  feature `LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING=COVERAGE_AND_ORIGIN` (see
+  [here](project:HowToUpdateDebugInfo.md#using-coverage-tracking-to-remove-false-positives)
+  for more info).
+
 ### Common CMake Flags
 
 - `-GNinja`

>From d4bdbc1f195fdc4d9f079681d4875fe6be9af01b Mon Sep 17 00:00:00 2001
From: Stephen Tozer <stephen.tozer at sony.com>
Date: Mon, 6 Jul 2026 13:34:14 +0100
Subject: [PATCH 2/5] Correct .md -> .rst

---
 llvm/docs/TestSuiteGuide.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md
index 220bbc99a68df..558e2c956f464 100644
--- a/llvm/docs/TestSuiteGuide.md
+++ b/llvm/docs/TestSuiteGuide.md
@@ -288,10 +288,10 @@ benchmarks. CMake can print a list of them:
   accumulating bugs from all C/C++ compilations in the file
   `<build-dir>/debugify-report.json`; this report can be prettified by using the
   `llvm/utils/llvm-original-di-preservation.py` script (documented
-  [here](project:HowToUpdateDebugInfo.md#test-original-debug-info-preservation-in-optimizations)).
+  [here](project:HowToUpdateDebugInfo.rst#test-original-debug-info-preservation-in-optimizations)).
   This requires the C and C++ compilers to be a version of Clang built with the
   feature `LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING=COVERAGE_AND_ORIGIN` (see
-  [here](project:HowToUpdateDebugInfo.md#using-coverage-tracking-to-remove-false-positives)
+  [here](project:HowToUpdateDebugInfo.rst#using-coverage-tracking-to-remove-false-positives)
   for more info).
 
 ### Common CMake Flags

>From 78f52b1f4dfdf366029565e0a846e50bc576f962 Mon Sep 17 00:00:00 2001
From: Stephen Tozer <stephen.tozer at sony.com>
Date: Mon, 6 Jul 2026 13:45:35 +0100
Subject: [PATCH 3/5] Use explicit label in doc ref

---
 llvm/docs/TestSuiteGuide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md
index 558e2c956f464..f434fbfd64058 100644
--- a/llvm/docs/TestSuiteGuide.md
+++ b/llvm/docs/TestSuiteGuide.md
@@ -288,7 +288,7 @@ benchmarks. CMake can print a list of them:
   accumulating bugs from all C/C++ compilations in the file
   `<build-dir>/debugify-report.json`; this report can be prettified by using the
   `llvm/utils/llvm-original-di-preservation.py` script (documented
-  [here](project:HowToUpdateDebugInfo.rst#test-original-debug-info-preservation-in-optimizations)).
+  [here](project:HowToUpdateDebugInfo.rst#OriginalDI)).
   This requires the C and C++ compilers to be a version of Clang built with the
   feature `LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING=COVERAGE_AND_ORIGIN` (see
   [here](project:HowToUpdateDebugInfo.rst#using-coverage-tracking-to-remove-false-positives)

>From f32dfc8580e2295181e3d54ec0567c0a934cc106 Mon Sep 17 00:00:00 2001
From: Stephen Tozer <stephen.tozer at sony.com>
Date: Wed, 8 Jul 2026 15:39:08 +0100
Subject: [PATCH 4/5] Fixup label references

---
 llvm/docs/HowToUpdateDebugInfo.rst | 2 ++
 llvm/docs/TestSuiteGuide.md        | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst
index d062010ecdb36..743ff6c723eb8 100644
--- a/llvm/docs/HowToUpdateDebugInfo.rst
+++ b/llvm/docs/HowToUpdateDebugInfo.rst
@@ -428,6 +428,8 @@ tests. Changes to this pass are not allowed to break existing tests.
    check lines. In cases where this can't be avoided (say, if a test wouldn't
    be precise enough), moving the test to its own file is preferred.
 
+.. _DebugifyCoverageTracking:
+
 Using Coverage Tracking to remove false positives
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md
index f434fbfd64058..a11038e98c3eb 100644
--- a/llvm/docs/TestSuiteGuide.md
+++ b/llvm/docs/TestSuiteGuide.md
@@ -288,10 +288,10 @@ benchmarks. CMake can print a list of them:
   accumulating bugs from all C/C++ compilations in the file
   `<build-dir>/debugify-report.json`; this report can be prettified by using the
   `llvm/utils/llvm-original-di-preservation.py` script (documented
-  [here](project:HowToUpdateDebugInfo.rst#OriginalDI)).
+  {ref}`here <OriginalDI>`).
   This requires the C and C++ compilers to be a version of Clang built with the
   feature `LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING=COVERAGE_AND_ORIGIN` (see
-  [here](project:HowToUpdateDebugInfo.rst#using-coverage-tracking-to-remove-false-positives)
+  {ref}`here <DebugifyCoverageTracking>`)
   for more info).
 
 ### Common CMake Flags

>From 5b531966f6728bd889abddda47073c81b3ff95d3 Mon Sep 17 00:00:00 2001
From: Stephen Tozer <stephen.tozer at sony.com>
Date: Wed, 8 Jul 2026 16:08:54 +0100
Subject: [PATCH 5/5] Remove extra parenthesis

---
 llvm/docs/TestSuiteGuide.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md
index a11038e98c3eb..22ff94c6525d7 100644
--- a/llvm/docs/TestSuiteGuide.md
+++ b/llvm/docs/TestSuiteGuide.md
@@ -291,8 +291,7 @@ benchmarks. CMake can print a list of them:
   {ref}`here <OriginalDI>`).
   This requires the C and C++ compilers to be a version of Clang built with the
   feature `LLVM_ENABLE_DEBUGLOC_COVERAGE_TRACKING=COVERAGE_AND_ORIGIN` (see
-  {ref}`here <DebugifyCoverageTracking>`)
-  for more info).
+  {ref}`here <DebugifyCoverageTracking>` for more info).
 
 ### Common CMake Flags