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