clang-tools  14.0.0git
IncludeCleaner.h
Go to the documentation of this file.
1 //===--- IncludeCleaner.h - Unused/Missing Headers Analysis -----*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 ///
9 /// \file
10 /// Include Cleaner is clangd functionality for providing diagnostics for misuse
11 /// of transitive headers and unused includes. It is inspired by
12 /// Include-What-You-Use tool (https://include-what-you-use.org/). Our goal is
13 /// to provide useful warnings in most popular scenarios but not 1:1 exact
14 /// feature compatibility.
15 ///
16 /// FIXME(kirillbobyrev): Add support for IWYU pragmas.
17 /// FIXME(kirillbobyrev): Add support for standard library headers.
18 ///
19 //===----------------------------------------------------------------------===//
20 
21 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H
22 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H
23 
24 #include "Headers.h"
25 #include "ParsedAST.h"
26 #include "clang/Basic/SourceLocation.h"
27 #include "llvm/ADT/DenseSet.h"
28 #include <vector>
29 
30 namespace clang {
31 namespace clangd {
32 
34  llvm::DenseSet<SourceLocation> User;
35  llvm::DenseSet<stdlib::Symbol> Stdlib;
36 };
37 
38 /// Finds locations of all symbols used in the main file.
39 ///
40 /// - RecursiveASTVisitor finds references to symbols and records their
41 /// associated locations. These may be macro expansions, and are not resolved
42 /// to their spelling or expansion location. These locations are later used to
43 /// determine which headers should be marked as "used" and "directly used".
44 /// - We also examine all identifier tokens in the file in case they reference
45 /// macros.
46 ///
47 /// We use this to compute unused headers, so we:
48 ///
49 /// - cover the whole file in a single traversal for efficiency
50 /// - don't attempt to describe where symbols were referenced from in
51 /// ambiguous cases (e.g. implicitly used symbols, multiple declarations)
52 /// - err on the side of reporting all possible locations
54 
56  llvm::DenseSet<FileID> User;
57  llvm::DenseSet<stdlib::Header> Stdlib;
58 };
59 
60 /// Retrieves IDs of all files containing SourceLocations from \p Locs.
61 /// The output only includes things SourceManager sees as files (not macro IDs).
62 /// This can include <built-in>, <scratch space> etc that are not true files.
64  const IncludeStructure &Includes,
65  const SourceManager &SM);
66 
67 /// Maps FileIDs to the internal IncludeStructure representation (HeaderIDs).
68 /// FileIDs that are not true files (<built-in> etc) are dropped.
69 llvm::DenseSet<IncludeStructure::HeaderID>
71  const IncludeStructure &Includes, const SourceManager &SM);
72 
73 /// Retrieves headers that are referenced from the main file but not used.
74 /// In unclear cases, headers are not marked as unused.
75 std::vector<const Inclusion *>
76 getUnused(ParsedAST &AST,
77  const llvm::DenseSet<IncludeStructure::HeaderID> &ReferencedFiles);
78 
79 std::vector<const Inclusion *> computeUnusedIncludes(ParsedAST &AST);
80 
81 std::vector<Diag> issueUnusedIncludesDiagnostics(ParsedAST &AST,
82  llvm::StringRef Code);
83 
84 /// Affects whether standard library includes should be considered for removal.
85 /// This is off by default for now due to implementation limitations:
86 /// - macros are not tracked
87 /// - symbol names without a unique associated header are not tracked
88 /// - references to std-namespaced C types are not properly tracked:
89 /// instead of std::size_t -> <cstddef> we see ::size_t -> <stddef.h>
90 /// FIXME: remove this hack once the implementation is good enough.
92 
93 } // namespace clangd
94 } // namespace clang
95 
96 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_INCLUDECLEANER_H
Headers.h
clang::clangd::ReferencedFiles::Stdlib
llvm::DenseSet< stdlib::Header > Stdlib
Definition: IncludeCleaner.h:57
clang::clangd::issueUnusedIncludesDiagnostics
std::vector< Diag > issueUnusedIncludesDiagnostics(ParsedAST &AST, llvm::StringRef Code)
Definition: IncludeCleaner.cpp:395
clang::clangd::ReferencedFiles::User
llvm::DenseSet< FileID > User
Definition: IncludeCleaner.h:56
clang::clangd::IncludeStructure
Definition: Headers.h:192
Code
std::string Code
Definition: FindTargetTests.cpp:67
clang::clangd::setIncludeCleanerAnalyzesStdlib
void setIncludeCleanerAnalyzesStdlib(bool B)
Affects whether standard library includes should be considered for removal.
Definition: IncludeCleaner.cpp:31
clang::clangd::translateToHeaderIDs
llvm::DenseSet< IncludeStructure::HeaderID > translateToHeaderIDs(const ReferencedFiles &Files, const IncludeStructure &Includes, const SourceManager &SM)
Maps FileIDs to the internal IncludeStructure representation (HeaderIDs).
Definition: IncludeCleaner.cpp:362
Files
llvm::DenseSet< FileID > Files
Definition: IncludeCleaner.cpp:170
clang::clangd::ReferencedLocations
Definition: IncludeCleaner.h:33
clang::clangd::computeUnusedIncludes
std::vector< const Inclusion * > computeUnusedIncludes(ParsedAST &AST)
Definition: IncludeCleaner.cpp:384
clang::clangd::findReferencedLocations
ReferencedLocations findReferencedLocations(ParsedAST &AST)
Finds locations of all symbols used in the main file.
Definition: IncludeCleaner.cpp:290
clang::clangd::getUnused
std::vector< const Inclusion * > getUnused(ParsedAST &AST, const llvm::DenseSet< IncludeStructure::HeaderID > &ReferencedFiles)
Retrieves headers that are referenced from the main file but not used.
Definition: IncludeCleaner.cpp:332
clang::clangd::ReferencedLocations::Stdlib
llvm::DenseSet< stdlib::Symbol > Stdlib
Definition: IncludeCleaner.h:35
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
clang::clangd::ParsedAST
Stores and provides access to parsed AST.
Definition: ParsedAST.h:49
clang::clangd::ReferencedLocations::User
llvm::DenseSet< SourceLocation > User
Definition: IncludeCleaner.h:34
clang::clangd::ReferencedFiles
Definition: IncludeCleaner.h:55
clang::clangd::findReferencedFiles
ReferencedFiles findReferencedFiles(const ReferencedLocations &Locs, const IncludeStructure &Includes, const SourceManager &SM)
Retrieves IDs of all files containing SourceLocations from Locs.
Definition: IncludeCleaner.cpp:299
ns1::ns2::B
@ B
Definition: CategoricalFeature.h:3
ParsedAST.h