clang-tools 20.0.0git
Headers.h
Go to the documentation of this file.
1//===--- Headers.h - Include headers -----------------------------*- 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#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_HEADERS_H
10#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_HEADERS_H
11
12#include "Protocol.h"
13#include "SourceCode.h"
14#include "index/Symbol.h"
15#include "support/Path.h"
16#include "clang/Basic/FileEntry.h"
17#include "clang/Basic/TokenKinds.h"
18#include "clang/Format/Format.h"
19#include "clang/Frontend/CompilerInstance.h"
20#include "clang/Lex/HeaderSearch.h"
21#include "clang/Lex/Preprocessor.h"
22#include "clang/Tooling/Inclusions/HeaderIncludes.h"
23#include "clang/Tooling/Inclusions/StandardLibrary.h"
24#include "llvm/ADT/ArrayRef.h"
25#include "llvm/ADT/DenseSet.h"
26#include "llvm/ADT/StringRef.h"
27#include "llvm/ADT/StringSet.h"
28#include "llvm/Support/Error.h"
29#include "llvm/Support/FileSystem/UniqueID.h"
30#include <optional>
31#include <string>
32
33namespace clang {
34namespace clangd {
35
36using HeaderFilter = llvm::ArrayRef<std::function<bool(llvm::StringRef)>>;
37
38/// Returns true if \p Include is literal include like "path" or <path>.
39bool isLiteralInclude(llvm::StringRef Include);
40
41/// Represents a header file to be #include'd.
42struct HeaderFile {
43 std::string File;
44 /// If this is true, `File` is a literal string quoted with <> or "" that
45 /// can be #included directly; otherwise, `File` is an absolute file path.
47
48 bool valid() const;
49};
50
51/// A header and directives as stored in a Symbol.
53 /// The header to include. This is either a URI or a verbatim include which is
54 /// quoted with <> or "".
55 llvm::StringRef Header;
56 /// The include directive(s) that can be used, e.g. #import and/or #include.
58};
59
60/// Creates a `HeaderFile` from \p Header which can be either a URI or a literal
61/// include.
62llvm::Expected<HeaderFile> toHeaderFile(llvm::StringRef Header,
63 llvm::StringRef HintPath);
64
65// Returns include headers for \p Sym sorted by popularity. If two headers are
66// equally popular, prefer the shorter one.
67llvm::SmallVector<SymbolInclude, 1> getRankedIncludes(const Symbol &Sym);
68
69// An #include directive that we found in the main file.
70struct Inclusion {
71 tok::PPKeywordKind Directive; // Directive used for inclusion, e.g. import
72 std::string Written; // Inclusion name as written e.g. <vector>.
73 Path Resolved; // Resolved path of included file. Empty if not resolved.
74 unsigned HashOffset = 0; // Byte offset from start of file to #.
75 int HashLine = 0; // Line number containing the directive, 0-indexed.
76 SrcMgr::CharacteristicKind FileKind = SrcMgr::C_User;
77 std::optional<unsigned> HeaderID;
78};
79llvm::raw_ostream &operator<<(llvm::raw_ostream &, const Inclusion &);
80bool operator==(const Inclusion &LHS, const Inclusion &RHS);
81
82// Contains information about one file in the build graph and its direct
83// dependencies. Doesn't own the strings it references (IncludeGraph is
84// self-contained).
86 enum class SourceFlag : uint8_t {
87 None = 0,
88 // Whether current file is a main file rather than a header.
89 IsTU = 1 << 0,
90 // Whether current file had any uncompilable errors during indexing.
91 HadErrors = 1 << 1,
92 };
93
95 llvm::StringRef URI;
97 std::vector<llvm::StringRef> DirectIncludes;
98};
99// FileURI and FileInclusions are references to keys of the map containing
100// them.
101// Important: The graph generated by those callbacks might contain cycles, self
102// edges and multi edges.
103using IncludeGraph = llvm::StringMap<IncludeGraphNode>;
104
107 return static_cast<IncludeGraphNode::SourceFlag>(static_cast<uint8_t>(A) |
108 static_cast<uint8_t>(B));
109}
110
113 return static_cast<uint8_t>(A) & static_cast<uint8_t>(B);
114}
115
118 return A = A | B;
119}
120
121// Information captured about the inclusion graph in a translation unit.
122// This includes detailed information about the direct #includes, and summary
123// information about all transitive includes.
124//
125// It should be built incrementally with collectIncludeStructureCallback().
126// When we build the preamble, we capture and store its include structure along
127// with the preamble data. When we use the preamble, we can copy its
128// IncludeStructure and use another collectIncludeStructureCallback() to fill
129// in any non-preamble inclusions.
131public:
133 // Reserve HeaderID = 0 for the main file.
134 RealPathNames.emplace_back();
135 }
136
137 // Inserts a PPCallback and CommentHandler that visits all includes in the
138 // main file and populates the structure. It will also scan for IWYU pragmas
139 // in comments.
140 void collect(const CompilerInstance &CI);
141
142 // HeaderID identifies file in the include graph. It corresponds to a
143 // FileEntry rather than a FileID, but stays stable across preamble & main
144 // file builds.
145 enum class HeaderID : unsigned {};
146
147 std::optional<HeaderID> getID(const FileEntry *Entry) const;
148 HeaderID getOrCreateID(FileEntryRef Entry);
149
150 StringRef getRealPath(HeaderID ID) const {
151 assert(static_cast<unsigned>(ID) <= RealPathNames.size());
152 return RealPathNames[static_cast<unsigned>(ID)];
153 }
154
155 // Return all transitively reachable files.
156 llvm::ArrayRef<std::string> allHeaders() const { return RealPathNames; }
157
158 // Returns includes inside the main file with the given spelling.
159 // Spelling should include brackets or quotes, e.g. <foo>.
160 llvm::SmallVector<const Inclusion *>
161 mainFileIncludesWithSpelling(llvm::StringRef Spelling) const;
162
163 // Return all transitively reachable files, and their minimum include depth.
164 // All transitive includes (absolute paths), with their minimum include depth.
165 // Root --> 0, #included file --> 1, etc.
166 // Root is the ID of the header being visited first.
167 llvm::DenseMap<HeaderID, unsigned>
169
170 // Maps HeaderID to the ids of the files included from it.
171 llvm::DenseMap<HeaderID, SmallVector<HeaderID>> IncludeChildren;
172
173 llvm::DenseMap<tooling::stdlib::Header, llvm::SmallVector<HeaderID>>
175
176 std::vector<Inclusion> MainFileIncludes;
177
178 // The entries of the header search path. (HeaderSearch::search_dir_range())
179 // Only includes the plain-directory entries (not header maps or frameworks).
180 // All paths are canonical (FileManager::getCanonicalPath()).
181 std::vector<std::string> SearchPathsCanonical;
182
183 // We reserve HeaderID(0) for the main file and will manually check for that
184 // in getID and getOrCreateID because the UniqueID is not stable when the
185 // content of the main file changes.
186 static const HeaderID MainFileID = HeaderID(0u);
187
188 class RecordHeaders;
189
190private:
191 // MainFileEntry will be used to check if the queried file is the main file
192 // or not.
193 const FileEntry *MainFileEntry = nullptr;
194
195 std::vector<std::string> RealPathNames; // In HeaderID order.
196 // FileEntry::UniqueID is mapped to the internal representation (HeaderID).
197 // Identifying files in a way that persists from preamble build to subsequent
198 // builds is surprisingly hard. FileID is unavailable in InclusionDirective(),
199 // and RealPathName and UniqueID are not preserved in
200 // the preamble.
201 llvm::DenseMap<llvm::sys::fs::UniqueID, HeaderID> UIDToIndex;
202
203 // Maps written includes to indices in MainFileInclude for easier lookup by
204 // spelling.
205 llvm::StringMap<llvm::SmallVector<unsigned>> MainFileIncludesBySpelling;
206};
207
208// Calculates insertion edit for including a new header in a file.
210public:
211 // If \p HeaderSearchInfo is nullptr (e.g. when compile command is
212 // infeasible), this will only try to insert verbatim headers, and
213 // include path of non-verbatim header will not be shortened.
214 IncludeInserter(StringRef FileName, StringRef Code,
215 const format::FormatStyle &Style, StringRef BuildDir,
216 HeaderSearch *HeaderSearchInfo, HeaderFilter QuotedHeaders,
217 HeaderFilter AngledHeaders)
218 : FileName(FileName), Code(Code), BuildDir(BuildDir),
219 HeaderSearchInfo(HeaderSearchInfo),
220 Inserter(FileName, Code, Style.IncludeStyle),
222
223 void addExisting(const Inclusion &Inc);
224
225 /// Checks whether to add an #include of the header into \p File.
226 /// An #include will not be added if:
227 /// - Either \p DeclaringHeader or \p InsertedHeader is already (directly)
228 /// in \p Inclusions (including those included via different paths).
229 /// - \p DeclaringHeader or \p InsertedHeader is the same as \p File.
230 ///
231 /// \param DeclaringHeader is path of the original header corresponding to \p
232 /// InsertedHeader e.g. the header that declares a symbol.
233 /// \param InsertedHeader The preferred header to be inserted. This could be
234 /// the same as DeclaringHeader but must be provided.
235 bool shouldInsertInclude(PathRef DeclaringHeader,
236 const HeaderFile &InsertedHeader) const;
237
238 /// Determines the preferred way to #include a file, taking into account the
239 /// search path. Usually this will prefer a shorter representation like
240 /// 'Foo/Bar.h' over a longer one like 'Baz/include/Foo/Bar.h'.
241 ///
242 /// \param InsertedHeader The preferred header to be inserted.
243 ///
244 /// \param IncludingFile is the absolute path of the file that InsertedHeader
245 /// will be inserted.
246 ///
247 /// \return A quoted "path" or <path> to be included, or std::nullopt if it
248 /// couldn't be shortened.
249 std::optional<std::string>
250 calculateIncludePath(const HeaderFile &InsertedHeader,
251 llvm::StringRef IncludingFile) const;
252
253 /// Calculates an edit that inserts \p VerbatimHeader into code. If the header
254 /// is already included, this returns std::nullopt.
255 std::optional<TextEdit> insert(llvm::StringRef VerbatimHeader,
256 tooling::IncludeDirective Directive) const;
257
258private:
259 StringRef FileName;
260 StringRef Code;
261 StringRef BuildDir;
262 HeaderSearch *HeaderSearchInfo = nullptr;
263 llvm::StringSet<> IncludedHeaders; // Both written and resolved.
264 tooling::HeaderIncludes Inserter; // Computers insertion replacement.
265 HeaderFilter QuotedHeaders;
266 HeaderFilter AngledHeaders;
267};
268
269} // namespace clangd
270} // namespace clang
271
272namespace llvm {
273
274// Support HeaderIDs as DenseMap keys.
275template <> struct DenseMapInfo<clang::clangd::IncludeStructure::HeaderID> {
277 return static_cast<clang::clangd::IncludeStructure::HeaderID>(-1);
278 }
279
281 return static_cast<clang::clangd::IncludeStructure::HeaderID>(-2);
282 }
283
284 static unsigned
286 return hash_value(static_cast<unsigned>(Tag));
287 }
288
291 return LHS == RHS;
292 }
293};
294
295} // namespace llvm
296
297#endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_HEADERS_H
StringRef BuildDir
Definition: ClangTidy.cpp:305
ASTNode Root
Definition: DumpAST.cpp:343
HTMLTag Tag
std::vector< std::function< bool(llvm::StringRef)> > AngledHeaders
std::vector< std::function< bool(llvm::StringRef)> > QuotedHeaders
StringRef FileName
const MacroDirective * Directive
std::unique_ptr< CompilerInvocation > CI
void addExisting(const Inclusion &Inc)
Definition: Headers.cpp:263
std::optional< std::string > calculateIncludePath(const HeaderFile &InsertedHeader, llvm::StringRef IncludingFile) const
Determines the preferred way to #include a file, taking into account the search path.
Definition: Headers.cpp:285
IncludeInserter(StringRef FileName, StringRef Code, const format::FormatStyle &Style, StringRef BuildDir, HeaderSearch *HeaderSearchInfo, HeaderFilter QuotedHeaders, HeaderFilter AngledHeaders)
Definition: Headers.h:214
bool shouldInsertInclude(PathRef DeclaringHeader, const HeaderFile &InsertedHeader) const
Checks whether to add an #include of the header into File.
Definition: Headers.cpp:271
std::optional< TextEdit > insert(llvm::StringRef VerbatimHeader, tooling::IncludeDirective Directive) const
Calculates an edit that inserts VerbatimHeader into code.
Definition: Headers.cpp:339
llvm::SmallVector< const Inclusion * > mainFileIncludesWithSpelling(llvm::StringRef Spelling) const
Definition: Headers.cpp:256
static const HeaderID MainFileID
Definition: Headers.h:186
llvm::DenseMap< HeaderID, unsigned > includeDepth(HeaderID Root=MainFileID) const
Definition: Headers.cpp:228
std::vector< Inclusion > MainFileIncludes
Definition: Headers.h:176
StringRef getRealPath(HeaderID ID) const
Definition: Headers.h:150
std::vector< std::string > SearchPathsCanonical
Definition: Headers.h:181
llvm::DenseMap< tooling::stdlib::Header, llvm::SmallVector< HeaderID > > StdlibHeaders
Definition: Headers.h:174
HeaderID getOrCreateID(FileEntryRef Entry)
Definition: Headers.cpp:208
llvm::ArrayRef< std::string > allHeaders() const
Definition: Headers.h:156
void collect(const CompilerInstance &CI)
Definition: Headers.cpp:178
std::optional< HeaderID > getID(const FileEntry *Entry) const
Definition: Headers.cpp:197
llvm::DenseMap< HeaderID, SmallVector< HeaderID > > IncludeChildren
Definition: Headers.h:171
bool isLiteralInclude(llvm::StringRef Include)
Returns true if Include is literal include like "path" or <path>.
Definition: Headers.cpp:134
std::string Path
A typedef to represent a file path.
Definition: Path.h:26
DeclRelationSet operator&(DeclRelation L, DeclRelation R)
Definition: FindTarget.h:211
bool operator==(const Inclusion &LHS, const Inclusion &RHS)
Definition: Headers.cpp:355
std::array< uint8_t, 8 > FileDigest
Definition: SourceCode.h:42
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
DeclRelationSet operator|(DeclRelation L, DeclRelation R)
Definition: FindTarget.h:208
llvm::Expected< HeaderFile > toHeaderFile(llvm::StringRef Header, llvm::StringRef HintPath)
Creates a HeaderFile from Header which can be either a URI or a literal include.
Definition: Headers.cpp:143
llvm::StringMap< IncludeGraphNode > IncludeGraph
Definition: Headers.h:103
llvm::SmallVector< SymbolInclude, 1 > getRankedIncludes(const Symbol &Sym)
Definition: Headers.cpp:163
llvm::ArrayRef< std::function< bool(llvm::StringRef)> > HeaderFilter
Definition: Headers.h:36
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:29
IncludeGraphNode::SourceFlag & operator|=(IncludeGraphNode::SourceFlag &A, IncludeGraphNode::SourceFlag B)
Definition: Headers.h:117
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Some operations such as code completion produce a set of candidates.
Definition: Generators.h:58
Represents a header file to be #include'd.
Definition: Headers.h:42
bool Verbatim
If this is true, File is a literal string quoted with <> or "" that can be #included directly; otherw...
Definition: Headers.h:46
std::vector< llvm::StringRef > DirectIncludes
Definition: Headers.h:97
std::string Written
Definition: Headers.h:72
tok::PPKeywordKind Directive
Definition: Headers.h:71
SrcMgr::CharacteristicKind FileKind
Definition: Headers.h:76
std::optional< unsigned > HeaderID
Definition: Headers.h:77
A header and directives as stored in a Symbol.
Definition: Headers.h:52
Symbol::IncludeDirective Directive
The include directive(s) that can be used, e.g. #import and/or #include.
Definition: Headers.h:57
llvm::StringRef Header
The header to include.
Definition: Headers.h:55
The class presents a C++ symbol, e.g.
Definition: Symbol.h:39
static unsigned getHashValue(const clang::clangd::IncludeStructure::HeaderID &Tag)
Definition: Headers.h:285
static clang::clangd::IncludeStructure::HeaderID getEmptyKey()
Definition: Headers.h:276
static clang::clangd::IncludeStructure::HeaderID getTombstoneKey()
Definition: Headers.h:280
static bool isEqual(const clang::clangd::IncludeStructure::HeaderID &LHS, const clang::clangd::IncludeStructure::HeaderID &RHS)
Definition: Headers.h:289