clang-tools  14.0.0git
Preamble.h
Go to the documentation of this file.
1 //===--- Preamble.h - Reusing expensive parts of the AST ---------*- 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 // The vast majority of code in a typical translation unit is in the headers
10 // included at the top of the file.
11 //
12 // The preamble optimization says that we can parse this code once, and reuse
13 // the result multiple times. The preamble is invalidated by changes to the
14 // code in the preamble region, to the compile command, or to files on disk.
15 //
16 // This is the most important optimization in clangd: it allows operations like
17 // code-completion to have sub-second latency. It is supported by the
18 // PrecompiledPreamble functionality in clang, which wraps the techniques used
19 // by PCH files, modules etc into a convenient interface.
20 //
21 //===----------------------------------------------------------------------===//
22 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
23 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
24 
25 #include "CollectMacros.h"
26 #include "Compiler.h"
27 #include "Diagnostics.h"
28 #include "FS.h"
29 #include "Headers.h"
31 #include "support/Path.h"
32 #include "clang/Frontend/CompilerInvocation.h"
33 #include "clang/Frontend/PrecompiledPreamble.h"
34 #include "clang/Lex/Lexer.h"
35 #include "clang/Tooling/CompilationDatabase.h"
36 #include "llvm/ADT/StringRef.h"
37 
38 #include <memory>
39 #include <string>
40 #include <vector>
41 
42 namespace clang {
43 namespace clangd {
44 
45 /// The parsed preamble and associated data.
46 ///
47 /// As we must avoid re-parsing the preamble, any information that can only
48 /// be obtained during parsing must be eagerly captured and stored here.
49 struct PreambleData {
50  PreambleData(PrecompiledPreamble Preamble) : Preamble(std::move(Preamble)) {}
51 
52  // Version of the ParseInputs this preamble was built from.
53  std::string Version;
54  tooling::CompileCommand CompileCommand;
55  PrecompiledPreamble Preamble;
56  std::vector<Diag> Diags;
57  // Processes like code completions and go-to-definitions will need #include
58  // information, and their compile action skips preamble range.
60  // Macros defined in the preamble section of the main file.
61  // Users care about headers vs main-file, not preamble vs non-preamble.
62  // These should be treated as main-file entities e.g. for code completion.
64  // Cache of FS operations performed when building the preamble.
65  // When reusing a preamble, this cache can be consumed to save IO.
66  std::unique_ptr<PreambleFileStatusCache> StatCache;
68  // Whether there was a (possibly-incomplete) include-guard on the main file.
69  // We need to propagate this information "by hand" to subsequent parses.
70  bool MainIsIncludeGuarded = false;
71 };
72 
74  std::function<void(ASTContext &, std::shared_ptr<clang::Preprocessor>,
75  const CanonicalIncludes &)>;
76 
77 /// Build a preamble for the new inputs unless an old one can be reused.
78 /// If \p PreambleCallback is set, it will be run on top of the AST while
79 /// building the preamble.
80 std::shared_ptr<const PreambleData>
81 buildPreamble(PathRef FileName, CompilerInvocation CI,
82  const ParseInputs &Inputs, bool StoreInMemory,
83  PreambleParsedCallback PreambleCallback);
84 
85 /// Returns true if \p Preamble is reusable for \p Inputs. Note that it will
86 /// return true when some missing headers are now available.
87 /// FIXME: Should return more information about the delta between \p Preamble
88 /// and \p Inputs, e.g. new headers.
91  const CompilerInvocation &CI);
92 
93 /// Stores information required to parse a TU using a (possibly stale) Baseline
94 /// preamble. Later on this information can be injected into the main file by
95 /// updating compiler invocation with \c apply. This injected section
96 /// approximately reflects additions to the preamble in Modified contents, e.g.
97 /// new include directives.
99 public:
100  enum class PatchType { MacroDirectives, All };
101  /// \p Preamble is used verbatim.
103  /// Builds a patch that contains new PP directives introduced to the preamble
104  /// section of \p Modified compared to \p Baseline.
105  /// FIXME: This only handles include directives, we should at least handle
106  /// define/undef.
107  static PreamblePatch createFullPatch(llvm::StringRef FileName,
108  const ParseInputs &Modified,
109  const PreambleData &Baseline);
110  static PreamblePatch createMacroPatch(llvm::StringRef FileName,
111  const ParseInputs &Modified,
112  const PreambleData &Baseline);
113 
114  /// Adjusts CI (which compiles the modified inputs) to be used with the
115  /// baseline preamble. This is done by inserting an artifical include to the
116  /// \p CI that contains new directives calculated in create.
117  void apply(CompilerInvocation &CI) const;
118 
119  /// Returns #include directives from the \c Modified preamble that were
120  /// resolved using the \c Baseline preamble. This covers the new locations of
121  /// inclusions that were moved around, but not inclusions of new files. Those
122  /// will be recorded when parsing the main file: the includes in the injected
123  /// section will be resolved back to their spelled positions in the main file
124  /// using the presumed-location mechanism.
125  std::vector<Inclusion> preambleIncludes() const;
126 
127  /// Returns preamble bounds for the Modified.
128  PreambleBounds modifiedBounds() const { return ModifiedBounds; }
129 
130  /// Returns textual patch contents.
131  llvm::StringRef text() const { return PatchContents; }
132 
133  /// Whether diagnostics generated using this patch are trustable.
134  bool preserveDiagnostics() const { return PatchContents.empty(); }
135 
136 private:
137  static PreamblePatch create(llvm::StringRef FileName,
138  const ParseInputs &Modified,
139  const PreambleData &Baseline,
141 
142  PreamblePatch() = default;
143  std::string PatchContents;
144  std::string PatchFileName;
145  /// Includes that are present in both \p Baseline and \p Modified. Used for
146  /// patching includes of baseline preamble.
147  std::vector<Inclusion> PreambleIncludes;
148  PreambleBounds ModifiedBounds = {0, false};
149 };
150 
151 /// Translates locations inside preamble patch to their main-file equivalent
152 /// using presumed locations. Returns \p Loc if it isn't inside preamble patch.
153 SourceLocation translatePreamblePatchLocation(SourceLocation Loc,
154  const SourceManager &SM);
155 
156 } // namespace clangd
157 } // namespace clang
158 
159 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_PREAMBLE_H
clang::clangd::PreambleData::MainIsIncludeGuarded
bool MainIsIncludeGuarded
Definition: Preamble.h:70
Loc
SourceLocation Loc
Definition: KernelNameRestrictionCheck.cpp:45
clang::clangd::PreambleData::StatCache
std::unique_ptr< PreambleFileStatusCache > StatCache
Definition: Preamble.h:66
clang::clangd::isPreambleCompatible
bool isPreambleCompatible(const PreambleData &Preamble, const ParseInputs &Inputs, PathRef FileName, const CompilerInvocation &CI)
Returns true if Preamble is reusable for Inputs.
Definition: Preamble.cpp:403
Headers.h
clang::clangd::PreamblePatch::text
llvm::StringRef text() const
Returns textual patch contents.
Definition: Preamble.h:131
clang::clangd::PreambleParsedCallback
std::function< void(ASTContext &, std::shared_ptr< clang::Preprocessor >, const CanonicalIncludes &)> PreambleParsedCallback
Definition: Preamble.h:75
Path.h
clang::clangd::PreambleData::Macros
MainFileMacros Macros
Definition: Preamble.h:63
clang::clangd::PreambleData::Preamble
PrecompiledPreamble Preamble
Definition: Preamble.h:55
CI
std::unique_ptr< CompilerInvocation > CI
Definition: TUScheduler.cpp:450
clang::clangd::PreamblePatch::unmodified
static PreamblePatch unmodified(const PreambleData &Preamble)
Preamble is used verbatim.
Definition: Preamble.cpp:567
clang::clangd::PreamblePatch
Stores information required to parse a TU using a (possibly stale) Baseline preamble.
Definition: Preamble.h:98
clang::clangd::PreambleData::Includes
IncludeStructure Includes
Definition: Preamble.h:59
Preamble
const PreambleData & Preamble
Definition: CodeComplete.cpp:1104
clang::clangd::IncludeStructure
Definition: Headers.h:113
Inputs
ParseInputs Inputs
Definition: TUScheduler.cpp:451
clang::clangd::PreambleData::Version
std::string Version
Definition: Preamble.h:53
clang::clangd::PreamblePatch::apply
void apply(CompilerInvocation &CI) const
Adjusts CI (which compiles the modified inputs) to be used with the baseline preamble.
Definition: Preamble.cpp:547
clang::clangd::ParseInputs
Information required to run clang, e.g. to parse AST or do code completion.
Definition: Compiler.h:47
CanonicalIncludes.h
clang::clangd::PreamblePatch::preserveDiagnostics
bool preserveDiagnostics() const
Whether diagnostics generated using this patch are trustable.
Definition: Preamble.h:134
clang::clangd::PreambleData
The parsed preamble and associated data.
Definition: Preamble.h:49
clang::clangd::CanonicalIncludes
Maps a definition location onto an #include file, based on a set of filename rules.
Definition: CanonicalIncludes.h:36
clang::clangd::PreamblePatch::createMacroPatch
static PreamblePatch createMacroPatch(llvm::StringRef FileName, const ParseInputs &Modified, const PreambleData &Baseline)
Definition: Preamble.cpp:541
clang::clangd::PreamblePatch::PatchType::MacroDirectives
@ MacroDirectives
clang::clangd::PreamblePatch::PatchType
PatchType
Definition: Preamble.h:100
CollectMacros.h
clang::clangd::buildPreamble
std::shared_ptr< const PreambleData > buildPreamble(PathRef FileName, CompilerInvocation CI, const ParseInputs &Inputs, bool StoreInMemory, PreambleParsedCallback PreambleCallback)
Build a preamble for the new inputs unless an old one can be reused.
Definition: Preamble.cpp:318
clang::clangd::MainFileMacros
Definition: CollectMacros.h:31
clang::clangd::PreambleData::Diags
std::vector< Diag > Diags
Definition: Preamble.h:56
Diagnostics.h
FileName
StringRef FileName
Definition: KernelNameRestrictionCheck.cpp:46
clang::clangd::PreambleData::CompileCommand
tooling::CompileCommand CompileCommand
Definition: Preamble.h:54
clang::clangd::PreamblePatch::modifiedBounds
PreambleBounds modifiedBounds() const
Returns preamble bounds for the Modified.
Definition: Preamble.h:128
Compiler.h
clang::clangd::PreamblePatch::createFullPatch
static PreamblePatch createFullPatch(llvm::StringRef FileName, const ParseInputs &Modified, const PreambleData &Baseline)
Builds a patch that contains new PP directives introduced to the preamble section of Modified compare...
Definition: Preamble.cpp:535
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:29
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
FS.h
clang::clangd::PreambleData::PreambleData
PreambleData(PrecompiledPreamble Preamble)
Definition: Preamble.h:50
clang::clangd::PreambleData::CanonIncludes
CanonicalIncludes CanonIncludes
Definition: Preamble.h:67
clang::clangd::PreamblePatch::preambleIncludes
std::vector< Inclusion > preambleIncludes() const
Returns #include directives from the Modified preamble that were resolved using the Baseline preamble...
Definition: Preamble.cpp:563
clang::clangd::PreamblePatch::PatchType::All
@ All
clang::clangd::translatePreamblePatchLocation
SourceLocation translatePreamblePatchLocation(SourceLocation Loc, const SourceManager &SM)
Translates locations inside preamble patch to their main-file equivalent using presumed locations.
Definition: Preamble.cpp:574