ASTUnit.h 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903
  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. #ifndef LLVM_CLANG_FRONTEND_ASTUNIT_H
  13. #define LLVM_CLANG_FRONTEND_ASTUNIT_H
  14. #include "clang-c/Index.h"
  15. #include "clang/AST/ASTContext.h"
  16. #include "clang/Basic/Diagnostic.h"
  17. #include "clang/Basic/FileSystemOptions.h"
  18. #include "clang/Basic/LLVM.h"
  19. #include "clang/Basic/LangOptions.h"
  20. #include "clang/Basic/SourceLocation.h"
  21. #include "clang/Basic/SourceManager.h"
  22. #include "clang/Basic/TargetOptions.h"
  23. #include "clang/Lex/HeaderSearchOptions.h"
  24. #include "clang/Lex/ModuleLoader.h"
  25. #include "clang/Lex/PreprocessingRecord.h"
  26. #include "clang/Sema/CodeCompleteConsumer.h"
  27. #include "clang/Serialization/ASTBitCodes.h"
  28. #include "clang/Frontend/PrecompiledPreamble.h"
  29. #include "llvm/ADT/ArrayRef.h"
  30. #include "llvm/ADT/DenseMap.h"
  31. #include "llvm/ADT/IntrusiveRefCntPtr.h"
  32. #include "llvm/ADT/None.h"
  33. #include "llvm/ADT/Optional.h"
  34. #include "llvm/ADT/STLExtras.h"
  35. #include "llvm/ADT/SmallVector.h"
  36. #include "llvm/ADT/StringMap.h"
  37. #include "llvm/ADT/StringRef.h"
  38. #include "llvm/ADT/iterator_range.h"
  39. #include <cassert>
  40. #include <cstddef>
  41. #include <cstdint>
  42. #include <memory>
  43. #include <string>
  44. #include <utility>
  45. #include <vector>
  46. namespace llvm {
  47. class MemoryBuffer;
  48. namespace vfs {
  49. class FileSystem;
  50. } // namespace vfs
  51. } // namespace llvm
  52. namespace clang {
  53. class ASTContext;
  54. class ASTDeserializationListener;
  55. class ASTMutationListener;
  56. class ASTReader;
  57. class CompilerInstance;
  58. class CompilerInvocation;
  59. class Decl;
  60. class FileEntry;
  61. class FileManager;
  62. class FrontendAction;
  63. class HeaderSearch;
  64. class InputKind;
  65. class InMemoryModuleCache;
  66. class PCHContainerOperations;
  67. class PCHContainerReader;
  68. class Preprocessor;
  69. class PreprocessorOptions;
  70. class Sema;
  71. class TargetInfo;
  72. /// \brief Enumerates the available scopes for skipping function bodies.
  73. enum class SkipFunctionBodiesScope { None, Preamble, PreambleAndMainFile };
  74. /// \brief Enumerates the available kinds for capturing diagnostics.
  75. enum class CaptureDiagsKind { None, All, AllWithoutNonErrorsFromIncludes };
  76. /// Utility class for loading a ASTContext from an AST file.
  77. class ASTUnit {
  78. public:
  79. struct StandaloneFixIt {
  80. std::pair<unsigned, unsigned> RemoveRange;
  81. std::pair<unsigned, unsigned> InsertFromRange;
  82. std::string CodeToInsert;
  83. bool BeforePreviousInsertions;
  84. };
  85. struct StandaloneDiagnostic {
  86. unsigned ID;
  87. DiagnosticsEngine::Level Level;
  88. std::string Message;
  89. std::string Filename;
  90. unsigned LocOffset;
  91. std::vector<std::pair<unsigned, unsigned>> Ranges;
  92. std::vector<StandaloneFixIt> FixIts;
  93. };
  94. private:
  95. std::shared_ptr<LangOptions> LangOpts;
  96. IntrusiveRefCntPtr<DiagnosticsEngine> Diagnostics;
  97. IntrusiveRefCntPtr<FileManager> FileMgr;
  98. IntrusiveRefCntPtr<SourceManager> SourceMgr;
  99. IntrusiveRefCntPtr<InMemoryModuleCache> ModuleCache;
  100. std::unique_ptr<HeaderSearch> HeaderInfo;
  101. IntrusiveRefCntPtr<TargetInfo> Target;
  102. std::shared_ptr<Preprocessor> PP;
  103. IntrusiveRefCntPtr<ASTContext> Ctx;
  104. std::shared_ptr<TargetOptions> TargetOpts;
  105. std::shared_ptr<HeaderSearchOptions> HSOpts;
  106. std::shared_ptr<PreprocessorOptions> PPOpts;
  107. IntrusiveRefCntPtr<ASTReader> Reader;
  108. bool HadModuleLoaderFatalFailure = false;
  109. struct ASTWriterData;
  110. std::unique_ptr<ASTWriterData> WriterData;
  111. FileSystemOptions FileSystemOpts;
  112. /// The AST consumer that received information about the translation
  113. /// unit as it was parsed or loaded.
  114. std::unique_ptr<ASTConsumer> Consumer;
  115. /// The semantic analysis object used to type-check the translation
  116. /// unit.
  117. std::unique_ptr<Sema> TheSema;
  118. /// Optional owned invocation, just used to make the invocation used in
  119. /// LoadFromCommandLine available.
  120. std::shared_ptr<CompilerInvocation> Invocation;
  121. /// Fake module loader: the AST unit doesn't need to load any modules.
  122. TrivialModuleLoader ModuleLoader;
  123. // OnlyLocalDecls - when true, walking this AST should only visit declarations
  124. // that come from the AST itself, not from included precompiled headers.
  125. // FIXME: This is temporary; eventually, CIndex will always do this.
  126. bool OnlyLocalDecls = false;
  127. /// Whether to capture any diagnostics produced.
  128. CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None;
  129. /// Track whether the main file was loaded from an AST or not.
  130. bool MainFileIsAST;
  131. /// What kind of translation unit this AST represents.
  132. TranslationUnitKind TUKind = TU_Complete;
  133. /// Whether we should time each operation.
  134. bool WantTiming;
  135. /// Whether the ASTUnit should delete the remapped buffers.
  136. bool OwnsRemappedFileBuffers = true;
  137. /// Track the top-level decls which appeared in an ASTUnit which was loaded
  138. /// from a source file.
  139. //
  140. // FIXME: This is just an optimization hack to avoid deserializing large parts
  141. // of a PCH file when using the Index library on an ASTUnit loaded from
  142. // source. In the long term we should make the Index library use efficient and
  143. // more scalable search mechanisms.
  144. std::vector<Decl*> TopLevelDecls;
  145. /// Sorted (by file offset) vector of pairs of file offset/Decl.
  146. using LocDeclsTy = SmallVector<std::pair<unsigned, Decl *>, 64>;
  147. using FileDeclsTy = llvm::DenseMap<FileID, LocDeclsTy *>;
  148. /// Map from FileID to the file-level declarations that it contains.
  149. /// The files and decls are only local (and non-preamble) ones.
  150. FileDeclsTy FileDecls;
  151. /// The name of the original source file used to generate this ASTUnit.
  152. std::string OriginalSourceFile;
  153. /// The set of diagnostics produced when creating the preamble.
  154. SmallVector<StandaloneDiagnostic, 4> PreambleDiagnostics;
  155. /// The set of diagnostics produced when creating this
  156. /// translation unit.
  157. SmallVector<StoredDiagnostic, 4> StoredDiagnostics;
  158. /// The set of diagnostics produced when failing to parse, e.g. due
  159. /// to failure to load the PCH.
  160. SmallVector<StoredDiagnostic, 4> FailedParseDiagnostics;
  161. /// The number of stored diagnostics that come from the driver
  162. /// itself.
  163. ///
  164. /// Diagnostics that come from the driver are retained from one parse to
  165. /// the next.
  166. unsigned NumStoredDiagnosticsFromDriver = 0;
  167. /// Counter that determines when we want to try building a
  168. /// precompiled preamble.
  169. ///
  170. /// If zero, we will never build a precompiled preamble. Otherwise,
  171. /// it's treated as a counter that decrements each time we reparse
  172. /// without the benefit of a precompiled preamble. When it hits 1,
  173. /// we'll attempt to rebuild the precompiled header. This way, if
  174. /// building the precompiled preamble fails, we won't try again for
  175. /// some number of calls.
  176. unsigned PreambleRebuildCountdown = 0;
  177. /// Counter indicating how often the preamble was build in total.
  178. unsigned PreambleCounter = 0;
  179. /// Cache pairs "filename - source location"
  180. ///
  181. /// Cache contains only source locations from preamble so it is
  182. /// guaranteed that they stay valid when the SourceManager is recreated.
  183. /// This cache is used when loading preamble to increase performance
  184. /// of that loading. It must be cleared when preamble is recreated.
  185. llvm::StringMap<SourceLocation> PreambleSrcLocCache;
  186. /// The contents of the preamble.
  187. llvm::Optional<PrecompiledPreamble> Preamble;
  188. /// When non-NULL, this is the buffer used to store the contents of
  189. /// the main file when it has been padded for use with the precompiled
  190. /// preamble.
  191. std::unique_ptr<llvm::MemoryBuffer> SavedMainFileBuffer;
  192. /// The number of warnings that occurred while parsing the preamble.
  193. ///
  194. /// This value will be used to restore the state of the \c DiagnosticsEngine
  195. /// object when re-using the precompiled preamble. Note that only the
  196. /// number of warnings matters, since we will not save the preamble
  197. /// when any errors are present.
  198. unsigned NumWarningsInPreamble = 0;
  199. /// A list of the serialization ID numbers for each of the top-level
  200. /// declarations parsed within the precompiled preamble.
  201. std::vector<serialization::DeclID> TopLevelDeclsInPreamble;
  202. /// Whether we should be caching code-completion results.
  203. bool ShouldCacheCodeCompletionResults : 1;
  204. /// Whether to include brief documentation within the set of code
  205. /// completions cached.
  206. bool IncludeBriefCommentsInCodeCompletion : 1;
  207. /// True if non-system source files should be treated as volatile
  208. /// (likely to change while trying to use them).
  209. bool UserFilesAreVolatile : 1;
  210. static void ConfigureDiags(IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
  211. ASTUnit &AST, CaptureDiagsKind CaptureDiagnostics);
  212. void TranslateStoredDiagnostics(FileManager &FileMgr,
  213. SourceManager &SrcMan,
  214. const SmallVectorImpl<StandaloneDiagnostic> &Diags,
  215. SmallVectorImpl<StoredDiagnostic> &Out);
  216. void clearFileLevelDecls();
  217. public:
  218. /// A cached code-completion result, which may be introduced in one of
  219. /// many different contexts.
  220. struct CachedCodeCompletionResult {
  221. /// The code-completion string corresponding to this completion
  222. /// result.
  223. CodeCompletionString *Completion;
  224. /// A bitmask that indicates which code-completion contexts should
  225. /// contain this completion result.
  226. ///
  227. /// The bits in the bitmask correspond to the values of
  228. /// CodeCompleteContext::Kind. To map from a completion context kind to a
  229. /// bit, shift 1 by that number of bits. Many completions can occur in
  230. /// several different contexts.
  231. uint64_t ShowInContexts;
  232. /// The priority given to this code-completion result.
  233. unsigned Priority;
  234. /// The libclang cursor kind corresponding to this code-completion
  235. /// result.
  236. CXCursorKind Kind;
  237. /// The availability of this code-completion result.
  238. CXAvailabilityKind Availability;
  239. /// The simplified type class for a non-macro completion result.
  240. SimplifiedTypeClass TypeClass;
  241. /// The type of a non-macro completion result, stored as a unique
  242. /// integer used by the string map of cached completion types.
  243. ///
  244. /// This value will be zero if the type is not known, or a unique value
  245. /// determined by the formatted type string. Se \c CachedCompletionTypes
  246. /// for more information.
  247. unsigned Type;
  248. };
  249. /// Retrieve the mapping from formatted type names to unique type
  250. /// identifiers.
  251. llvm::StringMap<unsigned> &getCachedCompletionTypes() {
  252. return CachedCompletionTypes;
  253. }
  254. /// Retrieve the allocator used to cache global code completions.
  255. std::shared_ptr<GlobalCodeCompletionAllocator>
  256. getCachedCompletionAllocator() {
  257. return CachedCompletionAllocator;
  258. }
  259. CodeCompletionTUInfo &getCodeCompletionTUInfo() {
  260. if (!CCTUInfo)
  261. CCTUInfo = llvm::make_unique<CodeCompletionTUInfo>(
  262. std::make_shared<GlobalCodeCompletionAllocator>());
  263. return *CCTUInfo;
  264. }
  265. private:
  266. /// Allocator used to store cached code completions.
  267. std::shared_ptr<GlobalCodeCompletionAllocator> CachedCompletionAllocator;
  268. std::unique_ptr<CodeCompletionTUInfo> CCTUInfo;
  269. /// The set of cached code-completion results.
  270. std::vector<CachedCodeCompletionResult> CachedCompletionResults;
  271. /// A mapping from the formatted type name to a unique number for that
  272. /// type, which is used for type equality comparisons.
  273. llvm::StringMap<unsigned> CachedCompletionTypes;
  274. /// A string hash of the top-level declaration and macro definition
  275. /// names processed the last time that we reparsed the file.
  276. ///
  277. /// This hash value is used to determine when we need to refresh the
  278. /// global code-completion cache.
  279. unsigned CompletionCacheTopLevelHashValue = 0;
  280. /// A string hash of the top-level declaration and macro definition
  281. /// names processed the last time that we reparsed the precompiled preamble.
  282. ///
  283. /// This hash value is used to determine when we need to refresh the
  284. /// global code-completion cache after a rebuild of the precompiled preamble.
  285. unsigned PreambleTopLevelHashValue = 0;
  286. /// The current hash value for the top-level declaration and macro
  287. /// definition names
  288. unsigned CurrentTopLevelHashValue = 0;
  289. /// Bit used by CIndex to mark when a translation unit may be in an
  290. /// inconsistent state, and is not safe to free.
  291. unsigned UnsafeToFree : 1;
  292. /// \brief Enumerator specifying the scope for skipping function bodies.
  293. SkipFunctionBodiesScope SkipFunctionBodies = SkipFunctionBodiesScope::None;
  294. /// Cache any "global" code-completion results, so that we can avoid
  295. /// recomputing them with each completion.
  296. void CacheCodeCompletionResults();
  297. /// Clear out and deallocate
  298. void ClearCachedCompletionResults();
  299. explicit ASTUnit(bool MainFileIsAST);
  300. bool Parse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  301. std::unique_ptr<llvm::MemoryBuffer> OverrideMainBuffer,
  302. IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS);
  303. std::unique_ptr<llvm::MemoryBuffer> getMainBufferWithPrecompiledPreamble(
  304. std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  305. CompilerInvocation &PreambleInvocationIn,
  306. IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS, bool AllowRebuild = true,
  307. unsigned MaxLines = 0);
  308. void RealizeTopLevelDeclsFromPreamble();
  309. /// Transfers ownership of the objects (like SourceManager) from
  310. /// \param CI to this ASTUnit.
  311. void transferASTDataFromCompilerInstance(CompilerInstance &CI);
  312. /// Allows us to assert that ASTUnit is not being used concurrently,
  313. /// which is not supported.
  314. ///
  315. /// Clients should create instances of the ConcurrencyCheck class whenever
  316. /// using the ASTUnit in a way that isn't intended to be concurrent, which is
  317. /// just about any usage.
  318. /// Becomes a noop in release mode; only useful for debug mode checking.
  319. class ConcurrencyState {
  320. void *Mutex; // a llvm::sys::MutexImpl in debug;
  321. public:
  322. ConcurrencyState();
  323. ~ConcurrencyState();
  324. void start();
  325. void finish();
  326. };
  327. ConcurrencyState ConcurrencyCheckValue;
  328. public:
  329. friend class ConcurrencyCheck;
  330. class ConcurrencyCheck {
  331. ASTUnit &Self;
  332. public:
  333. explicit ConcurrencyCheck(ASTUnit &Self) : Self(Self) {
  334. Self.ConcurrencyCheckValue.start();
  335. }
  336. ~ConcurrencyCheck() {
  337. Self.ConcurrencyCheckValue.finish();
  338. }
  339. };
  340. ASTUnit(const ASTUnit &) = delete;
  341. ASTUnit &operator=(const ASTUnit &) = delete;
  342. ~ASTUnit();
  343. bool isMainFileAST() const { return MainFileIsAST; }
  344. bool isUnsafeToFree() const { return UnsafeToFree; }
  345. void setUnsafeToFree(bool Value) { UnsafeToFree = Value; }
  346. const DiagnosticsEngine &getDiagnostics() const { return *Diagnostics; }
  347. DiagnosticsEngine &getDiagnostics() { return *Diagnostics; }
  348. const SourceManager &getSourceManager() const { return *SourceMgr; }
  349. SourceManager &getSourceManager() { return *SourceMgr; }
  350. const Preprocessor &getPreprocessor() const { return *PP; }
  351. Preprocessor &getPreprocessor() { return *PP; }
  352. std::shared_ptr<Preprocessor> getPreprocessorPtr() const { return PP; }
  353. const ASTContext &getASTContext() const { return *Ctx; }
  354. ASTContext &getASTContext() { return *Ctx; }
  355. void setASTContext(ASTContext *ctx) { Ctx = ctx; }
  356. void setPreprocessor(std::shared_ptr<Preprocessor> pp);
  357. /// Enable source-range based diagnostic messages.
  358. ///
  359. /// If diagnostic messages with source-range information are to be expected
  360. /// and AST comes not from file (e.g. after LoadFromCompilerInvocation) this
  361. /// function has to be called.
  362. /// The function is to be called only once and the AST should be associated
  363. /// with the same source file afterwards.
  364. void enableSourceFileDiagnostics();
  365. bool hasSema() const { return (bool)TheSema; }
  366. Sema &getSema() const {
  367. assert(TheSema && "ASTUnit does not have a Sema object!");
  368. return *TheSema;
  369. }
  370. const LangOptions &getLangOpts() const {
  371. assert(LangOpts && "ASTUnit does not have language options");
  372. return *LangOpts;
  373. }
  374. const HeaderSearchOptions &getHeaderSearchOpts() const {
  375. assert(HSOpts && "ASTUnit does not have header search options");
  376. return *HSOpts;
  377. }
  378. const PreprocessorOptions &getPreprocessorOpts() const {
  379. assert(PPOpts && "ASTUnit does not have preprocessor options");
  380. return *PPOpts;
  381. }
  382. const FileManager &getFileManager() const { return *FileMgr; }
  383. FileManager &getFileManager() { return *FileMgr; }
  384. const FileSystemOptions &getFileSystemOpts() const { return FileSystemOpts; }
  385. IntrusiveRefCntPtr<ASTReader> getASTReader() const;
  386. StringRef getOriginalSourceFileName() const {
  387. return OriginalSourceFile;
  388. }
  389. ASTMutationListener *getASTMutationListener();
  390. ASTDeserializationListener *getDeserializationListener();
  391. bool getOnlyLocalDecls() const { return OnlyLocalDecls; }
  392. bool getOwnsRemappedFileBuffers() const { return OwnsRemappedFileBuffers; }
  393. void setOwnsRemappedFileBuffers(bool val) { OwnsRemappedFileBuffers = val; }
  394. StringRef getMainFileName() const;
  395. /// If this ASTUnit came from an AST file, returns the filename for it.
  396. StringRef getASTFileName() const;
  397. using top_level_iterator = std::vector<Decl *>::iterator;
  398. top_level_iterator top_level_begin() {
  399. assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
  400. if (!TopLevelDeclsInPreamble.empty())
  401. RealizeTopLevelDeclsFromPreamble();
  402. return TopLevelDecls.begin();
  403. }
  404. top_level_iterator top_level_end() {
  405. assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
  406. if (!TopLevelDeclsInPreamble.empty())
  407. RealizeTopLevelDeclsFromPreamble();
  408. return TopLevelDecls.end();
  409. }
  410. std::size_t top_level_size() const {
  411. assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
  412. return TopLevelDeclsInPreamble.size() + TopLevelDecls.size();
  413. }
  414. bool top_level_empty() const {
  415. assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
  416. return TopLevelDeclsInPreamble.empty() && TopLevelDecls.empty();
  417. }
  418. /// Add a new top-level declaration.
  419. void addTopLevelDecl(Decl *D) {
  420. TopLevelDecls.push_back(D);
  421. }
  422. /// Add a new local file-level declaration.
  423. void addFileLevelDecl(Decl *D);
  424. /// Get the decls that are contained in a file in the Offset/Length
  425. /// range. \p Length can be 0 to indicate a point at \p Offset instead of
  426. /// a range.
  427. void findFileRegionDecls(FileID File, unsigned Offset, unsigned Length,
  428. SmallVectorImpl<Decl *> &Decls);
  429. /// Retrieve a reference to the current top-level name hash value.
  430. ///
  431. /// Note: This is used internally by the top-level tracking action
  432. unsigned &getCurrentTopLevelHashValue() { return CurrentTopLevelHashValue; }
  433. /// Get the source location for the given file:line:col triplet.
  434. ///
  435. /// The difference with SourceManager::getLocation is that this method checks
  436. /// whether the requested location points inside the precompiled preamble
  437. /// in which case the returned source location will be a "loaded" one.
  438. SourceLocation getLocation(const FileEntry *File,
  439. unsigned Line, unsigned Col) const;
  440. /// Get the source location for the given file:offset pair.
  441. SourceLocation getLocation(const FileEntry *File, unsigned Offset) const;
  442. /// If \p Loc is a loaded location from the preamble, returns
  443. /// the corresponding local location of the main file, otherwise it returns
  444. /// \p Loc.
  445. SourceLocation mapLocationFromPreamble(SourceLocation Loc) const;
  446. /// If \p Loc is a local location of the main file but inside the
  447. /// preamble chunk, returns the corresponding loaded location from the
  448. /// preamble, otherwise it returns \p Loc.
  449. SourceLocation mapLocationToPreamble(SourceLocation Loc) const;
  450. bool isInPreambleFileID(SourceLocation Loc) const;
  451. bool isInMainFileID(SourceLocation Loc) const;
  452. SourceLocation getStartOfMainFileID() const;
  453. SourceLocation getEndOfPreambleFileID() const;
  454. /// \see mapLocationFromPreamble.
  455. SourceRange mapRangeFromPreamble(SourceRange R) const {
  456. return SourceRange(mapLocationFromPreamble(R.getBegin()),
  457. mapLocationFromPreamble(R.getEnd()));
  458. }
  459. /// \see mapLocationToPreamble.
  460. SourceRange mapRangeToPreamble(SourceRange R) const {
  461. return SourceRange(mapLocationToPreamble(R.getBegin()),
  462. mapLocationToPreamble(R.getEnd()));
  463. }
  464. unsigned getPreambleCounterForTests() const { return PreambleCounter; }
  465. // Retrieve the diagnostics associated with this AST
  466. using stored_diag_iterator = StoredDiagnostic *;
  467. using stored_diag_const_iterator = const StoredDiagnostic *;
  468. stored_diag_const_iterator stored_diag_begin() const {
  469. return StoredDiagnostics.begin();
  470. }
  471. stored_diag_iterator stored_diag_begin() {
  472. return StoredDiagnostics.begin();
  473. }
  474. stored_diag_const_iterator stored_diag_end() const {
  475. return StoredDiagnostics.end();
  476. }
  477. stored_diag_iterator stored_diag_end() {
  478. return StoredDiagnostics.end();
  479. }
  480. unsigned stored_diag_size() const { return StoredDiagnostics.size(); }
  481. stored_diag_iterator stored_diag_afterDriver_begin() {
  482. if (NumStoredDiagnosticsFromDriver > StoredDiagnostics.size())
  483. NumStoredDiagnosticsFromDriver = 0;
  484. return StoredDiagnostics.begin() + NumStoredDiagnosticsFromDriver;
  485. }
  486. using cached_completion_iterator =
  487. std::vector<CachedCodeCompletionResult>::iterator;
  488. cached_completion_iterator cached_completion_begin() {
  489. return CachedCompletionResults.begin();
  490. }
  491. cached_completion_iterator cached_completion_end() {
  492. return CachedCompletionResults.end();
  493. }
  494. unsigned cached_completion_size() const {
  495. return CachedCompletionResults.size();
  496. }
  497. /// Returns an iterator range for the local preprocessing entities
  498. /// of the local Preprocessor, if this is a parsed source file, or the loaded
  499. /// preprocessing entities of the primary module if this is an AST file.
  500. llvm::iterator_range<PreprocessingRecord::iterator>
  501. getLocalPreprocessingEntities() const;
  502. /// Type for a function iterating over a number of declarations.
  503. /// \returns true to continue iteration and false to abort.
  504. using DeclVisitorFn = bool (*)(void *context, const Decl *D);
  505. /// Iterate over local declarations (locally parsed if this is a parsed
  506. /// source file or the loaded declarations of the primary module if this is an
  507. /// AST file).
  508. /// \returns true if the iteration was complete or false if it was aborted.
  509. bool visitLocalTopLevelDecls(void *context, DeclVisitorFn Fn);
  510. /// Get the PCH file if one was included.
  511. const FileEntry *getPCHFile();
  512. /// Returns true if the ASTUnit was constructed from a serialized
  513. /// module file.
  514. bool isModuleFile() const;
  515. std::unique_ptr<llvm::MemoryBuffer>
  516. getBufferForFile(StringRef Filename, std::string *ErrorStr = nullptr);
  517. /// Determine what kind of translation unit this AST represents.
  518. TranslationUnitKind getTranslationUnitKind() const { return TUKind; }
  519. /// Determine the input kind this AST unit represents.
  520. InputKind getInputKind() const;
  521. /// A mapping from a file name to the memory buffer that stores the
  522. /// remapped contents of that file.
  523. using RemappedFile = std::pair<std::string, llvm::MemoryBuffer *>;
  524. /// Create a ASTUnit. Gets ownership of the passed CompilerInvocation.
  525. static std::unique_ptr<ASTUnit>
  526. create(std::shared_ptr<CompilerInvocation> CI,
  527. IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
  528. CaptureDiagsKind CaptureDiagnostics, bool UserFilesAreVolatile);
  529. enum WhatToLoad {
  530. /// Load options and the preprocessor state.
  531. LoadPreprocessorOnly,
  532. /// Load the AST, but do not restore Sema state.
  533. LoadASTOnly,
  534. /// Load everything, including Sema.
  535. LoadEverything
  536. };
  537. /// Create a ASTUnit from an AST file.
  538. ///
  539. /// \param Filename - The AST file to load.
  540. ///
  541. /// \param PCHContainerRdr - The PCHContainerOperations to use for loading and
  542. /// creating modules.
  543. /// \param Diags - The diagnostics engine to use for reporting errors; its
  544. /// lifetime is expected to extend past that of the returned ASTUnit.
  545. ///
  546. /// \returns - The initialized ASTUnit or null if the AST failed to load.
  547. static std::unique_ptr<ASTUnit> LoadFromASTFile(
  548. const std::string &Filename, const PCHContainerReader &PCHContainerRdr,
  549. WhatToLoad ToLoad, IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
  550. const FileSystemOptions &FileSystemOpts, bool UseDebugInfo = false,
  551. bool OnlyLocalDecls = false, ArrayRef<RemappedFile> RemappedFiles = None,
  552. CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
  553. bool AllowPCHWithCompilerErrors = false,
  554. bool UserFilesAreVolatile = false);
  555. private:
  556. /// Helper function for \c LoadFromCompilerInvocation() and
  557. /// \c LoadFromCommandLine(), which loads an AST from a compiler invocation.
  558. ///
  559. /// \param PrecompilePreambleAfterNParses After how many parses the preamble
  560. /// of this translation unit should be precompiled, to improve the performance
  561. /// of reparsing. Set to zero to disable preambles.
  562. ///
  563. /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
  564. /// Note that preamble is saved to a temporary directory on a RealFileSystem,
  565. /// so in order for it to be loaded correctly, VFS should have access to
  566. /// it(i.e., be an overlay over RealFileSystem).
  567. ///
  568. /// \returns \c true if a catastrophic failure occurred (which means that the
  569. /// \c ASTUnit itself is invalid), or \c false otherwise.
  570. bool LoadFromCompilerInvocation(
  571. std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  572. unsigned PrecompilePreambleAfterNParses,
  573. IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS);
  574. public:
  575. /// Create an ASTUnit from a source file, via a CompilerInvocation
  576. /// object, by invoking the optionally provided ASTFrontendAction.
  577. ///
  578. /// \param CI - The compiler invocation to use; it must have exactly one input
  579. /// source file. The ASTUnit takes ownership of the CompilerInvocation object.
  580. ///
  581. /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
  582. /// creating modules.
  583. ///
  584. /// \param Diags - The diagnostics engine to use for reporting errors; its
  585. /// lifetime is expected to extend past that of the returned ASTUnit.
  586. ///
  587. /// \param Action - The ASTFrontendAction to invoke. Its ownership is not
  588. /// transferred.
  589. ///
  590. /// \param Unit - optionally an already created ASTUnit. Its ownership is not
  591. /// transferred.
  592. ///
  593. /// \param Persistent - if true the returned ASTUnit will be complete.
  594. /// false means the caller is only interested in getting info through the
  595. /// provided \see Action.
  596. ///
  597. /// \param ErrAST - If non-null and parsing failed without any AST to return
  598. /// (e.g. because the PCH could not be loaded), this accepts the ASTUnit
  599. /// mainly to allow the caller to see the diagnostics.
  600. /// This will only receive an ASTUnit if a new one was created. If an already
  601. /// created ASTUnit was passed in \p Unit then the caller can check that.
  602. ///
  603. static ASTUnit *LoadFromCompilerInvocationAction(
  604. std::shared_ptr<CompilerInvocation> CI,
  605. std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  606. IntrusiveRefCntPtr<DiagnosticsEngine> Diags,
  607. FrontendAction *Action = nullptr, ASTUnit *Unit = nullptr,
  608. bool Persistent = true, StringRef ResourceFilesPath = StringRef(),
  609. bool OnlyLocalDecls = false,
  610. CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
  611. unsigned PrecompilePreambleAfterNParses = 0,
  612. bool CacheCodeCompletionResults = false,
  613. bool IncludeBriefCommentsInCodeCompletion = false,
  614. bool UserFilesAreVolatile = false,
  615. std::unique_ptr<ASTUnit> *ErrAST = nullptr);
  616. /// LoadFromCompilerInvocation - Create an ASTUnit from a source file, via a
  617. /// CompilerInvocation object.
  618. ///
  619. /// \param CI - The compiler invocation to use; it must have exactly one input
  620. /// source file. The ASTUnit takes ownership of the CompilerInvocation object.
  621. ///
  622. /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
  623. /// creating modules.
  624. ///
  625. /// \param Diags - The diagnostics engine to use for reporting errors; its
  626. /// lifetime is expected to extend past that of the returned ASTUnit.
  627. //
  628. // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
  629. // shouldn't need to specify them at construction time.
  630. static std::unique_ptr<ASTUnit> LoadFromCompilerInvocation(
  631. std::shared_ptr<CompilerInvocation> CI,
  632. std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  633. IntrusiveRefCntPtr<DiagnosticsEngine> Diags, FileManager *FileMgr,
  634. bool OnlyLocalDecls = false,
  635. CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
  636. unsigned PrecompilePreambleAfterNParses = 0,
  637. TranslationUnitKind TUKind = TU_Complete,
  638. bool CacheCodeCompletionResults = false,
  639. bool IncludeBriefCommentsInCodeCompletion = false,
  640. bool UserFilesAreVolatile = false);
  641. /// LoadFromCommandLine - Create an ASTUnit from a vector of command line
  642. /// arguments, which must specify exactly one source file.
  643. ///
  644. /// \param ArgBegin - The beginning of the argument vector.
  645. ///
  646. /// \param ArgEnd - The end of the argument vector.
  647. ///
  648. /// \param PCHContainerOps - The PCHContainerOperations to use for loading and
  649. /// creating modules.
  650. ///
  651. /// \param Diags - The diagnostics engine to use for reporting errors; its
  652. /// lifetime is expected to extend past that of the returned ASTUnit.
  653. ///
  654. /// \param ResourceFilesPath - The path to the compiler resource files.
  655. ///
  656. /// \param ModuleFormat - If provided, uses the specific module format.
  657. ///
  658. /// \param ErrAST - If non-null and parsing failed without any AST to return
  659. /// (e.g. because the PCH could not be loaded), this accepts the ASTUnit
  660. /// mainly to allow the caller to see the diagnostics.
  661. ///
  662. /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
  663. /// Note that preamble is saved to a temporary directory on a RealFileSystem,
  664. /// so in order for it to be loaded correctly, VFS should have access to
  665. /// it(i.e., be an overlay over RealFileSystem). RealFileSystem will be used
  666. /// if \p VFS is nullptr.
  667. ///
  668. // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
  669. // shouldn't need to specify them at construction time.
  670. static ASTUnit *LoadFromCommandLine(
  671. const char **ArgBegin, const char **ArgEnd,
  672. std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  673. IntrusiveRefCntPtr<DiagnosticsEngine> Diags, StringRef ResourceFilesPath,
  674. bool OnlyLocalDecls = false,
  675. CaptureDiagsKind CaptureDiagnostics = CaptureDiagsKind::None,
  676. ArrayRef<RemappedFile> RemappedFiles = None,
  677. bool RemappedFilesKeepOriginalName = true,
  678. unsigned PrecompilePreambleAfterNParses = 0,
  679. TranslationUnitKind TUKind = TU_Complete,
  680. bool CacheCodeCompletionResults = false,
  681. bool IncludeBriefCommentsInCodeCompletion = false,
  682. bool AllowPCHWithCompilerErrors = false,
  683. SkipFunctionBodiesScope SkipFunctionBodies =
  684. SkipFunctionBodiesScope::None,
  685. bool SingleFileParse = false, bool UserFilesAreVolatile = false,
  686. bool ForSerialization = false,
  687. llvm::Optional<StringRef> ModuleFormat = llvm::None,
  688. std::unique_ptr<ASTUnit> *ErrAST = nullptr,
  689. IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr);
  690. /// Reparse the source files using the same command-line options that
  691. /// were originally used to produce this translation unit.
  692. ///
  693. /// \param VFS - A llvm::vfs::FileSystem to be used for all file accesses.
  694. /// Note that preamble is saved to a temporary directory on a RealFileSystem,
  695. /// so in order for it to be loaded correctly, VFS should give an access to
  696. /// this(i.e. be an overlay over RealFileSystem).
  697. /// FileMgr->getVirtualFileSystem() will be used if \p VFS is nullptr.
  698. ///
  699. /// \returns True if a failure occurred that causes the ASTUnit not to
  700. /// contain any translation-unit information, false otherwise.
  701. bool Reparse(std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  702. ArrayRef<RemappedFile> RemappedFiles = None,
  703. IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr);
  704. /// Free data that will be re-generated on the next parse.
  705. ///
  706. /// Preamble-related data is not affected.
  707. void ResetForParse();
  708. /// Perform code completion at the given file, line, and
  709. /// column within this translation unit.
  710. ///
  711. /// \param File The file in which code completion will occur.
  712. ///
  713. /// \param Line The line at which code completion will occur.
  714. ///
  715. /// \param Column The column at which code completion will occur.
  716. ///
  717. /// \param IncludeMacros Whether to include macros in the code-completion
  718. /// results.
  719. ///
  720. /// \param IncludeCodePatterns Whether to include code patterns (such as a
  721. /// for loop) in the code-completion results.
  722. ///
  723. /// \param IncludeBriefComments Whether to include brief documentation within
  724. /// the set of code completions returned.
  725. ///
  726. /// FIXME: The Diag, LangOpts, SourceMgr, FileMgr, StoredDiagnostics, and
  727. /// OwnedBuffers parameters are all disgusting hacks. They will go away.
  728. void CodeComplete(StringRef File, unsigned Line, unsigned Column,
  729. ArrayRef<RemappedFile> RemappedFiles, bool IncludeMacros,
  730. bool IncludeCodePatterns, bool IncludeBriefComments,
  731. CodeCompleteConsumer &Consumer,
  732. std::shared_ptr<PCHContainerOperations> PCHContainerOps,
  733. DiagnosticsEngine &Diag, LangOptions &LangOpts,
  734. SourceManager &SourceMgr, FileManager &FileMgr,
  735. SmallVectorImpl<StoredDiagnostic> &StoredDiagnostics,
  736. SmallVectorImpl<const llvm::MemoryBuffer *> &OwnedBuffers);
  737. /// Save this translation unit to a file with the given name.
  738. ///
  739. /// \returns true if there was a file error or false if the save was
  740. /// successful.
  741. bool Save(StringRef File);
  742. /// Serialize this translation unit with the given output stream.
  743. ///
  744. /// \returns True if an error occurred, false otherwise.
  745. bool serialize(raw_ostream &OS);
  746. };
  747. } // namespace clang
  748. #endif // LLVM_CLANG_FRONTEND_ASTUNIT_H