ASTUnit.h revision 87c08a5d6b9e1e44ae6f554df40139d3a6f60b33 
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/Index/ASTLocation.h"
18#include "clang/Frontend/PCHBitCodes.h"
19#include "clang/Sema/Sema.h"
20#include "clang/Lex/PreprocessingRecord.h"
21#include "clang/Basic/SourceManager.h"
22#include "clang/Basic/FileManager.h"
23#include "clang-c/Index.h"
24#include "llvm/ADT/IntrusiveRefCntPtr.h"
25#include "llvm/ADT/OwningPtr.h"
26#include "llvm/ADT/SmallVector.h"
27#include "llvm/ADT/StringMap.h"
28#include "llvm/System/Path.h"
29#include "llvm/Support/Timer.h"
30#include <map>
31#include <string>
32#include <vector>
33#include <cassert>
34#include <utility>
35#include <sys/types.h>
36
37namespace llvm {
38  class MemoryBuffer;
39}
40
41namespace clang {
42class ASTContext;
43class CodeCompleteConsumer;
44class CompilerInvocation;
45class Decl;
46class Diagnostic;
47class FileEntry;
48class FileManager;
49class HeaderSearch;
50class Preprocessor;
51class SourceManager;
52class TargetInfo;
53
54using namespace idx;
55
56/// \brief Utility class for loading a ASTContext from a PCH file.
57///
58class ASTUnit {
59public:
60  typedef std::map<FileID, std::vector<PreprocessedEntity *> >
61    PreprocessedEntitiesByFileMap;
62private:
63  llvm::IntrusiveRefCntPtr<Diagnostic> Diagnostics;
64  llvm::OwningPtr<FileManager>      FileMgr;
65  llvm::OwningPtr<SourceManager>    SourceMgr;
66  llvm::OwningPtr<HeaderSearch>     HeaderInfo;
67  llvm::OwningPtr<TargetInfo>       Target;
68  llvm::OwningPtr<Preprocessor>     PP;
69  llvm::OwningPtr<ASTContext>       Ctx;
70
71  /// \brief The AST consumer that received information about the translation
72  /// unit as it was parsed or loaded.
73  llvm::OwningPtr<ASTConsumer> Consumer;
74
75  /// \brief The semantic analysis object used to type-check the translation
76  /// unit.
77  llvm::OwningPtr<Sema> TheSema;
78
79  /// Optional owned invocation, just used to make the invocation used in
80  /// LoadFromCommandLine available.
81  llvm::OwningPtr<CompilerInvocation> Invocation;
82
83  // OnlyLocalDecls - when true, walking this AST should only visit declarations
84  // that come from the AST itself, not from included precompiled headers.
85  // FIXME: This is temporary; eventually, CIndex will always do this.
86  bool                              OnlyLocalDecls;
87
88  /// \brief Whether to capture any diagnostics produced.
89  bool CaptureDiagnostics;
90
91  /// \brief Track whether the main file was loaded from an AST or not.
92  bool MainFileIsAST;
93
94  /// \brief Whether this AST represents a complete translation unit.
95  bool CompleteTranslationUnit;
96
97  /// Track the top-level decls which appeared in an ASTUnit which was loaded
98  /// from a source file.
99  //
100  // FIXME: This is just an optimization hack to avoid deserializing large parts
101  // of a PCH file when using the Index library on an ASTUnit loaded from
102  // source. In the long term we should make the Index library use efficient and
103  // more scalable search mechanisms.
104  std::vector<Decl*> TopLevelDecls;
105
106  /// The name of the original source file used to generate this ASTUnit.
107  std::string OriginalSourceFile;
108
109  // Critical optimization when using clang_getCursor().
110  ASTLocation LastLoc;
111
112  /// \brief The set of diagnostics produced when creating this
113  /// translation unit.
114  llvm::SmallVector<StoredDiagnostic, 4> StoredDiagnostics;
115
116  /// \brief Temporary files that should be removed when the ASTUnit is
117  /// destroyed.
118  llvm::SmallVector<llvm::sys::Path, 4> TemporaryFiles;
119
120  /// \brief A mapping from file IDs to the set of preprocessed entities
121  /// stored in that file.
122  ///
123  /// FIXME: This is just an optimization hack to avoid searching through
124  /// many preprocessed entities during cursor traversal in the CIndex library.
125  /// Ideally, we would just be able to perform a binary search within the
126  /// list of preprocessed entities.
127  PreprocessedEntitiesByFileMap PreprocessedEntitiesByFile;
128
129  /// \brief Simple hack to allow us to assert that ASTUnit is not being
130  /// used concurrently, which is not supported.
131  ///
132  /// Clients should create instances of the ConcurrencyCheck class whenever
133  /// using the ASTUnit in a way that isn't intended to be concurrent, which is
134  /// just about any usage.
135  unsigned int ConcurrencyCheckValue;
136  static const unsigned int CheckLocked = 28573289;
137  static const unsigned int CheckUnlocked = 9803453;
138
139  /// \brief Counter that determines when we want to try building a
140  /// precompiled preamble.
141  ///
142  /// If zero, we will never build a precompiled preamble. Otherwise,
143  /// it's treated as a counter that decrements each time we reparse
144  /// without the benefit of a precompiled preamble. When it hits 1,
145  /// we'll attempt to rebuild the precompiled header. This way, if
146  /// building the precompiled preamble fails, we won't try again for
147  /// some number of calls.
148  unsigned PreambleRebuildCounter;
149
150  /// \brief The file in which the precompiled preamble is stored.
151  std::string PreambleFile;
152
153  /// \brief The contents of the preamble that has been precompiled to
154  /// \c PreambleFile.
155  std::vector<char> Preamble;
156
157  /// \brief Whether the preamble ends at the start of a new line.
158  ///
159  /// Used to inform the lexer as to whether it's starting at the beginning of
160  /// a line after skipping the preamble.
161  bool PreambleEndsAtStartOfLine;
162
163  /// \brief The size of the source buffer that we've reserved for the main
164  /// file within the precompiled preamble.
165  unsigned PreambleReservedSize;
166
167  /// \brief Keeps track of the files that were used when computing the
168  /// preamble, with both their buffer size and their modification time.
169  ///
170  /// If any of the files have changed from one compile to the next,
171  /// the preamble must be thrown away.
172  llvm::StringMap<std::pair<off_t, time_t> > FilesInPreamble;
173
174  /// \brief When non-NULL, this is the buffer used to store the contents of
175  /// the main file when it has been padded for use with the precompiled
176  /// preamble.
177  llvm::MemoryBuffer *SavedMainFileBuffer;
178
179  /// \brief The number of warnings that occurred while parsing the preamble.
180  ///
181  /// This value will be used to restore the state of the \c Diagnostic object
182  /// when re-using the precompiled preamble. Note that only the
183  /// number of warnings matters, since we will not save the preamble
184  /// when any errors are present.
185  unsigned NumWarningsInPreamble;
186
187  /// \brief The number of diagnostics that were stored when parsing
188  /// the precompiled preamble.
189  ///
190  /// This value is used to determine how many of the stored
191  /// diagnostics should be retained when reparsing in the presence of
192  /// a precompiled preamble.
193  unsigned NumStoredDiagnosticsInPreamble;
194
195  /// \brief The group of timers associated with this translation unit.
196  llvm::OwningPtr<llvm::TimerGroup> TimerGroup;
197
198  /// \brief A list of the PCH ID numbers for each of the top-level
199  /// declarations parsed within the precompiled preamble.
200  std::vector<pch::DeclID> TopLevelDeclsInPreamble;
201
202  ///
203  /// \defgroup CodeCompleteCaching Code-completion caching
204  ///
205  /// \{
206  ///
207
208  /// \brief Whether we should be caching code-completion results.
209  bool ShouldCacheCodeCompletionResults;
210
211public:
212  /// \brief A cached code-completion result, which may be introduced in one of
213  /// many different contexts.
214  struct CachedCodeCompletionResult {
215    /// \brief The code-completion string corresponding to this completion
216    /// result.
217    CodeCompletionString *Completion;
218
219    /// \brief A bitmask that indicates which code-completion contexts should
220    /// contain this completion result.
221    ///
222    /// The bits in the bitmask correspond to the values of
223    /// CodeCompleteContext::Kind. To map from a completion context kind to a
224    /// bit, subtract one from the completion context kind and shift 1 by that
225    /// number of bits. Many completions can occur in several different
226    /// contexts.
227    unsigned ShowInContexts;
228
229    /// \brief The priority given to this code-completion result.
230    unsigned Priority;
231
232    /// \brief The libclang cursor kind corresponding to this code-completion
233    /// result.
234    CXCursorKind Kind;
235  };
236
237private:
238  /// \brief The set of cached code-completion results.
239  std::vector<CachedCodeCompletionResult> CachedCompletionResults;
240
241  /// \brief Cache any "global" code-completion results, so that we
242  void CacheCodeCompletionResults();
243
244  /// \brief Clear out and deallocate
245  void ClearCachedCompletionResults();
246
247  ///
248  /// \}
249  ///
250
251  /// \brief The timers we've created from the various parses, reparses, etc.
252  /// involved in this translation unit.
253  std::vector<llvm::Timer *> Timers;
254
255  ASTUnit(const ASTUnit&); // DO NOT IMPLEMENT
256  ASTUnit &operator=(const ASTUnit &); // DO NOT IMPLEMENT
257
258  explicit ASTUnit(bool MainFileIsAST);
259
260  void CleanTemporaryFiles();
261  bool Parse(llvm::MemoryBuffer *OverrideMainBuffer);
262
263  std::pair<llvm::MemoryBuffer *, std::pair<unsigned, bool> >
264  ComputePreamble(CompilerInvocation &Invocation,
265                  unsigned MaxLines, bool &CreatedBuffer);
266
267  llvm::MemoryBuffer *getMainBufferWithPrecompiledPreamble(
268                                                     bool AllowRebuild = true,
269                                                        unsigned MaxLines = 0);
270  void RealizeTopLevelDeclsFromPreamble();
271
272public:
273  class ConcurrencyCheck {
274    volatile ASTUnit &Self;
275
276  public:
277    explicit ConcurrencyCheck(ASTUnit &Self)
278      : Self(Self)
279    {
280      assert(Self.ConcurrencyCheckValue == CheckUnlocked &&
281             "Concurrent access to ASTUnit!");
282      Self.ConcurrencyCheckValue = CheckLocked;
283    }
284
285    ~ConcurrencyCheck() {
286      Self.ConcurrencyCheckValue = CheckUnlocked;
287    }
288  };
289  friend class ConcurrencyCheck;
290
291  ~ASTUnit();
292
293  bool isMainFileAST() const { return MainFileIsAST; }
294
295  const Diagnostic &getDiagnostics() const { return *Diagnostics; }
296  Diagnostic &getDiagnostics()             { return *Diagnostics; }
297
298  const SourceManager &getSourceManager() const { return *SourceMgr; }
299        SourceManager &getSourceManager()       { return *SourceMgr; }
300
301  const Preprocessor &getPreprocessor() const { return *PP.get(); }
302        Preprocessor &getPreprocessor()       { return *PP.get(); }
303
304  const ASTContext &getASTContext() const { return *Ctx.get(); }
305        ASTContext &getASTContext()       { return *Ctx.get(); }
306
307  bool hasSema() const { return TheSema; }
308  Sema &getSema() const {
309    assert(TheSema && "ASTUnit does not have a Sema object!");
310    return *TheSema;
311  }
312
313  const FileManager &getFileManager() const { return *FileMgr; }
314        FileManager &getFileManager()       { return *FileMgr; }
315
316  const std::string &getOriginalSourceFileName();
317  const std::string &getPCHFileName();
318
319  /// \brief Add a temporary file that the ASTUnit depends on.
320  ///
321  /// This file will be erased when the ASTUnit is destroyed.
322  void addTemporaryFile(const llvm::sys::Path &TempFile) {
323    TemporaryFiles.push_back(TempFile);
324  }
325
326  bool getOnlyLocalDecls() const { return OnlyLocalDecls; }
327
328  /// \brief Retrieve the maximum PCH level of declarations that a
329  /// traversal of the translation unit should consider.
330  unsigned getMaxPCHLevel() const;
331
332  void setLastASTLocation(ASTLocation ALoc) { LastLoc = ALoc; }
333  ASTLocation getLastASTLocation() const { return LastLoc; }
334
335  typedef std::vector<Decl *>::iterator top_level_iterator;
336
337  top_level_iterator top_level_begin() {
338    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
339    if (!TopLevelDeclsInPreamble.empty())
340      RealizeTopLevelDeclsFromPreamble();
341    return TopLevelDecls.begin();
342  }
343
344  top_level_iterator top_level_end() {
345    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
346    if (!TopLevelDeclsInPreamble.empty())
347      RealizeTopLevelDeclsFromPreamble();
348    return TopLevelDecls.end();
349  }
350
351  std::size_t top_level_size() const {
352    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
353    return TopLevelDeclsInPreamble.size() + TopLevelDecls.size();
354  }
355
356  bool top_level_empty() const {
357    assert(!isMainFileAST() && "Invalid call for AST based ASTUnit!");
358    return TopLevelDeclsInPreamble.empty() && TopLevelDecls.empty();
359  }
360
361  /// \brief Add a new top-level declaration.
362  void addTopLevelDecl(Decl *D) {
363    TopLevelDecls.push_back(D);
364  }
365
366  /// \brief Add a new top-level declaration, identified by its ID in
367  /// the precompiled preamble.
368  void addTopLevelDeclFromPreamble(pch::DeclID D) {
369    TopLevelDeclsInPreamble.push_back(D);
370  }
371
372  /// \brief Retrieve the mapping from File IDs to the preprocessed entities
373  /// within that file.
374  PreprocessedEntitiesByFileMap &getPreprocessedEntitiesByFile() {
375    return PreprocessedEntitiesByFile;
376  }
377
378  // Retrieve the diagnostics associated with this AST
379  typedef const StoredDiagnostic *stored_diag_iterator;
380  stored_diag_iterator stored_diag_begin() const {
381    return StoredDiagnostics.begin();
382  }
383  stored_diag_iterator stored_diag_end() const {
384    return StoredDiagnostics.end();
385  }
386  unsigned stored_diag_size() const { return StoredDiagnostics.size(); }
387
388  llvm::SmallVector<StoredDiagnostic, 4> &getStoredDiagnostics() {
389    return StoredDiagnostics;
390  }
391
392  typedef std::vector<CachedCodeCompletionResult>::iterator
393    cached_completion_iterator;
394
395  cached_completion_iterator cached_completion_begin() {
396    return CachedCompletionResults.begin();
397  }
398
399  cached_completion_iterator cached_completion_end() {
400    return CachedCompletionResults.end();
401  }
402
403  unsigned cached_completion_size() const {
404    return CachedCompletionResults.size();
405  }
406
407  /// \brief Whether this AST represents a complete translation unit.
408  ///
409  /// If false, this AST is only a partial translation unit, e.g., one
410  /// that might still be used as a precompiled header or preamble.
411  bool isCompleteTranslationUnit() const { return CompleteTranslationUnit; }
412
413  /// \brief A mapping from a file name to the memory buffer that stores the
414  /// remapped contents of that file.
415  typedef std::pair<std::string, const llvm::MemoryBuffer *> RemappedFile;
416
417  /// \brief Create a ASTUnit from a PCH file.
418  ///
419  /// \param Filename - The PCH file to load.
420  ///
421  /// \param Diags - The diagnostics engine to use for reporting errors; its
422  /// lifetime is expected to extend past that of the returned ASTUnit.
423  ///
424  /// \returns - The initialized ASTUnit or null if the PCH failed to load.
425  static ASTUnit *LoadFromPCHFile(const std::string &Filename,
426                                  llvm::IntrusiveRefCntPtr<Diagnostic> Diags,
427                                  bool OnlyLocalDecls = false,
428                                  RemappedFile *RemappedFiles = 0,
429                                  unsigned NumRemappedFiles = 0,
430                                  bool CaptureDiagnostics = false);
431
432  /// LoadFromCompilerInvocation - Create an ASTUnit from a source file, via a
433  /// CompilerInvocation object.
434  ///
435  /// \param CI - The compiler invocation to use; it must have exactly one input
436  /// source file. The ASTUnit takes ownership of the CompilerInvocation object.
437  ///
438  /// \param Diags - The diagnostics engine to use for reporting errors; its
439  /// lifetime is expected to extend past that of the returned ASTUnit.
440  //
441  // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
442  // shouldn't need to specify them at construction time.
443  static ASTUnit *LoadFromCompilerInvocation(CompilerInvocation *CI,
444                                     llvm::IntrusiveRefCntPtr<Diagnostic> Diags,
445                                             bool OnlyLocalDecls = false,
446                                             bool CaptureDiagnostics = false,
447                                             bool PrecompilePreamble = false,
448                                          bool CompleteTranslationUnit = true,
449                                       bool CacheCodeCompletionResults = false);
450
451  /// LoadFromCommandLine - Create an ASTUnit from a vector of command line
452  /// arguments, which must specify exactly one source file.
453  ///
454  /// \param ArgBegin - The beginning of the argument vector.
455  ///
456  /// \param ArgEnd - The end of the argument vector.
457  ///
458  /// \param Diags - The diagnostics engine to use for reporting errors; its
459  /// lifetime is expected to extend past that of the returned ASTUnit.
460  ///
461  /// \param ResourceFilesPath - The path to the compiler resource files.
462  //
463  // FIXME: Move OnlyLocalDecls, UseBumpAllocator to setters on the ASTUnit, we
464  // shouldn't need to specify them at construction time.
465  static ASTUnit *LoadFromCommandLine(const char **ArgBegin,
466                                      const char **ArgEnd,
467                                    llvm::IntrusiveRefCntPtr<Diagnostic> Diags,
468                                      llvm::StringRef ResourceFilesPath,
469                                      bool OnlyLocalDecls = false,
470                                      RemappedFile *RemappedFiles = 0,
471                                      unsigned NumRemappedFiles = 0,
472                                      bool CaptureDiagnostics = false,
473                                      bool PrecompilePreamble = false,
474                                      bool CompleteTranslationUnit = true,
475                                      bool CacheCodeCompletionResults = false);
476
477  /// \brief Reparse the source files using the same command-line options that
478  /// were originally used to produce this translation unit.
479  ///
480  /// \returns True if a failure occurred that causes the ASTUnit not to
481  /// contain any translation-unit information, false otherwise.
482  bool Reparse(RemappedFile *RemappedFiles = 0,
483               unsigned NumRemappedFiles = 0);
484
485  /// \brief Perform code completion at the given file, line, and
486  /// column within this translation unit.
487  ///
488  /// \param File The file in which code completion will occur.
489  ///
490  /// \param Line The line at which code completion will occur.
491  ///
492  /// \param Column The column at which code completion will occur.
493  ///
494  /// \param IncludeMacros Whether to include macros in the code-completion
495  /// results.
496  ///
497  /// \param IncludeCodePatterns Whether to include code patterns (such as a
498  /// for loop) in the code-completion results.
499  ///
500  /// FIXME: The Diag, LangOpts, SourceMgr, FileMgr, and
501  /// StoredDiagnostics parameters are all disgusting hacks. They will
502  /// go away.
503  void CodeComplete(llvm::StringRef File, unsigned Line, unsigned Column,
504                    RemappedFile *RemappedFiles, unsigned NumRemappedFiles,
505                    bool IncludeMacros, bool IncludeCodePatterns,
506                    CodeCompleteConsumer &Consumer,
507                    Diagnostic &Diag, LangOptions &LangOpts,
508                    SourceManager &SourceMgr, FileManager &FileMgr,
509                    llvm::SmallVectorImpl<StoredDiagnostic> &StoredDiagnostics);
510
511  /// \brief Save this translation unit to a file with the given name.
512  ///
513  /// \returns True if an error occurred, false otherwise.
514  bool Save(llvm::StringRef File);
515};
516
517} // namespace clang
518
519#endif
520