clang-tools  9.0.0
ClangdUnit.h
Go to the documentation of this file.
1 //===--- ClangdUnit.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 
9 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDUNIT_H
10 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDUNIT_H
11 
12 #include "Compiler.h"
13 #include "Diagnostics.h"
14 #include "FS.h"
15 #include "Function.h"
16 #include "Headers.h"
17 #include "Path.h"
18 #include "Protocol.h"
20 #include "index/Index.h"
21 #include "clang/Frontend/FrontendAction.h"
22 #include "clang/Frontend/PrecompiledPreamble.h"
23 #include "clang/Lex/Preprocessor.h"
24 #include "clang/Serialization/ASTBitCodes.h"
25 #include "clang/Tooling/CompilationDatabase.h"
26 #include "clang/Tooling/Core/Replacement.h"
27 #include "clang/Tooling/Syntax/Tokens.h"
28 #include <memory>
29 #include <string>
30 #include <vector>
31 
32 namespace llvm {
33 class raw_ostream;
34 
35 namespace vfs {
36 class FileSystem;
37 } // namespace vfs
38 } // namespace llvm
39 
40 namespace clang {
41 
42 namespace tooling {
43 struct CompileCommand;
44 } // namespace tooling
45 
46 namespace clangd {
47 
48 // Stores Preamble and associated data.
49 struct PreambleData {
50  PreambleData(PrecompiledPreamble Preamble, std::vector<Diag> Diags,
51  IncludeStructure Includes,
52  std::vector<std::string> MainFileMacros,
53  std::unique_ptr<PreambleFileStatusCache> StatCache,
54  CanonicalIncludes CanonIncludes);
55 
56  tooling::CompileCommand CompileCommand;
57  PrecompiledPreamble Preamble;
58  std::vector<Diag> Diags;
59  // Processes like code completions and go-to-definitions will need #include
60  // information, and their compile action skips preamble range.
62  // Macros defined in the preamble section of the main file.
63  // Users care about headers vs main-file, not preamble vs non-preamble.
64  // These should be treated as main-file entities e.g. for code completion.
65  std::vector<std::string> MainFileMacros;
66  // Cache of FS operations performed when building the preamble.
67  // When reusing a preamble, this cache can be consumed to save IO.
68  std::unique_ptr<PreambleFileStatusCache> StatCache;
70 };
71 
72 /// Stores and provides access to parsed AST.
73 class ParsedAST {
74 public:
75  /// Attempts to run Clang and store parsed AST. If \p Preamble is non-null
76  /// it is reused during parsing.
77  static llvm::Optional<ParsedAST>
78  build(std::unique_ptr<clang::CompilerInvocation> CI,
79  std::shared_ptr<const PreambleData> Preamble,
80  std::unique_ptr<llvm::MemoryBuffer> Buffer,
81  IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS, const SymbolIndex *Index,
82  const ParseOptions &Opts);
83 
84  ParsedAST(ParsedAST &&Other);
85  ParsedAST &operator=(ParsedAST &&Other);
86 
87  ~ParsedAST();
88 
89  /// Note that the returned ast will not contain decls from the preamble that
90  /// were not deserialized during parsing. Clients should expect only decls
91  /// from the main file to be in the AST.
92  ASTContext &getASTContext();
93  const ASTContext &getASTContext() const;
94 
95  Preprocessor &getPreprocessor();
96  std::shared_ptr<Preprocessor> getPreprocessorPtr();
97  const Preprocessor &getPreprocessor() const;
98 
99  SourceManager &getSourceManager() {
100  return getASTContext().getSourceManager();
101  }
102  const SourceManager &getSourceManager() const {
103  return getASTContext().getSourceManager();
104  }
105 
106  /// This function returns top-level decls present in the main file of the AST.
107  /// The result does not include the decls that come from the preamble.
108  /// (These should be const, but RecursiveASTVisitor requires Decl*).
109  ArrayRef<Decl *> getLocalTopLevelDecls();
110 
111  const std::vector<Diag> &getDiagnostics() const;
112 
113  /// Returns the esitmated size of the AST and the accessory structures, in
114  /// bytes. Does not include the size of the preamble.
115  std::size_t getUsedBytes() const;
116  const IncludeStructure &getIncludeStructure() const;
117  const CanonicalIncludes &getCanonicalIncludes() const;
118 
119  /// Tokens recorded while parsing the main file.
120  /// (!) does not have tokens from the preamble.
121  const syntax::TokenBuffer &getTokens() const { return Tokens; }
122 
123 private:
124  ParsedAST(std::shared_ptr<const PreambleData> Preamble,
125  std::unique_ptr<CompilerInstance> Clang,
126  std::unique_ptr<FrontendAction> Action, syntax::TokenBuffer Tokens,
127  std::vector<Decl *> LocalTopLevelDecls, std::vector<Diag> Diags,
128  IncludeStructure Includes, CanonicalIncludes CanonIncludes);
129 
130  // In-memory preambles must outlive the AST, it is important that this member
131  // goes before Clang and Action.
132  std::shared_ptr<const PreambleData> Preamble;
133  // We store an "incomplete" FrontendAction (i.e. no EndSourceFile was called
134  // on it) and CompilerInstance used to run it. That way we don't have to do
135  // complex memory management of all Clang structures on our own. (They are
136  // stored in CompilerInstance and cleaned up by
137  // FrontendAction.EndSourceFile).
138  std::unique_ptr<CompilerInstance> Clang;
139  std::unique_ptr<FrontendAction> Action;
140  /// Tokens recorded after the preamble finished.
141  /// - Includes all spelled tokens for the main file.
142  /// - Includes expanded tokens produced **after** preabmle.
143  /// - Does not have spelled or expanded tokens for files from preamble.
144  syntax::TokenBuffer Tokens;
145 
146  // Data, stored after parsing.
147  std::vector<Diag> Diags;
148  // Top-level decls inside the current file. Not that this does not include
149  // top-level decls from the preamble.
150  std::vector<Decl *> LocalTopLevelDecls;
151  IncludeStructure Includes;
152  CanonicalIncludes CanonIncludes;
153 };
154 
156  std::function<void(ASTContext &, std::shared_ptr<clang::Preprocessor>,
157  const CanonicalIncludes &)>;
158 
159 /// Rebuild the preamble for the new inputs unless the old one can be reused.
160 /// If \p OldPreamble can be reused, it is returned unchanged.
161 /// If \p OldPreamble is null, always builds the preamble.
162 /// If \p PreambleCallback is set, it will be run on top of the AST while
163 /// building the preamble. Note that if the old preamble was reused, no AST is
164 /// built and, therefore, the callback will not be executed.
165 std::shared_ptr<const PreambleData>
166 buildPreamble(PathRef FileName, CompilerInvocation &CI,
167  std::shared_ptr<const PreambleData> OldPreamble,
168  const tooling::CompileCommand &OldCompileCommand,
169  const ParseInputs &Inputs, bool StoreInMemory,
170  PreambleParsedCallback PreambleCallback);
171 
172 /// Build an AST from provided user inputs. This function does not check if
173 /// preamble can be reused, as this function expects that \p Preamble is the
174 /// result of calling buildPreamble.
175 llvm::Optional<ParsedAST>
176 buildAST(PathRef FileName, std::unique_ptr<CompilerInvocation> Invocation,
177  const ParseInputs &Inputs,
178  std::shared_ptr<const PreambleData> Preamble);
179 
180 /// Get the beginning SourceLocation at a specified \p Pos.
181 /// May be invalid if Pos is, or if there's no identifier.
182 SourceLocation getBeginningOfIdentifier(const ParsedAST &Unit,
183  const Position &Pos, const FileID FID);
184 
185 /// For testing/debugging purposes. Note that this method deserializes all
186 /// unserialized Decls, so use with care.
187 void dumpAST(ParsedAST &AST, llvm::raw_ostream &OS);
188 
189 } // namespace clangd
190 } // namespace clang
191 
192 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_CLANGDUNIT_H
Some operations such as code completion produce a set of candidates.
std::vector< std::string > MainFileMacros
Definition: ClangdUnit.h:65
llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS
void dumpAST(ParsedAST &AST, llvm::raw_ostream &OS)
For testing/debugging purposes.
Definition: ClangdUnit.cpp:282
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:85
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:23
const syntax::TokenBuffer & getTokens() const
Tokens recorded while parsing the main file.
Definition: ClangdUnit.h:121
SourceLocation getBeginningOfIdentifier(const ParsedAST &Unit, const Position &Pos, const FileID FID)
Get the beginning SourceLocation at a specified Pos.
Definition: ClangdUnit.cpp:659
std::shared_ptr< const PreambleData > buildPreamble(PathRef FileName, CompilerInvocation &CI, std::shared_ptr< const PreambleData > OldPreamble, const tooling::CompileCommand &OldCompileCommand, const ParseInputs &Inputs, bool StoreInMemory, PreambleParsedCallback PreambleCallback)
Rebuild the preamble for the new inputs unless the old one can be reused.
Definition: ClangdUnit.cpp:566
Maps a definition location onto an #include file, based on a set of filename rules.
CanonicalIncludes CanonIncludes
Definition: ClangdUnit.h:69
std::unique_ptr< PreambleFileStatusCache > StatCache
Definition: ClangdUnit.h:68
const SourceManager & getSourceManager() const
Definition: ClangdUnit.h:102
llvm::unique_function< void()> Action
llvm::Optional< ParsedAST > buildAST(PathRef FileName, std::unique_ptr< CompilerInvocation > Invocation, const ParseInputs &Inputs, std::shared_ptr< const PreambleData > Preamble)
Build an AST from provided user inputs.
Definition: ClangdUnit.cpp:638
StringRef Tokens
PathRef FileName
Stores and provides access to parsed AST.
Definition: ClangdUnit.h:73
std::function< void(ASTContext &, std::shared_ptr< clang::Preprocessor >, const CanonicalIncludes &)> PreambleParsedCallback
Definition: ClangdUnit.h:157
SourceManager & getSourceManager()
Definition: ClangdUnit.h:99
tooling::CompileCommand CompileCommand
Definition: ClangdUnit.h:56
Information required to run clang, e.g. to parse AST or do code completion.
Definition: Compiler.h:44
const PreambleData * Preamble
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::vector< Diag > Diags
Definition: ClangdUnit.h:58
PrecompiledPreamble Preamble
Definition: ClangdUnit.h:57
IncludeStructure Includes
Definition: ClangdUnit.h:61
const SymbolIndex * Index
Definition: Dexp.cpp:84