1 //===- ASTUnit.h - ASTUnit utility ------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 // ASTUnit utility class.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_CLANG_FRONTEND_ASTUNIT_H
14 #define LLVM_CLANG_FRONTEND_ASTUNIT_H
16 #include "clang-c/Index.h"
17 #include "clang/AST/ASTContext.h"
18 #include "clang/Basic/Diagnostic.h"
19 #include "clang/Basic/FileSystemOptions.h"
20 #include "clang/Basic/LLVM.h"
21 #include "clang/Basic/LangOptions.h"
22 #include "clang/Basic/SourceLocation.h"
23 #include "clang/Basic/SourceManager.h"
24 #include "clang/Basic/TargetOptions.h"
25 #include "clang/Lex/HeaderSearchOptions.h"
26 #include "clang/Lex/ModuleLoader.h"
27 #include "clang/Lex/PreprocessingRecord.h"
28 #include "clang/Sema/CodeCompleteConsumer.h"
29 #include "clang/Serialization/ASTBitCodes.h"
30 #include "clang/Frontend/PrecompiledPreamble.h"
31 #include "llvm/ADT/ArrayRef.h"
32 #include "llvm/ADT/DenseMap.h"
33 #include "llvm/ADT/IntrusiveRefCntPtr.h"
34 #include "llvm/ADT/None.h"
35 #include "llvm/ADT/Optional.h"
36 #include "llvm/ADT/STLExtras.h"
37 #include "llvm/ADT/SmallVector.h"
38 #include "llvm/ADT/StringMap.h"
39 #include "llvm/ADT/StringRef.h"
40 #include "llvm/ADT/iterator_range.h"
63 class ASTDeserializationListener;
64 class ASTMutationListener;
66 class CompilerInstance;
67 class CompilerInvocation;
74 class InMemoryModuleCache;
75 class PCHContainerOperations;
76 class PCHContainerReader;
78 class PreprocessorOptions;
82 /// \brief Enumerates the available scopes for skipping function bodies.
83 enum class SkipFunctionBodiesScope { None, Preamble, PreambleAndMainFile };
85 /// \brief Enumerates the available kinds for capturing diagnostics.
86 enum class CaptureDiagsKind { None, All, AllWithoutNonErrorsFromIncludes };
88 /// Utility class for loading a ASTContext from an AST file.
91 struct StandaloneFixIt {
92 std::pair<unsigned, unsigned> RemoveRange;
93 std::pair<unsigned, unsigned> InsertFromRange;
94 std::string CodeToInsert;
95 bool BeforePreviousInsertions;
98 struct StandaloneDiagnostic {
100 DiagnosticsEngine::Level Level;
102 std::string Filename;
104 std::vector<std::pair<unsigned, unsigned>> Ranges;
105 std::vector<StandaloneFixIt> FixIts;
109 std::shared_ptr<LangOptions> LangOpts;
110 IntrusiveRefCntPtr<DiagnosticsEngine> Diagnostics;
111 IntrusiveRefCntPtr<FileManager> FileMgr;
112 IntrusiveRefCntPtr<SourceManager> SourceMgr;
113 IntrusiveRefCntPtr<InMemoryModuleCache> ModuleCache;
114 std::unique_ptr<HeaderSearch> HeaderInfo;
115 IntrusiveRefCntPtr<TargetInfo> Target;
116 std::shared_ptr<Preprocessor> PP;
117 IntrusiveRefCntPtr<ASTContext> Ctx;
118 std::shared_ptr<TargetOptions> TargetOpts;
119 std::shared_ptr<HeaderSearchOptions> HSOpts;
120 std::shared_ptr<PreprocessorOptions> PPOpts;
121 IntrusiveRefCntPtr<ASTReader> Reader;
122 bool HadModuleLoaderFatalFailure = false;
124 struct ASTWriterData;
125 std::unique_ptr<ASTWriterData> WriterData;
127 FileSystemOptions FileSystemOpts;
129 /// The AST consumer that received information about the translation
130 /// unit as it was parsed or loaded.
131 std::unique_ptr<ASTConsumer> Consumer;
133 /// The semantic analysis object used to type-check the translation
135 std::unique_ptr<Sema> TheSema;
137 /// Optional owned invocation, just used to make the invocation used in
138 /// LoadFromCommandLine available.
139 std::shared_ptr<CompilerInvocation> Invocation;
141 /// Fake module loader: the AST unit doesn't need to load any modules.
142 TrivialModuleLoader ModuleLoader;
144 // OnlyLocalDecls - when true, walking this AST should only visit declarations
145 // that come from the AST itself, not from included precompiled headers.
146 // FIXME: This is temporary; eventually, CIndex will always do this.
147 bool OnlyLocalDecls = false;
149 /// Whether to capture any diagnostics produced.
150 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None;
152 /// Track whether the main file was loaded from an AST or not.
155 /// What kind of translation unit this AST represents.
156 TranslationUnitKind TUKind = TU_Complete;
158 /// Whether we should time each operation.
161 /// Whether the ASTUnit should delete the remapped buffers.
162 bool OwnsRemappedFileBuffers = true;
164 /// Track the top-level decls which appeared in an ASTUnit which was loaded
165 /// from a source file.
167 // FIXME: This is just an optimization hack to avoid deserializing large parts
168 // of a PCH file when using the Index library on an ASTUnit loaded from
169 // source. In the long term we should make the Index library use efficient and
170 // more scalable search mechanisms.
171 std::vector<Decl*> TopLevelDecls;
173 /// Sorted (by file offset) vector of pairs of file offset/Decl.
174 using LocDeclsTy = SmallVector<std::pair<unsigned, Decl *>, 64>;
175 using FileDeclsTy = llvm::DenseMap<FileID, LocDeclsTy *>;
177 /// Map from FileID to the file-level declarations that it contains.
178 /// The files and decls are only local (and non-preamble) ones.
179 FileDeclsTy FileDecls;
181 /// The name of the original source file used to generate this ASTUnit.
182 std::string OriginalSourceFile;
184 /// The set of diagnostics produced when creating the preamble.
185 SmallVector<StandaloneDiagnostic, 4> PreambleDiagnostics;
187 /// The set of diagnostics produced when creating this
188 /// translation unit.
189 SmallVector<StoredDiagnostic, 4> StoredDiagnostics;
191 /// The set of diagnostics produced when failing to parse, e.g. due
192 /// to failure to load the PCH.
193 SmallVector<StoredDiagnostic, 4> FailedParseDiagnostics;
195 /// The number of stored diagnostics that come from the driver
198 /// Diagnostics that come from the driver are retained from one parse to
200 unsigned NumStoredDiagnosticsFromDriver = 0;
202 /// Counter that determines when we want to try building a
203 /// precompiled preamble.
205 /// If zero, we will never build a precompiled preamble. Otherwise,
206 /// it's treated as a counter that decrements each time we reparse
207 /// without the benefit of a precompiled preamble. When it hits 1,
208 /// we'll attempt to rebuild the precompiled header. This way, if
209 /// building the precompiled preamble fails, we won't try again for
210 /// some number of calls.
211 unsigned PreambleRebuildCountdown = 0;
213 /// Counter indicating how often the preamble was build in total.
214 unsigned PreambleCounter = 0;
216 /// Cache pairs "filename - source location"
218 /// Cache contains only source locations from preamble so it is
219 /// guaranteed that they stay valid when the SourceManager is recreated.
220 /// This cache is used when loading preamble to increase performance
221 /// of that loading. It must be cleared when preamble is recreated.
222 llvm::StringMap<SourceLocation> PreambleSrcLocCache;
224 /// The contents of the preamble.
225 llvm::Optional<PrecompiledPreamble> Preamble;
227 /// When non-NULL, this is the buffer used to store the contents of
228 /// the main file when it has been padded for use with the precompiled
230 std::unique_ptr<llvm::MemoryBuffer> SavedMainFileBuffer;
232 /// The number of warnings that occurred while parsing the preamble.
234 /// This value will be used to restore the state of the \c DiagnosticsEngine
235 /// object when re-using the precompiled preamble. Note that only the
236 /// number of warnings matters, since we will not save the preamble
237 /// when any errors are present.
238 unsigned NumWarningsInPreamble = 0;
240 /// A list of the serialization ID numbers for each of the top-level
241 /// declarations parsed within the precompiled preamble.
242 std::vector<serialization::DeclID> TopLevelDeclsInPreamble;
244 /// Whether we should be caching code-completion results.
245 bool ShouldCacheCodeCompletionResults : 1;
247 /// Whether to include brief documentation within the set of code
248 /// completions cached.
249 bool IncludeBriefCommentsInCodeCompletion : 1;
251 /// True if non-system source files should be treated as volatile
252 /// (likely to change while trying to use them).
253 bool UserFilesAreVolatile : 1;
255 static void ConfigureDiags(IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
256 ASTUnit &AST, CaptureDiagsKind CaptureDiagnostics);
258 void TranslateStoredDiagnostics(FileManager &FileMgr,
259 SourceManager &SrcMan,
260 const SmallVectorImpl<StandaloneDiagnostic> &Diags,
261 SmallVectorImpl<StoredDiagnostic> &Out);
263 void clearFileLevelDecls();
266 /// A cached code-completion result, which may be introduced in one of
267 /// many different contexts.
268 struct CachedCodeCompletionResult {
269 /// The code-completion string corresponding to this completion
271 CodeCompletionString *Completion;
273 /// A bitmask that indicates which code-completion contexts should
274 /// contain this completion result.
276 /// The bits in the bitmask correspond to the values of
277 /// CodeCompleteContext::Kind. To map from a completion context kind to a
278 /// bit, shift 1 by that number of bits. Many completions can occur in
279 /// several different contexts.
280 uint64_t ShowInContexts;
282 /// The priority given to this code-completion result.
285 /// The libclang cursor kind corresponding to this code-completion
289 /// The availability of this code-completion result.
290 CXAvailabilityKind Availability;
292 /// The simplified type class for a non-macro completion result.
293 SimplifiedTypeClass TypeClass;
295 /// The type of a non-macro completion result, stored as a unique
296 /// integer used by the string map of cached completion types.
298 /// This value will be zero if the type is not known, or a unique value
299 /// determined by the formatted type string. Se \c CachedCompletionTypes
300 /// for more information.
304 /// Retrieve the mapping from formatted type names to unique type
306 llvm::StringMap<unsigned> &getCachedCompletionTypes() {
307 return CachedCompletionTypes;
310 /// Retrieve the allocator used to cache global code completions.
311 std::shared_ptr<GlobalCodeCompletionAllocator>
312 getCachedCompletionAllocator() {
313 return CachedCompletionAllocator;
316 CodeCompletionTUInfo &getCodeCompletionTUInfo() {
318 CCTUInfo = llvm::make_unique<CodeCompletionTUInfo>(
319 std::make_shared<GlobalCodeCompletionAllocator>());
324 /// Allocator used to store cached code completions.
325 std::shared_ptr<GlobalCodeCompletionAllocator> CachedCompletionAllocator;
327 std::unique_ptr<CodeCompletionTUInfo> CCTUInfo;
329 /// The set of cached code-completion results.
330 std::vector<CachedCodeCompletionResult> CachedCompletionResults;
332 /// A mapping from the formatted type name to a unique number for that
333 /// type, which is used for type equality comparisons.
334 llvm::StringMap<unsigned> CachedCompletionTypes;
336 /// A string hash of the top-level declaration and macro definition
337 /// names processed the last time that we reparsed the file.
339 /// This hash value is used to determine when we need to refresh the
340 /// global code-completion cache.
341 unsigned CompletionCacheTopLevelHashValue = 0;
343 /// A string hash of the top-level declaration and macro definition
344 /// names processed the last time that we reparsed the precompiled preamble.
346 /// This hash value is used to determine when we need to refresh the
347 /// global code-completion cache after a rebuild of the precompiled preamble.
348 unsigned PreambleTopLevelHashValue = 0;
350 /// The current hash value for the top-level declaration and macro
352 unsigned CurrentTopLevelHashValue = 0;
354 /// Bit used by CIndex to mark when a translation unit may be in an
355 /// inconsistent state, and is not safe to free.
356 unsigned UnsafeToFree : 1;
358 /// \brief Enumerator specifying the scope for skipping function bodies.
359 SkipFunctionBodiesScope SkipFunctionBodies = SkipFunctionBodiesScope::None;
361 /// Cache any "global" code-completion results, so that we can avoid
362 /// recomputing them with each completion.
363 void CacheCodeCompletionResults();
365 /// Clear out and deallocate
366 void ClearCachedCompletionResults();
368 explicit ASTUnit(bool MainFileIsAST);
370 bool Parse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
371 std::unique_ptr<llvm::MemoryBuffer> OverrideMainBuffer,
372 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS);
374 std::unique_ptr<llvm::MemoryBuffer> getMainBufferWithPrecompiledPreamble(
375 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
376 CompilerInvocation &PreambleInvocationIn,
377 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS, bool AllowRebuild = true,
378 unsigned MaxLines = 0);
379 void RealizeTopLevelDeclsFromPreamble();
381 /// Transfers ownership of the objects (like SourceManager) from
382 /// \param CI to this ASTUnit.
383 void transferASTDataFromCompilerInstance(CompilerInstance &CI);
385 /// Allows us to assert that ASTUnit is not being used concurrently,
386 /// which is not supported.
388 /// Clients should create instances of the ConcurrencyCheck class whenever
389 /// using the ASTUnit in a way that isn't intended to be concurrent, which is
390 /// just about any usage.
391 /// Becomes a noop in release mode; only useful for debug mode checking.
392 class ConcurrencyState {
393 void *Mutex; // a llvm::sys::MutexImpl in debug;
402 ConcurrencyState ConcurrencyCheckValue;
405 friend class ConcurrencyCheck;
407 class ConcurrencyCheck {
411 explicit ConcurrencyCheck(ASTUnit &Self) : Self(Self) {
412 Self.ConcurrencyCheckValue.start();
415 ~ConcurrencyCheck() {
416 Self.ConcurrencyCheckValue.finish();
420 ASTUnit(const ASTUnit &) = delete;
421 ASTUnit &operator=(const ASTUnit &) = delete;
424 bool isMainFileAST() const { return MainFileIsAST; }
426 bool isUnsafeToFree() const { return UnsafeToFree; }
427 void setUnsafeToFree(bool Value) { UnsafeToFree = Value; }
429 const DiagnosticsEngine &getDiagnostics() const { return *Diagnostics; }
430 DiagnosticsEngine &getDiagnostics() { return *Diagnostics; }
432 const SourceManager &getSourceManager() const { return *SourceMgr; }
433 SourceManager &getSourceManager() { return *SourceMgr; }
435 const Preprocessor &getPreprocessor() const { return *PP; }
436 Preprocessor &getPreprocessor() { return *PP; }
437 std::shared_ptr<Preprocessor> getPreprocessorPtr() const { return PP; }
439 const ASTContext &getASTContext() const { return *Ctx; }
440 ASTContext &getASTContext() { return *Ctx; }
442 void setASTContext(ASTContext *ctx) { Ctx = ctx; }
443 void setPreprocessor(std::shared_ptr<Preprocessor> pp);
445 /// Enable source-range based diagnostic messages.
447 /// If diagnostic messages with source-range information are to be expected
448 /// and AST comes not from file (e.g. after LoadFromCompilerInvocation) this
449 /// function has to be called.
450 /// The function is to be called only once and the AST should be associated
451 /// with the same source file afterwards.
452 void enableSourceFileDiagnostics();
454 bool hasSema() const { return (bool)TheSema; }
456 Sema &getSema() const {
457 assert(TheSema && "ASTUnit does not have a Sema object!");
461 const LangOptions &getLangOpts() const {
462 assert(LangOpts && "ASTUnit does not have language options");
466 const HeaderSearchOptions &getHeaderSearchOpts() const {
467 assert(HSOpts && "ASTUnit does not have header search options");
471 const PreprocessorOptions &getPreprocessorOpts() const {
472 assert(PPOpts && "ASTUnit does not have preprocessor options");
476 const FileManager &getFileManager() const { return *FileMgr; }
477 FileManager &getFileManager() { return *FileMgr; }
479 const FileSystemOptions &getFileSystemOpts() const { return FileSystemOpts; }
481 IntrusiveRefCntPtr<ASTReader> getASTReader() const;
483 StringRef getOriginalSourceFileName() const {
484 return OriginalSourceFile;
487 ASTMutationListener *getASTMutationListener();
488 ASTDeserializationListener *getDeserializationListener();
490 bool getOnlyLocalDecls() const { return OnlyLocalDecls; }
492 bool getOwnsRemappedFileBuffers() const { return OwnsRemappedFileBuffers; }
493 void setOwnsRemappedFileBuffers(bool val) { OwnsRemappedFileBuffers = val; }
495 StringRef getMainFileName() const;
497 /// If this ASTUnit came from an AST file, returns the filename for it.
498 StringRef getASTFileName() const;
500 using top_level_iterator = std::vector<Decl *>::iterator;
502 top_level_iterator top_level_begin() {
503 assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
504 if (!TopLevelDeclsInPreamble.empty())
505 RealizeTopLevelDeclsFromPreamble();
506 return TopLevelDecls.begin();
509 top_level_iterator top_level_end() {
510 assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
511 if (!TopLevelDeclsInPreamble.empty())
512 RealizeTopLevelDeclsFromPreamble();
513 return TopLevelDecls.end();
516 std::size_t top_level_size() const {
517 assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
518 return TopLevelDeclsInPreamble.size() + TopLevelDecls.size();
521 bool top_level_empty() const {
522 assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
523 return TopLevelDeclsInPreamble.empty() && TopLevelDecls.empty();
526 /// Add a new top-level declaration.
527 void addTopLevelDecl(Decl *D) {
528 TopLevelDecls.push_back(D);
531 /// Add a new local file-level declaration.
532 void addFileLevelDecl(Decl *D);
534 /// Get the decls that are contained in a file in the Offset/Length
535 /// range. \p Length can be 0 to indicate a point at \p Offset instead of
537 void findFileRegionDecls(FileID File, unsigned Offset, unsigned Length,
538 SmallVectorImpl<Decl *> &Decls);
540 /// Retrieve a reference to the current top-level name hash value.
542 /// Note: This is used internally by the top-level tracking action
543 unsigned &getCurrentTopLevelHashValue() { return CurrentTopLevelHashValue; }
545 /// Get the source location for the given file:line:col triplet.
547 /// The difference with SourceManager::getLocation is that this method checks
548 /// whether the requested location points inside the precompiled preamble
549 /// in which case the returned source location will be a "loaded" one.
550 SourceLocation getLocation(const FileEntry *File,
551 unsigned Line, unsigned Col) const;
553 /// Get the source location for the given file:offset pair.
554 SourceLocation getLocation(const FileEntry *File, unsigned Offset) const;
556 /// If \p Loc is a loaded location from the preamble, returns
557 /// the corresponding local location of the main file, otherwise it returns
559 SourceLocation mapLocationFromPreamble(SourceLocation Loc) const;
561 /// If \p Loc is a local location of the main file but inside the
562 /// preamble chunk, returns the corresponding loaded location from the
563 /// preamble, otherwise it returns \p Loc.
564 SourceLocation mapLocationToPreamble(SourceLocation Loc) const;
566 bool isInPreambleFileID(SourceLocation Loc) const;
567 bool isInMainFileID(SourceLocation Loc) const;
568 SourceLocation getStartOfMainFileID() const;
569 SourceLocation getEndOfPreambleFileID() const;
571 /// \see mapLocationFromPreamble.
572 SourceRange mapRangeFromPreamble(SourceRange R) const {
573 return SourceRange(mapLocationFromPreamble(R.getBegin()),
574 mapLocationFromPreamble(R.getEnd()));
577 /// \see mapLocationToPreamble.
578 SourceRange mapRangeToPreamble(SourceRange R) const {
579 return SourceRange(mapLocationToPreamble(R.getBegin()),
580 mapLocationToPreamble(R.getEnd()));
583 unsigned getPreambleCounterForTests() const { return PreambleCounter; }
585 // Retrieve the diagnostics associated with this AST
586 using stored_diag_iterator = StoredDiagnostic *;
587 using stored_diag_const_iterator = const StoredDiagnostic *;
589 stored_diag_const_iterator stored_diag_begin() const {
590 return StoredDiagnostics.begin();
593 stored_diag_iterator stored_diag_begin() {
594 return StoredDiagnostics.begin();
597 stored_diag_const_iterator stored_diag_end() const {
598 return StoredDiagnostics.end();
601 stored_diag_iterator stored_diag_end() {
602 return StoredDiagnostics.end();
605 unsigned stored_diag_size() const { return StoredDiagnostics.size(); }
607 stored_diag_iterator stored_diag_afterDriver_begin() {
608 if (NumStoredDiagnosticsFromDriver > StoredDiagnostics.size())
609 NumStoredDiagnosticsFromDriver = 0;
610 return StoredDiagnostics.begin() + NumStoredDiagnosticsFromDriver;
613 using cached_completion_iterator =
614 std::vector<CachedCodeCompletionResult>::iterator;
616 cached_completion_iterator cached_completion_begin() {
617 return CachedCompletionResults.begin();
620 cached_completion_iterator cached_completion_end() {
621 return CachedCompletionResults.end();
624 unsigned cached_completion_size() const {
625 return CachedCompletionResults.size();
628 /// Returns an iterator range for the local preprocessing entities
629 /// of the local Preprocessor, if this is a parsed source file, or the loaded
630 /// preprocessing entities of the primary module if this is an AST file.
631 llvm::iterator_range<PreprocessingRecord::iterator>
632 getLocalPreprocessingEntities() const;
634 /// Type for a function iterating over a number of declarations.
635 /// \returns true to continue iteration and false to abort.
636 using DeclVisitorFn = bool (*)(void *context, const Decl *D);
638 /// Iterate over local declarations (locally parsed if this is a parsed
639 /// source file or the loaded declarations of the primary module if this is an
641 /// \returns true if the iteration was complete or false if it was aborted.
642 bool visitLocalTopLevelDecls(void *context, DeclVisitorFn Fn);
644 /// Get the PCH file if one was included.
645 const FileEntry *getPCHFile();
647 /// Returns true if the ASTUnit was constructed from a serialized
649 bool isModuleFile() const;
651 std::unique_ptr<llvm::MemoryBuffer>
652 getBufferForFile(StringRef Filename, std::string *ErrorStr = nullptr);
654 /// Determine what kind of translation unit this AST represents.
655 TranslationUnitKind getTranslationUnitKind() const { return TUKind; }
657 /// Determine the input kind this AST unit represents.
658 InputKind getInputKind() const;
660 /// A mapping from a file name to the memory buffer that stores the
661 /// remapped contents of that file.
662 using RemappedFile = std::pair<std::string, llvm::MemoryBuffer *>;
664 /// Create a ASTUnit. Gets ownership of the passed CompilerInvocation.
665 static std::unique_ptr<ASTUnit>
666 create(std::shared_ptr<CompilerInvocation> CI,
667 IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
668 CaptureDiagsKind CaptureDiagnostics, bool UserFilesAreVolatile);
671 /// Load options and the preprocessor state.
672 LoadPreprocessorOnly,
674 /// Load the AST, but do not restore Sema state.
677 /// Load everything, including Sema.
681 /// Create a ASTUnit from an AST file.
683 /// \param Filename - The AST file to load.
685 /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and
686 /// creating modules.
687 /// \param Diags - The diagnostics engine to use for reporting errors; its
688 /// lifetime is expected to extend past that of the returned ASTUnit.
690 /// \returns - The initialized ASTUnit or null if the AST failed to load.
691 static std::unique_ptr<ASTUnit> LoadFromASTFile(
692 const std::string &Filename, const PCHContainerReader &PCHContainerRdr,
693 WhatToLoad ToLoad, IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
694 const FileSystemOptions &FileSystemOpts, bool UseDebugInfo = false,
695 bool OnlyLocalDecls = false, ArrayRef<RemappedFile> RemappedFiles = None,
696 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
697 bool AllowPCHWithCompilerErrors = false,
698 bool UserFilesAreVolatile = false);
701 /// Helper function for \c LoadFromCompilerInvocation() and
702 /// \c LoadFromCommandLine(), which loads an AST from a compiler invocation.
704 /// \param PrecompilePreambleAfterNParses After how many parses the preamble
705 /// of this translation unit should be precompiled, to improve the performance
706 /// of reparsing. Set to zero to disable preambles.
708 /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
709 /// Note that preamble is saved to a temporary directory on a RealFileSystem,
710 /// so in order for it to be loaded correctly, VFS should have access to
711 /// it(i.e., be an overlay over RealFileSystem).
713 /// \returns \c true if a catastrophic failure occurred (which means that the
714 /// \c ASTUnit itself is invalid), or \c false otherwise.
715 bool LoadFromCompilerInvocation(
716 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
717 unsigned PrecompilePreambleAfterNParses,
718 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS);
721 /// Create an ASTUnit from a source file, via a CompilerInvocation
722 /// object, by invoking the optionally provided ASTFrontendAction.
724 /// \param CI - The compiler invocation to use; it must have exactly one input
725 /// source file. The ASTUnit takes ownership of the CompilerInvocation object.
727 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
728 /// creating modules.
730 /// \param Diags - The diagnostics engine to use for reporting errors; its
731 /// lifetime is expected to extend past that of the returned ASTUnit.
733 /// \param Action - The ASTFrontendAction to invoke. Its ownership is not
736 /// \param Unit - optionally an already created ASTUnit. Its ownership is not
739 /// \param Persistent - if true the returned ASTUnit will be complete.
740 /// false means the caller is only interested in getting info through the
741 /// provided \see Action.
743 /// \param ErrAST - If non-null and parsing failed without any AST to return
744 /// (e.g. because the PCH could not be loaded), this accepts the ASTUnit
745 /// mainly to allow the caller to see the diagnostics.
746 /// This will only receive an ASTUnit if a new one was created. If an already
747 /// created ASTUnit was passed in \p Unit then the caller can check that.
749 static ASTUnit *LoadFromCompilerInvocationAction(
750 std::shared_ptr<CompilerInvocation> CI,
751 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
752 IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
753 FrontendAction *Action = nullptr, ASTUnit *Unit = nullptr,
754 bool Persistent = true, StringRef ResourceFilesPath = StringRef(),
755 bool OnlyLocalDecls = false,
756 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
757 unsigned PrecompilePreambleAfterNParses = 0,
758 bool CacheCodeCompletionResults = false,
759 bool IncludeBriefCommentsInCodeCompletion = false,
760 bool UserFilesAreVolatile = false,
761 std::unique_ptr<ASTUnit> *ErrAST = nullptr);
763 /// LoadFromCompilerInvocation - Create an ASTUnit from a source file, via a
764 /// CompilerInvocation object.
766 /// \param CI - The compiler invocation to use; it must have exactly one input
767 /// source file. The ASTUnit takes ownership of the CompilerInvocation object.
769 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
770 /// creating modules.
772 /// \param Diags - The diagnostics engine to use for reporting errors; its
773 /// lifetime is expected to extend past that of the returned ASTUnit.
775 // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
776 // shouldn't need to specify them at construction time.
777 static std::unique_ptr<ASTUnit> LoadFromCompilerInvocation(
778 std::shared_ptr<CompilerInvocation> CI,
779 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
780 IntrusiveRefCntPtr<DiagnosticsEngine> Diags, FileManager *FileMgr,
781 bool OnlyLocalDecls = false,
782 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
783 unsigned PrecompilePreambleAfterNParses = 0,
784 TranslationUnitKind TUKind = TU_Complete,
785 bool CacheCodeCompletionResults = false,
786 bool IncludeBriefCommentsInCodeCompletion = false,
787 bool UserFilesAreVolatile = false);
789 /// LoadFromCommandLine - Create an ASTUnit from a vector of command line
790 /// arguments, which must specify exactly one source file.
792 /// \param ArgBegin - The beginning of the argument vector.
794 /// \param ArgEnd - The end of the argument vector.
796 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
797 /// creating modules.
799 /// \param Diags - The diagnostics engine to use for reporting errors; its
800 /// lifetime is expected to extend past that of the returned ASTUnit.
802 /// \param ResourceFilesPath - The path to the compiler resource files.
804 /// \param ModuleFormat - If provided, uses the specific module format.
806 /// \param ErrAST - If non-null and parsing failed without any AST to return
807 /// (e.g. because the PCH could not be loaded), this accepts the ASTUnit
808 /// mainly to allow the caller to see the diagnostics.
810 /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
811 /// Note that preamble is saved to a temporary directory on a RealFileSystem,
812 /// so in order for it to be loaded correctly, VFS should have access to
813 /// it(i.e., be an overlay over RealFileSystem). RealFileSystem will be used
814 /// if \p VFS is nullptr.
816 // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
817 // shouldn't need to specify them at construction time.
818 static ASTUnit *LoadFromCommandLine(
819 const char **ArgBegin, const char **ArgEnd,
820 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
821 IntrusiveRefCntPtr<DiagnosticsEngine> Diags, StringRef ResourceFilesPath,
822 bool OnlyLocalDecls = false,
823 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
824 ArrayRef<RemappedFile> RemappedFiles = None,
825 bool RemappedFilesKeepOriginalName = true,
826 unsigned PrecompilePreambleAfterNParses = 0,
827 TranslationUnitKind TUKind = TU_Complete,
828 bool CacheCodeCompletionResults = false,
829 bool IncludeBriefCommentsInCodeCompletion = false,
830 bool AllowPCHWithCompilerErrors = false,
831 SkipFunctionBodiesScope SkipFunctionBodies =
832 SkipFunctionBodiesScope::None,
833 bool SingleFileParse = false, bool UserFilesAreVolatile = false,
834 bool ForSerialization = false,
835 llvm::Optional<StringRef> ModuleFormat = llvm::None,
836 std::unique_ptr<ASTUnit> *ErrAST = nullptr,
837 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr);
839 /// Reparse the source files using the same command-line options that
840 /// were originally used to produce this translation unit.
842 /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
843 /// Note that preamble is saved to a temporary directory on a RealFileSystem,
844 /// so in order for it to be loaded correctly, VFS should give an access to
845 /// this(i.e. be an overlay over RealFileSystem).
846 /// FileMgr->getVirtualFileSystem() will be used if \p VFS is nullptr.
848 /// \returns True if a failure occurred that causes the ASTUnit not to
849 /// contain any translation-unit information, false otherwise.
850 bool Reparse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
851 ArrayRef<RemappedFile> RemappedFiles = None,
852 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr);
854 /// Free data that will be re-generated on the next parse.
856 /// Preamble-related data is not affected.
857 void ResetForParse();
859 /// Perform code completion at the given file, line, and
860 /// column within this translation unit.
862 /// \param File The file in which code completion will occur.
864 /// \param Line The line at which code completion will occur.
866 /// \param Column The column at which code completion will occur.
868 /// \param IncludeMacros Whether to include macros in the code-completion
871 /// \param IncludeCodePatterns Whether to include code patterns (such as a
872 /// for loop) in the code-completion results.
874 /// \param IncludeBriefComments Whether to include brief documentation within
875 /// the set of code completions returned.
877 /// FIXME: The Diag, LangOpts, SourceMgr, FileMgr, StoredDiagnostics, and
878 /// OwnedBuffers parameters are all disgusting hacks. They will go away.
879 void CodeComplete(StringRef File, unsigned Line, unsigned Column,
880 ArrayRef<RemappedFile> RemappedFiles, bool IncludeMacros,
881 bool IncludeCodePatterns, bool IncludeBriefComments,
882 CodeCompleteConsumer &Consumer,
883 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
884 DiagnosticsEngine &Diag, LangOptions &LangOpts,
885 SourceManager &SourceMgr, FileManager &FileMgr,
886 SmallVectorImpl<StoredDiagnostic> &StoredDiagnostics,
887 SmallVectorImpl<const llvm::MemoryBuffer *> &OwnedBuffers);
889 /// Save this translation unit to a file with the given name.
891 /// \returns true if there was a file error or false if the save was
893 bool Save(StringRef File);
895 /// Serialize this translation unit with the given output stream.
897 /// \returns True if an error occurred, false otherwise.
898 bool serialize(raw_ostream &OS);
903 #endif // LLVM_CLANG_FRONTEND_ASTUNIT_H