[clang-tools-extra] [clang-include-cleaner] Generalize analyze() to accept callbacks and deprecate the old overload and AnalysisResults (PR #241509)
via cfe-commits
cfe-commits at lists.llvm.org
Wed Nov 11 17:52:41 PST 2026
https://github.com/higher-performance updated https://github.com/llvm/llvm-project/pull/241509
>From 17f7325769b3e03b3b8cafb73e1f8fb682f47a05 Mon Sep 17 00:00:00 2001
From: higher-performance <higher.performance.github at gmail.com>
Date: Wed, 11 Nov 2026 15:54:23 -0500
Subject: [PATCH] [clang-include-cleaner] Generalize analyze() to accept
callbacks and provide more information to enable efficient
cross-translation-unit analysis
---
.../include/clang-include-cleaner/Analysis.h | 19 +++-
.../include-cleaner/lib/Analysis.cpp | 92 ++++++++++++-------
2 files changed, 78 insertions(+), 33 deletions(-)
diff --git a/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h b/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h
index c3241763237d14..b2edaec5c0581d 100644
--- a/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h
+++ b/clang-tools-extra/include-cleaner/include/clang-include-cleaner/Analysis.h
@@ -22,6 +22,7 @@
#include "llvm/ADT/StringRef.h"
#include <string>
#include <utility>
+#include <vector>
namespace clang {
class SourceLocation;
@@ -71,8 +72,24 @@ struct AnalysisResults {
/// This exposes conclusions but not reasons: use lower-level walkUsed for that.
///
/// The HeaderFilter is a predicate that receives absolute path or spelling
-/// without quotes/brackets, when a phyiscal file doesn't exist.
+/// without quotes/brackets, when a physical file doesn't exist.
/// No analysis will be performed for headers that satisfy the predicate.
+///
+/// The UnusedHeaderCallback is called for every header that is unused.
+///
+/// The Callback is called for every symbol reference. The Header pointer is
+/// NULL for every missing #include. Note that the Header pointer is temporary
+/// and might not survive the callback.
+void analyze(
+ llvm::ArrayRef<Decl *> ASTRoots, llvm::ArrayRef<SymbolReference> MacroRefs,
+ const Includes &Inc, const PragmaIncludes *PI, const Preprocessor &PP,
+ llvm::function_ref<bool(llvm::StringRef)> HeaderFilter,
+ llvm::function_ref<void(const Include *)> UnusedHeaderCallback,
+ llvm::function_ref<void(const Header *, const Include *,
+ llvm::StringRef Spelling, const SymbolReference &,
+ llvm::ArrayRef<Header> Providers)>
+ Callback);
+
AnalysisResults
analyze(llvm::ArrayRef<Decl *> ASTRoots,
llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &I,
diff --git a/clang-tools-extra/include-cleaner/lib/Analysis.cpp b/clang-tools-extra/include-cleaner/lib/Analysis.cpp
index 922a690dfc47cb..f22364ef6fa9f9 100644
--- a/clang-tools-extra/include-cleaner/lib/Analysis.cpp
+++ b/clang-tools-extra/include-cleaner/lib/Analysis.cpp
@@ -87,36 +87,41 @@ void walkUsed(llvm::ArrayRef<Decl *> ASTRoots,
}
}
-AnalysisResults
-analyze(llvm::ArrayRef<Decl *> ASTRoots,
- llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &Inc,
- const PragmaIncludes *PI, const Preprocessor &PP,
- llvm::function_ref<bool(llvm::StringRef)> HeaderFilter) {
+void analyze(
+ llvm::ArrayRef<Decl *> ASTRoots, llvm::ArrayRef<SymbolReference> MacroRefs,
+ const Includes &Inc, const PragmaIncludes *PI, const Preprocessor &PP,
+ llvm::function_ref<bool(llvm::StringRef)> HeaderFilter,
+ llvm::function_ref<void(const Include *)> UnusedHeaderCallback,
+ llvm::function_ref<void(const Header *, const Include *,
+ llvm::StringRef Spelling, const SymbolReference &,
+ llvm::ArrayRef<Header> Providers)>
+ Callback) {
auto &SM = PP.getSourceManager();
const auto MainFile = *SM.getFileEntryRefForID(SM.getMainFileID());
llvm::DenseSet<const Include *> Used;
- llvm::StringMap<Header> Missing;
constexpr auto DefaultHeaderFilter = [](llvm::StringRef) { return false; };
if (!HeaderFilter)
HeaderFilter = DefaultHeaderFilter;
OptionalDirectoryEntryRef ResourceDir =
PP.getHeaderSearchInfo().getModuleMap().getBuiltinDir();
walkUsed(ASTRoots, MacroRefs, PI, PP,
- [&](const SymbolReference &Ref, llvm::ArrayRef<Header> Providers) {
- bool Satisfied = false;
+ [=, &Used, &PP, &Inc](const SymbolReference &Ref,
+ llvm::ArrayRef<Header> Providers) {
+ std::pair<const Header *, const Include *> Satisfied;
for (const Header &H : Providers) {
if (H.kind() == Header::Physical &&
(H.physical() == MainFile ||
H.physical().getDir() == ResourceDir)) {
- Satisfied = true;
+ Satisfied = {&H, nullptr};
}
for (const Include *I : Inc.match(H)) {
Used.insert(I);
- Satisfied = true;
+ Satisfied = {&H, I};
}
}
// Bail out if we can't (or need not) insert an include.
- if (Satisfied || Providers.empty() || Ref.RT != RefType::Explicit)
+ if (Satisfied.first || Providers.empty() ||
+ Ref.RT != RefType::Explicit)
return;
if (HeaderFilter(Providers.front().resolvedPath()))
return;
@@ -126,36 +131,59 @@ analyze(llvm::ArrayRef<Decl *> ASTRoots,
// refers to it.
auto Spelling = spellHeader(
{Providers.front(), PP.getHeaderSearchInfo(), MainFile});
- for (const Include *I : Inc.match(Header{Spelling})) {
+ Header similar_header(Spelling);
+ for (const Include *I : Inc.match(similar_header)) {
Used.insert(I);
- Satisfied = true;
+ Satisfied = {&similar_header, I};
+ }
+ if (Callback) {
+ Callback(Satisfied.first, Satisfied.second, Spelling, Ref,
+ Providers);
}
- if (!Satisfied)
- Missing.try_emplace(std::move(Spelling), Providers.front());
});
- AnalysisResults Results;
- for (const Include &I : Inc.all()) {
- if (Used.contains(&I) || !I.Resolved ||
- HeaderFilter(I.Resolved->getName()) ||
- I.Resolved->getDir() == ResourceDir)
- continue;
- if (PI) {
- if (PI->shouldKeep(*I.Resolved))
+ if (UnusedHeaderCallback) {
+ for (const Include &I : Inc.all()) {
+ if (Used.contains(&I) || !I.Resolved ||
+ HeaderFilter(I.Resolved->getName()) ||
+ I.Resolved->getDir() == ResourceDir)
continue;
- // Check if main file is the public interface for a private header. If so
- // we shouldn't diagnose it as unused.
- if (auto PHeader = PI->getPublic(*I.Resolved); !PHeader.empty()) {
- PHeader = PHeader.trim("<>\"");
- // Since most private -> public mappings happen in a verbatim way, we
- // check textually here. This might go wrong in presence of symlinks or
- // header mappings. But that's not different than rest of the places.
- if (MainFile.getName().ends_with(PHeader))
+ if (PI) {
+ if (PI->shouldKeep(*I.Resolved))
continue;
+ // Check if main file is the public interface for a private header. If
+ // so we shouldn't diagnose it as unused.
+ if (auto PHeader = PI->getPublic(*I.Resolved); !PHeader.empty()) {
+ PHeader = PHeader.trim("<>\"");
+ // Since most private -> public mappings happen in a verbatim way, we
+ // check textually here. This might go wrong in presence of symlinks
+ // or header mappings. But that's not different than rest of the
+ // places.
+ if (MainFile.getName().ends_with(PHeader))
+ continue;
+ }
}
+ UnusedHeaderCallback(&I);
}
- Results.Unused.push_back(&I);
}
+}
+
+AnalysisResults
+analyze(llvm::ArrayRef<Decl *> ASTRoots,
+ llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &Inc,
+ const PragmaIncludes *PI, const Preprocessor &PP,
+ llvm::function_ref<bool(llvm::StringRef)> HeaderFilter) {
+ llvm::StringMap<Header> Missing;
+ AnalysisResults Results;
+ analyze(
+ ASTRoots, MacroRefs, Inc, PI, PP, HeaderFilter,
+ [&Results](const Include *I) { Results.Unused.push_back(I); },
+ [&Results](const Header *H, const Include *, llvm::StringRef Spelling,
+ const SymbolReference &, llvm::ArrayRef<Header> Providers) {
+ if (!H) {
+ Results.Missing.emplace_back(Spelling, Providers.front());
+ }
+ });
for (auto &E : Missing)
Results.Missing.emplace_back(E.first().str(), E.second);
llvm::sort(Results.Missing);
More information about the cfe-commits
mailing list