| 1 |
//===--- SymbolCollector.h ---------------------------------------*- 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 |
#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SYMBOLCOLLECTOR_H |
| 9 |
#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SYMBOLCOLLECTOR_H |
| 10 |
|
| 11 |
#include "CollectMacros.h" |
| 12 |
#include "index/CanonicalIncludes.h" |
| 13 |
#include "index/Ref.h" |
| 14 |
#include "index/Relation.h" |
| 15 |
#include "index/Symbol.h" |
| 16 |
#include "index/SymbolID.h" |
| 17 |
#include "index/SymbolOrigin.h" |
| 18 |
#include "clang/AST/ASTContext.h" |
| 19 |
#include "clang/AST/Decl.h" |
| 20 |
#include "clang/Basic/SourceLocation.h" |
| 21 |
#include "clang/Basic/SourceManager.h" |
| 22 |
#include "clang/Index/IndexDataConsumer.h" |
| 23 |
#include "clang/Index/IndexSymbol.h" |
| 24 |
#include "clang/Sema/CodeCompleteConsumer.h" |
| 25 |
#include "llvm/ADT/ArrayRef.h" |
| 26 |
#include "llvm/ADT/DenseMap.h" |
| 27 |
#include <functional> |
| 28 |
#include <optional> |
| 29 |
|
| 30 |
namespace clang { |
| 31 |
namespace clangd { |
| 32 |
|
| 33 |
/// Collect declarations (symbols) from an AST. |
| 34 |
/// It collects most declarations except: |
| 35 |
/// - Implicit declarations |
| 36 |
/// - Anonymous declarations (anonymous enum/class/struct, etc) |
| 37 |
/// - Declarations in anonymous namespaces in headers |
| 38 |
/// - Local declarations (in function bodies, blocks, etc) |
| 39 |
/// - Template specializations |
| 40 |
/// - Library-specific private declarations (e.g. private declaration generated |
| 41 |
/// by protobuf compiler) |
| 42 |
/// |
| 43 |
/// References to main-file symbols are not collected. |
| 44 |
/// |
| 45 |
/// See also shouldCollectSymbol(...). |
| 46 |
/// |
| 47 |
/// Clients (e.g. clangd) can use SymbolCollector together with |
| 48 |
/// index::indexTopLevelDecls to retrieve all symbols when the source file is |
| 49 |
/// changed. |
| 50 |
class SymbolCollector : public index::IndexDataConsumer { |
| 51 |
public: |
| 52 |
struct Options { |
| 53 |
/// When symbol paths cannot be resolved to absolute paths (e.g. files in |
| 54 |
/// VFS that does not have absolute path), combine the fallback directory |
| 55 |
/// with symbols' paths to get absolute paths. This must be an absolute |
| 56 |
/// path. |
| 57 |
std::string FallbackDir; |
| 58 |
bool CollectIncludePath = false; |
| 59 |
/// If set, this is used to map symbol #include path to a potentially |
| 60 |
/// different #include path. |
| 61 |
const CanonicalIncludes *Includes = nullptr; |
| 62 |
// Populate the Symbol.References field. |
| 63 |
bool CountReferences = false; |
| 64 |
/// The symbol ref kinds that will be collected. |
| 65 |
/// If not set, SymbolCollector will not collect refs. |
| 66 |
/// Note that references of namespace decls are not collected, as they |
| 67 |
/// contribute large part of the index, and they are less useful compared |
| 68 |
/// with other decls. |
| 69 |
RefKind RefFilter = RefKind::Unknown; |
| 70 |
/// If set to true, SymbolCollector will collect all refs (from main file |
| 71 |
/// and included headers); otherwise, only refs from main file will be |
| 72 |
/// collected. |
| 73 |
/// This flag is only meaningful when RefFilter is set. |
| 74 |
bool RefsInHeaders = false; |
| 75 |
// Every symbol collected will be stamped with this origin. |
| 76 |
SymbolOrigin Origin = SymbolOrigin::Unknown; |
| 77 |
/// Collect macros. |
| 78 |
/// Note that SymbolCollector must be run with preprocessor in order to |
| 79 |
/// collect macros. For example, `indexTopLevelDecls` will not index any |
| 80 |
/// macro even if this is true. |
| 81 |
bool CollectMacro = false; |
| 82 |
/// Collect symbols local to main-files, such as static functions, symbols |
| 83 |
/// inside an anonymous namespace, function-local classes and its member |
| 84 |
/// functions. |
| 85 |
bool CollectMainFileSymbols = true; |
| 86 |
/// Collect references to main-file symbols. |
| 87 |
bool CollectMainFileRefs = false; |
| 88 |
/// Collect symbols with reserved names, like __Vector_base. |
| 89 |
/// This does not currently affect macros (many like _WIN32 are important!) |
| 90 |
bool CollectReserved = false; |
| 91 |
/// If set to true, SymbolCollector will collect doc for all symbols. |
| 92 |
/// Note that documents of symbols being indexed for completion will always |
| 93 |
/// be collected regardless of this option. |
| 94 |
bool StoreAllDocumentation = false; |
| 95 |
/// If this is set, only collect symbols/references from a file if |
| 96 |
/// `FileFilter(SM, FID)` is true. If not set, all files are indexed. |
| 97 |
std::function<bool(const SourceManager &, FileID)> FileFilter = nullptr; |
| 98 |
}; |
| 99 |
|
| 100 |
SymbolCollector(Options Opts); |
| 101 |
~SymbolCollector(); |
| 102 |
|
| 103 |
/// Returns true is \p ND should be collected. |
| 104 |
static bool shouldCollectSymbol(const NamedDecl &ND, const ASTContext &ASTCtx, |
| 105 |
const Options &Opts, bool IsMainFileSymbol); |
| 106 |
|
| 107 |
// Given a ref contained in enclosing decl `Enclosing`, return |
| 108 |
// the decl that should be used as that ref's Ref::Container. This is |
| 109 |
// usually `Enclosing` itself, but in cases where `Enclosing` is not |
| 110 |
// indexed, we walk further up because Ref::Container should always be |
| 111 |
// an indexed symbol. |
| 112 |
// Note: we don't use DeclContext as the container as in some cases |
| 113 |
// it's useful to use a Decl which is not a DeclContext. For example, |
| 114 |
// for a ref occurring in the initializer of a namespace-scope variable, |
| 115 |
// it's useful to use that variable as the container, as otherwise the |
| 116 |
// next enclosing DeclContext would be a NamespaceDecl or TranslationUnitDecl, |
| 117 |
// which are both not indexed and less granular than we'd like for use cases |
| 118 |
// like call hierarchy. |
| 119 |
static const Decl *getRefContainer(const Decl *Enclosing, |
| 120 |
const SymbolCollector::Options &Opts); |
| 121 |
|
| 122 |
void initialize(ASTContext &Ctx) override; |
| 123 |
|
| 124 |
void setPreprocessor(std::shared_ptr<Preprocessor> PP) override { |
| 125 |
this->PP = PP.get(); |
| 126 |
} |
| 127 |
void setPreprocessor(Preprocessor &PP) { this->PP = &PP; } |
| 128 |
|
| 129 |
bool |
| 130 |
handleDeclOccurrence(const Decl *D, index::SymbolRoleSet Roles, |
| 131 |
ArrayRef<index::SymbolRelation> Relations, |
| 132 |
SourceLocation Loc, |
| 133 |
index::IndexDataConsumer::ASTNodeInfo ASTNode) override; |
| 134 |
|
| 135 |
bool handleMacroOccurrence(const IdentifierInfo *Name, const MacroInfo *MI, |
| 136 |
index::SymbolRoleSet Roles, |
| 137 |
SourceLocation Loc) override; |
| 138 |
|
| 139 |
void handleMacros(const MainFileMacros &MacroRefsToIndex); |
| 140 |
|
| 141 |
SymbolSlab takeSymbols() { return std::move(Symbols).build(); } |
| 142 |
RefSlab takeRefs() { return std::move(Refs).build(); } |
| 143 |
RelationSlab takeRelations() { return std::move(Relations).build(); } |
| 144 |
|
| 145 |
/// Returns true if we are interested in references and declarations from \p |
| 146 |
/// FID. If this function return false, bodies of functions inside those files |
| 147 |
/// will be skipped to decrease indexing time. |
| 148 |
bool shouldIndexFile(FileID FID); |
| 149 |
|
| 150 |
void finish() override; |
| 151 |
|
| 152 |
private: |
| 153 |
const Symbol *addDeclaration(const NamedDecl &, SymbolID, |
| 154 |
bool IsMainFileSymbol); |
| 155 |
void addDefinition(const NamedDecl &, const Symbol &DeclSymbol); |
| 156 |
void processRelations(const NamedDecl &ND, const SymbolID &ID, |
| 157 |
ArrayRef<index::SymbolRelation> Relations); |
| 158 |
|
| 159 |
std::optional<SymbolLocation> getTokenLocation(SourceLocation TokLoc); |
| 160 |
|
| 161 |
std::optional<std::string> getIncludeHeader(const Symbol &S, FileID); |
| 162 |
|
| 163 |
SymbolID getSymbolIDCached(const Decl *D); |
| 164 |
SymbolID getSymbolIDCached(const llvm::StringRef MacroName, |
| 165 |
const MacroInfo *MI, const SourceManager &SM); |
| 166 |
|
| 167 |
// All Symbols collected from the AST. |
| 168 |
SymbolSlab::Builder Symbols; |
| 169 |
// File IDs for Symbol.IncludeHeaders. |
| 170 |
// The final spelling is calculated in finish(). |
| 171 |
llvm::DenseMap<SymbolID, FileID> IncludeFiles; |
| 172 |
// Files which contain ObjC symbols. |
| 173 |
// This is finalized and used in finish(). |
| 174 |
llvm::DenseSet<FileID> FilesWithObjCConstructs; |
| 175 |
void setIncludeLocation(const Symbol &S, SourceLocation); |
| 176 |
// Indexed macros, to be erased if they turned out to be include guards. |
| 177 |
llvm::DenseSet<const IdentifierInfo *> IndexedMacros; |
| 178 |
// All refs collected from the AST. It includes: |
| 179 |
// 1) symbols declared in the preamble and referenced from the main file ( |
| 180 |
// which is not a header), or |
| 181 |
// 2) symbols declared and referenced from the main file (which is a header) |
| 182 |
RefSlab::Builder Refs; |
| 183 |
// All relations collected from the AST. |
| 184 |
RelationSlab::Builder Relations; |
| 185 |
ASTContext *ASTCtx; |
| 186 |
Preprocessor *PP = nullptr; |
| 187 |
std::shared_ptr<GlobalCodeCompletionAllocator> CompletionAllocator; |
| 188 |
std::unique_ptr<CodeCompletionTUInfo> CompletionTUInfo; |
| 189 |
Options Opts; |
| 190 |
struct SymbolRef { |
| 191 |
SourceLocation Loc; |
| 192 |
FileID FID; |
| 193 |
index::SymbolRoleSet Roles; |
| 194 |
const Decl *Container; |
| 195 |
bool Spelled; |
| 196 |
}; |
| 197 |
void addRef(SymbolID ID, const SymbolRef &SR); |
| 198 |
// Symbols referenced from the current TU, flushed on finish(). |
| 199 |
llvm::DenseSet<SymbolID> ReferencedSymbols; |
| 200 |
// Maps canonical declaration provided by clang to canonical declaration for |
| 201 |
// an index symbol, if clangd prefers a different declaration than that |
| 202 |
// provided by clang. For example, friend declaration might be considered |
| 203 |
// canonical by clang but should not be considered canonical in the index |
| 204 |
// unless it's a definition. |
| 205 |
llvm::DenseMap<const Decl *, const Decl *> CanonicalDecls; |
| 206 |
// Cache whether to index a file or not. |
| 207 |
llvm::DenseMap<FileID, bool> FilesToIndexCache; |
| 208 |
// Encapsulates calculations and caches around header paths, which headers |
| 209 |
// to insert for which symbol, etc. |
| 210 |
class HeaderFileURICache; |
| 211 |
std::unique_ptr<HeaderFileURICache> HeaderFileURIs; |
| 212 |
llvm::DenseMap<const Decl *, SymbolID> DeclToIDCache; |
| 213 |
llvm::DenseMap<const MacroInfo *, SymbolID> MacroToIDCache; |
| 214 |
}; |
| 215 |
|
| 216 |
} // namespace clangd |
| 217 |
} // namespace clang |
| 218 |
|
| 219 |
#endif |