1 //===- ASTUnit.h - ASTUnit utility ------------------------------*- 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 // ASTUnit utility class. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef LLVM_CLANG_FRONTEND_ASTUNIT_H 14 #define LLVM_CLANG_FRONTEND_ASTUNIT_H 15 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" 41 #include <cassert> 42 #include <cstddef> 43 #include <cstdint> 44 #include <memory> 45 #include <string> 46 #include <utility> 47 #include <vector> 48 49 namespace llvm { 50 51 class MemoryBuffer; 52 53 namespace vfs { 54 55 class FileSystem; 56 57 } // namespace vfs 58 } // namespace llvm 59 60 namespace clang { 61 62 class ASTContext; 63 class ASTDeserializationListener; 64 class ASTMutationListener; 65 class ASTReader; 66 class CompilerInstance; 67 class CompilerInvocation; 68 class Decl; 69 class FileEntry; 70 class FileManager; 71 class FrontendAction; 72 class HeaderSearch; 73 class InputKind; 74 class InMemoryModuleCache; 75 class PCHContainerOperations; 76 class PCHContainerReader; 77 class Preprocessor; 78 class PreprocessorOptions; 79 class Sema; 80 class TargetInfo; 81 82 /// \brief Enumerates the available scopes for skipping function bodies. 83 enum class SkipFunctionBodiesScope { None, Preamble, PreambleAndMainFile }; 84 85 /// \brief Enumerates the available kinds for capturing diagnostics. 86 enum class CaptureDiagsKind { None, All, AllWithoutNonErrorsFromIncludes }; 87 88 /// Utility class for loading a ASTContext from an AST file. 89 class ASTUnit { 90 public: 91 struct StandaloneFixIt { 92 std::pair<unsigned, unsigned> RemoveRange; 93 std::pair<unsigned, unsigned> InsertFromRange; 94 std::string CodeToInsert; 95 bool BeforePreviousInsertions; 96 }; 97 98 struct StandaloneDiagnostic { 99 unsigned ID; 100 DiagnosticsEngine::Level Level; 101 std::string Message; 102 std::string Filename; 103 unsigned LocOffset; 104 std::vector<std::pair<unsigned, unsigned>> Ranges; 105 std::vector<StandaloneFixIt> FixIts; 106 }; 107 108 private: 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; 123 124 struct ASTWriterData; 125 std::unique_ptr<ASTWriterData> WriterData; 126 127 FileSystemOptions FileSystemOpts; 128 129 /// The AST consumer that received information about the translation 130 /// unit as it was parsed or loaded. 131 std::unique_ptr<ASTConsumer> Consumer; 132 133 /// The semantic analysis object used to type-check the translation 134 /// unit. 135 std::unique_ptr<Sema> TheSema; 136 137 /// Optional owned invocation, just used to make the invocation used in 138 /// LoadFromCommandLine available. 139 std::shared_ptr<CompilerInvocation> Invocation; 140 141 /// Fake module loader: the AST unit doesn't need to load any modules. 142 TrivialModuleLoader ModuleLoader; 143 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; 148 149 /// Whether to capture any diagnostics produced. 150 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None; 151 152 /// Track whether the main file was loaded from an AST or not. 153 bool MainFileIsAST; 154 155 /// What kind of translation unit this AST represents. 156 TranslationUnitKind TUKind = TU_Complete; 157 158 /// Whether we should time each operation. 159 bool WantTiming; 160 161 /// Whether the ASTUnit should delete the remapped buffers. 162 bool OwnsRemappedFileBuffers = true; 163 164 /// Track the top-level decls which appeared in an ASTUnit which was loaded 165 /// from a source file. 166 // 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; 172 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, std::unique_ptr<LocDeclsTy>>; 176 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; 180 181 /// The name of the original source file used to generate this ASTUnit. 182 std::string OriginalSourceFile; 183 184 /// The set of diagnostics produced when creating the preamble. 185 SmallVector<StandaloneDiagnostic, 4> PreambleDiagnostics; 186 187 /// The set of diagnostics produced when creating this 188 /// translation unit. 189 SmallVector<StoredDiagnostic, 4> StoredDiagnostics; 190 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; 194 195 /// The number of stored diagnostics that come from the driver 196 /// itself. 197 /// 198 /// Diagnostics that come from the driver are retained from one parse to 199 /// the next. 200 unsigned NumStoredDiagnosticsFromDriver = 0; 201 202 /// Counter that determines when we want to try building a 203 /// precompiled preamble. 204 /// 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; 212 213 /// Counter indicating how often the preamble was build in total. 214 unsigned PreambleCounter = 0; 215 216 /// Cache pairs "filename - source location" 217 /// 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; 223 224 /// The contents of the preamble. 225 llvm::Optional<PrecompiledPreamble> Preamble; 226 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 229 /// preamble. 230 std::unique_ptr<llvm::MemoryBuffer> SavedMainFileBuffer; 231 232 /// The number of warnings that occurred while parsing the preamble. 233 /// 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; 239 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; 243 244 /// Whether we should be caching code-completion results. 245 bool ShouldCacheCodeCompletionResults : 1; 246 247 /// Whether to include brief documentation within the set of code 248 /// completions cached. 249 bool IncludeBriefCommentsInCodeCompletion : 1; 250 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; 254 255 static void ConfigureDiags(IntrusiveRefCntPtr<DiagnosticsEngine> Diags, 256 ASTUnit &AST, CaptureDiagsKind CaptureDiagnostics); 257 258 void TranslateStoredDiagnostics(FileManager &FileMgr, 259 SourceManager &SrcMan, 260 const SmallVectorImpl<StandaloneDiagnostic> &Diags, 261 SmallVectorImpl<StoredDiagnostic> &Out); 262 263 void clearFileLevelDecls(); 264 265 public: 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 270 /// result. 271 CodeCompletionString *Completion; 272 273 /// A bitmask that indicates which code-completion contexts should 274 /// contain this completion result. 275 /// 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; 281 282 /// The priority given to this code-completion result. 283 unsigned Priority; 284 285 /// The libclang cursor kind corresponding to this code-completion 286 /// result. 287 CXCursorKind Kind; 288 289 /// The availability of this code-completion result. 290 CXAvailabilityKind Availability; 291 292 /// The simplified type class for a non-macro completion result. 293 SimplifiedTypeClass TypeClass; 294 295 /// The type of a non-macro completion result, stored as a unique 296 /// integer used by the string map of cached completion types. 297 /// 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. 301 unsigned Type; 302 }; 303 304 /// Retrieve the mapping from formatted type names to unique type 305 /// identifiers. getCachedCompletionTypes()306 llvm::StringMap<unsigned> &getCachedCompletionTypes() { 307 return CachedCompletionTypes; 308 } 309 310 /// Retrieve the allocator used to cache global code completions. 311 std::shared_ptr<GlobalCodeCompletionAllocator> getCachedCompletionAllocator()312 getCachedCompletionAllocator() { 313 return CachedCompletionAllocator; 314 } 315 getCodeCompletionTUInfo()316 CodeCompletionTUInfo &getCodeCompletionTUInfo() { 317 if (!CCTUInfo) 318 CCTUInfo = std::make_unique<CodeCompletionTUInfo>( 319 std::make_shared<GlobalCodeCompletionAllocator>()); 320 return *CCTUInfo; 321 } 322 323 private: 324 /// Allocator used to store cached code completions. 325 std::shared_ptr<GlobalCodeCompletionAllocator> CachedCompletionAllocator; 326 327 std::unique_ptr<CodeCompletionTUInfo> CCTUInfo; 328 329 /// The set of cached code-completion results. 330 std::vector<CachedCodeCompletionResult> CachedCompletionResults; 331 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; 335 336 /// A string hash of the top-level declaration and macro definition 337 /// names processed the last time that we reparsed the file. 338 /// 339 /// This hash value is used to determine when we need to refresh the 340 /// global code-completion cache. 341 unsigned CompletionCacheTopLevelHashValue = 0; 342 343 /// A string hash of the top-level declaration and macro definition 344 /// names processed the last time that we reparsed the precompiled preamble. 345 /// 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; 349 350 /// The current hash value for the top-level declaration and macro 351 /// definition names 352 unsigned CurrentTopLevelHashValue = 0; 353 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; 357 358 /// \brief Enumerator specifying the scope for skipping function bodies. 359 SkipFunctionBodiesScope SkipFunctionBodies = SkipFunctionBodiesScope::None; 360 361 /// Cache any "global" code-completion results, so that we can avoid 362 /// recomputing them with each completion. 363 void CacheCodeCompletionResults(); 364 365 /// Clear out and deallocate 366 void ClearCachedCompletionResults(); 367 368 explicit ASTUnit(bool MainFileIsAST); 369 370 bool Parse(std::shared_ptr<PCHContainerOperations> PCHContainerOps, 371 std::unique_ptr<llvm::MemoryBuffer> OverrideMainBuffer, 372 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS); 373 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(); 380 381 /// Transfers ownership of the objects (like SourceManager) from 382 /// \param CI to this ASTUnit. 383 void transferASTDataFromCompilerInstance(CompilerInstance &CI); 384 385 /// Allows us to assert that ASTUnit is not being used concurrently, 386 /// which is not supported. 387 /// 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 std::recursive_mutex in debug; 394 395 public: 396 ConcurrencyState(); 397 ~ConcurrencyState(); 398 399 void start(); 400 void finish(); 401 }; 402 ConcurrencyState ConcurrencyCheckValue; 403 404 public: 405 friend class ConcurrencyCheck; 406 407 class ConcurrencyCheck { 408 ASTUnit &Self; 409 410 public: ConcurrencyCheck(ASTUnit & Self)411 explicit ConcurrencyCheck(ASTUnit &Self) : Self(Self) { 412 Self.ConcurrencyCheckValue.start(); 413 } 414 ~ConcurrencyCheck()415 ~ConcurrencyCheck() { 416 Self.ConcurrencyCheckValue.finish(); 417 } 418 }; 419 420 ASTUnit(const ASTUnit &) = delete; 421 ASTUnit &operator=(const ASTUnit &) = delete; 422 ~ASTUnit(); 423 isMainFileAST()424 bool isMainFileAST() const { return MainFileIsAST; } 425 isUnsafeToFree()426 bool isUnsafeToFree() const { return UnsafeToFree; } setUnsafeToFree(bool Value)427 void setUnsafeToFree(bool Value) { UnsafeToFree = Value; } 428 getDiagnostics()429 const DiagnosticsEngine &getDiagnostics() const { return *Diagnostics; } getDiagnostics()430 DiagnosticsEngine &getDiagnostics() { return *Diagnostics; } 431 getSourceManager()432 const SourceManager &getSourceManager() const { return *SourceMgr; } getSourceManager()433 SourceManager &getSourceManager() { return *SourceMgr; } 434 getPreprocessor()435 const Preprocessor &getPreprocessor() const { return *PP; } getPreprocessor()436 Preprocessor &getPreprocessor() { return *PP; } getPreprocessorPtr()437 std::shared_ptr<Preprocessor> getPreprocessorPtr() const { return PP; } 438 getASTContext()439 const ASTContext &getASTContext() const { return *Ctx; } getASTContext()440 ASTContext &getASTContext() { return *Ctx; } 441 setASTContext(ASTContext * ctx)442 void setASTContext(ASTContext *ctx) { Ctx = ctx; } 443 void setPreprocessor(std::shared_ptr<Preprocessor> pp); 444 445 /// Enable source-range based diagnostic messages. 446 /// 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(); 453 hasSema()454 bool hasSema() const { return (bool)TheSema; } 455 getSema()456 Sema &getSema() const { 457 assert(TheSema && "ASTUnit does not have a Sema object!"); 458 return *TheSema; 459 } 460 getLangOpts()461 const LangOptions &getLangOpts() const { 462 assert(LangOpts && "ASTUnit does not have language options"); 463 return *LangOpts; 464 } 465 getHeaderSearchOpts()466 const HeaderSearchOptions &getHeaderSearchOpts() const { 467 assert(HSOpts && "ASTUnit does not have header search options"); 468 return *HSOpts; 469 } 470 getPreprocessorOpts()471 const PreprocessorOptions &getPreprocessorOpts() const { 472 assert(PPOpts && "ASTUnit does not have preprocessor options"); 473 return *PPOpts; 474 } 475 getFileManager()476 const FileManager &getFileManager() const { return *FileMgr; } getFileManager()477 FileManager &getFileManager() { return *FileMgr; } 478 getFileSystemOpts()479 const FileSystemOptions &getFileSystemOpts() const { return FileSystemOpts; } 480 481 IntrusiveRefCntPtr<ASTReader> getASTReader() const; 482 getOriginalSourceFileName()483 StringRef getOriginalSourceFileName() const { 484 return OriginalSourceFile; 485 } 486 487 ASTMutationListener *getASTMutationListener(); 488 ASTDeserializationListener *getDeserializationListener(); 489 getOnlyLocalDecls()490 bool getOnlyLocalDecls() const { return OnlyLocalDecls; } 491 getOwnsRemappedFileBuffers()492 bool getOwnsRemappedFileBuffers() const { return OwnsRemappedFileBuffers; } setOwnsRemappedFileBuffers(bool val)493 void setOwnsRemappedFileBuffers(bool val) { OwnsRemappedFileBuffers = val; } 494 495 StringRef getMainFileName() const; 496 497 /// If this ASTUnit came from an AST file, returns the filename for it. 498 StringRef getASTFileName() const; 499 500 using top_level_iterator = std::vector<Decl *>::iterator; 501 top_level_begin()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(); 507 } 508 top_level_end()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(); 514 } 515 top_level_size()516 std::size_t top_level_size() const { 517 assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!"); 518 return TopLevelDeclsInPreamble.size() + TopLevelDecls.size(); 519 } 520 top_level_empty()521 bool top_level_empty() const { 522 assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!"); 523 return TopLevelDeclsInPreamble.empty() && TopLevelDecls.empty(); 524 } 525 526 /// Add a new top-level declaration. addTopLevelDecl(Decl * D)527 void addTopLevelDecl(Decl *D) { 528 TopLevelDecls.push_back(D); 529 } 530 531 /// Add a new local file-level declaration. 532 void addFileLevelDecl(Decl *D); 533 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 536 /// a range. 537 void findFileRegionDecls(FileID File, unsigned Offset, unsigned Length, 538 SmallVectorImpl<Decl *> &Decls); 539 540 /// Retrieve a reference to the current top-level name hash value. 541 /// 542 /// Note: This is used internally by the top-level tracking action getCurrentTopLevelHashValue()543 unsigned &getCurrentTopLevelHashValue() { return CurrentTopLevelHashValue; } 544 545 /// Get the source location for the given file:line:col triplet. 546 /// 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; 552 553 /// Get the source location for the given file:offset pair. 554 SourceLocation getLocation(const FileEntry *File, unsigned Offset) const; 555 556 /// If \p Loc is a loaded location from the preamble, returns 557 /// the corresponding local location of the main file, otherwise it returns 558 /// \p Loc. 559 SourceLocation mapLocationFromPreamble(SourceLocation Loc) const; 560 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; 565 566 bool isInPreambleFileID(SourceLocation Loc) const; 567 bool isInMainFileID(SourceLocation Loc) const; 568 SourceLocation getStartOfMainFileID() const; 569 SourceLocation getEndOfPreambleFileID() const; 570 571 /// \see mapLocationFromPreamble. mapRangeFromPreamble(SourceRange R)572 SourceRange mapRangeFromPreamble(SourceRange R) const { 573 return SourceRange(mapLocationFromPreamble(R.getBegin()), 574 mapLocationFromPreamble(R.getEnd())); 575 } 576 577 /// \see mapLocationToPreamble. mapRangeToPreamble(SourceRange R)578 SourceRange mapRangeToPreamble(SourceRange R) const { 579 return SourceRange(mapLocationToPreamble(R.getBegin()), 580 mapLocationToPreamble(R.getEnd())); 581 } 582 getPreambleCounterForTests()583 unsigned getPreambleCounterForTests() const { return PreambleCounter; } 584 585 // Retrieve the diagnostics associated with this AST 586 using stored_diag_iterator = StoredDiagnostic *; 587 using stored_diag_const_iterator = const StoredDiagnostic *; 588 stored_diag_begin()589 stored_diag_const_iterator stored_diag_begin() const { 590 return StoredDiagnostics.begin(); 591 } 592 stored_diag_begin()593 stored_diag_iterator stored_diag_begin() { 594 return StoredDiagnostics.begin(); 595 } 596 stored_diag_end()597 stored_diag_const_iterator stored_diag_end() const { 598 return StoredDiagnostics.end(); 599 } 600 stored_diag_end()601 stored_diag_iterator stored_diag_end() { 602 return StoredDiagnostics.end(); 603 } 604 stored_diag_size()605 unsigned stored_diag_size() const { return StoredDiagnostics.size(); } 606 stored_diag_afterDriver_begin()607 stored_diag_iterator stored_diag_afterDriver_begin() { 608 if (NumStoredDiagnosticsFromDriver > StoredDiagnostics.size()) 609 NumStoredDiagnosticsFromDriver = 0; 610 return StoredDiagnostics.begin() + NumStoredDiagnosticsFromDriver; 611 } 612 613 using cached_completion_iterator = 614 std::vector<CachedCodeCompletionResult>::iterator; 615 cached_completion_begin()616 cached_completion_iterator cached_completion_begin() { 617 return CachedCompletionResults.begin(); 618 } 619 cached_completion_end()620 cached_completion_iterator cached_completion_end() { 621 return CachedCompletionResults.end(); 622 } 623 cached_completion_size()624 unsigned cached_completion_size() const { 625 return CachedCompletionResults.size(); 626 } 627 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; 633 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); 637 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 640 /// AST file). 641 /// \returns true if the iteration was complete or false if it was aborted. 642 bool visitLocalTopLevelDecls(void *context, DeclVisitorFn Fn); 643 644 /// Get the PCH file if one was included. 645 const FileEntry *getPCHFile(); 646 647 /// Returns true if the ASTUnit was constructed from a serialized 648 /// module file. 649 bool isModuleFile() const; 650 651 std::unique_ptr<llvm::MemoryBuffer> 652 getBufferForFile(StringRef Filename, std::string *ErrorStr = nullptr); 653 654 /// Determine what kind of translation unit this AST represents. getTranslationUnitKind()655 TranslationUnitKind getTranslationUnitKind() const { return TUKind; } 656 657 /// Determine the input kind this AST unit represents. 658 InputKind getInputKind() const; 659 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 *>; 663 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); 669 670 enum WhatToLoad { 671 /// Load options and the preprocessor state. 672 LoadPreprocessorOnly, 673 674 /// Load the AST, but do not restore Sema state. 675 LoadASTOnly, 676 677 /// Load everything, including Sema. 678 LoadEverything 679 }; 680 681 /// Create a ASTUnit from an AST file. 682 /// 683 /// \param Filename - The AST file to load. 684 /// 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. 689 /// 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 AllowASTWithCompilerErrors = false, 698 bool UserFilesAreVolatile = false); 699 700 private: 701 /// Helper function for \c LoadFromCompilerInvocation() and 702 /// \c LoadFromCommandLine(), which loads an AST from a compiler invocation. 703 /// 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. 707 /// 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). 712 /// 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); 719 720 public: 721 /// Create an ASTUnit from a source file, via a CompilerInvocation 722 /// object, by invoking the optionally provided ASTFrontendAction. 723 /// 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. 726 /// 727 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and 728 /// creating modules. 729 /// 730 /// \param Diags - The diagnostics engine to use for reporting errors; its 731 /// lifetime is expected to extend past that of the returned ASTUnit. 732 /// 733 /// \param Action - The ASTFrontendAction to invoke. Its ownership is not 734 /// transferred. 735 /// 736 /// \param Unit - optionally an already created ASTUnit. Its ownership is not 737 /// transferred. 738 /// 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. 742 /// 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. 748 /// 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 UserFilesAreVolatile = false, 760 std::unique_ptr<ASTUnit> *ErrAST = nullptr); 761 762 /// LoadFromCompilerInvocation - Create an ASTUnit from a source file, via a 763 /// CompilerInvocation object. 764 /// 765 /// \param CI - The compiler invocation to use; it must have exactly one input 766 /// source file. The ASTUnit takes ownership of the CompilerInvocation object. 767 /// 768 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and 769 /// creating modules. 770 /// 771 /// \param Diags - The diagnostics engine to use for reporting errors; its 772 /// lifetime is expected to extend past that of the returned ASTUnit. 773 // 774 // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we 775 // shouldn't need to specify them at construction time. 776 static std::unique_ptr<ASTUnit> LoadFromCompilerInvocation( 777 std::shared_ptr<CompilerInvocation> CI, 778 std::shared_ptr<PCHContainerOperations> PCHContainerOps, 779 IntrusiveRefCntPtr<DiagnosticsEngine> Diags, FileManager *FileMgr, 780 bool OnlyLocalDecls = false, 781 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None, 782 unsigned PrecompilePreambleAfterNParses = 0, 783 TranslationUnitKind TUKind = TU_Complete, 784 bool CacheCodeCompletionResults = false, 785 bool IncludeBriefCommentsInCodeCompletion = false, 786 bool UserFilesAreVolatile = false); 787 788 /// LoadFromCommandLine - Create an ASTUnit from a vector of command line 789 /// arguments, which must specify exactly one source file. 790 /// 791 /// \param ArgBegin - The beginning of the argument vector. 792 /// 793 /// \param ArgEnd - The end of the argument vector. 794 /// 795 /// \param PCHContainerOps - The PCHContainerOperations to use for loading and 796 /// creating modules. 797 /// 798 /// \param Diags - The diagnostics engine to use for reporting errors; its 799 /// lifetime is expected to extend past that of the returned ASTUnit. 800 /// 801 /// \param ResourceFilesPath - The path to the compiler resource files. 802 /// 803 /// \param ModuleFormat - If provided, uses the specific module format. 804 /// 805 /// \param ErrAST - If non-null and parsing failed without any AST to return 806 /// (e.g. because the PCH could not be loaded), this accepts the ASTUnit 807 /// mainly to allow the caller to see the diagnostics. 808 /// 809 /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses. 810 /// Note that preamble is saved to a temporary directory on a RealFileSystem, 811 /// so in order for it to be loaded correctly, VFS should have access to 812 /// it(i.e., be an overlay over RealFileSystem). RealFileSystem will be used 813 /// if \p VFS is nullptr. 814 /// 815 // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we 816 // shouldn't need to specify them at construction time. 817 static ASTUnit *LoadFromCommandLine( 818 const char **ArgBegin, const char **ArgEnd, 819 std::shared_ptr<PCHContainerOperations> PCHContainerOps, 820 IntrusiveRefCntPtr<DiagnosticsEngine> Diags, StringRef ResourceFilesPath, 821 bool OnlyLocalDecls = false, 822 CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None, 823 ArrayRef<RemappedFile> RemappedFiles = None, 824 bool RemappedFilesKeepOriginalName = true, 825 unsigned PrecompilePreambleAfterNParses = 0, 826 TranslationUnitKind TUKind = TU_Complete, 827 bool CacheCodeCompletionResults = false, 828 bool IncludeBriefCommentsInCodeCompletion = false, 829 bool AllowPCHWithCompilerErrors = false, 830 SkipFunctionBodiesScope SkipFunctionBodies = 831 SkipFunctionBodiesScope::None, 832 bool SingleFileParse = false, bool UserFilesAreVolatile = false, 833 bool ForSerialization = false, 834 bool RetainExcludedConditionalBlocks = false, 835 llvm::Optional<StringRef> ModuleFormat = llvm::None, 836 std::unique_ptr<ASTUnit> *ErrAST = nullptr, 837 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr); 838 839 /// Reparse the source files using the same command-line options that 840 /// were originally used to produce this translation unit. 841 /// 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. 847 /// 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); 853 854 /// Free data that will be re-generated on the next parse. 855 /// 856 /// Preamble-related data is not affected. 857 void ResetForParse(); 858 859 /// Perform code completion at the given file, line, and 860 /// column within this translation unit. 861 /// 862 /// \param File The file in which code completion will occur. 863 /// 864 /// \param Line The line at which code completion will occur. 865 /// 866 /// \param Column The column at which code completion will occur. 867 /// 868 /// \param IncludeMacros Whether to include macros in the code-completion 869 /// results. 870 /// 871 /// \param IncludeCodePatterns Whether to include code patterns (such as a 872 /// for loop) in the code-completion results. 873 /// 874 /// \param IncludeBriefComments Whether to include brief documentation within 875 /// the set of code completions returned. 876 /// 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); 888 889 /// Save this translation unit to a file with the given name. 890 /// 891 /// \returns true if there was a file error or false if the save was 892 /// successful. 893 bool Save(StringRef File); 894 895 /// Serialize this translation unit with the given output stream. 896 /// 897 /// \returns True if an error occurred, false otherwise. 898 bool serialize(raw_ostream &OS); 899 }; 900 901 } // namespace clang 902 903 #endif // LLVM_CLANG_FRONTEND_ASTUNIT_H 904