1 //===-- CompilerInstance.h - Clang Compiler Instance ------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_CLANG_FRONTEND_COMPILERINSTANCE_H_
11 #define LLVM_CLANG_FRONTEND_COMPILERINSTANCE_H_
13 #include "clang/AST/ASTConsumer.h"
14 #include "clang/Frontend/PCHContainerOperations.h"
15 #include "clang/Basic/Diagnostic.h"
16 #include "clang/Basic/SourceManager.h"
17 #include "clang/Frontend/CompilerInvocation.h"
18 #include "clang/Frontend/Utils.h"
19 #include "clang/Lex/ModuleLoader.h"
20 #include "llvm/ADT/ArrayRef.h"
21 #include "llvm/ADT/DenseMap.h"
22 #include "llvm/ADT/IntrusiveRefCntPtr.h"
23 #include "llvm/ADT/StringRef.h"
40 class CodeCompleteConsumer;
41 class DiagnosticsEngine;
42 class DiagnosticConsumer;
43 class ExternalASTSource;
53 /// CompilerInstance - Helper class for managing a single instance of the Clang
56 /// The CompilerInstance serves two purposes:
57 /// (1) It manages the various objects which are necessary to run the compiler,
58 /// for example the preprocessor, the target information, and the AST
60 /// (2) It provides utility routines for constructing and manipulating the
61 /// common Clang objects.
63 /// The compiler instance generally owns the instance of all the objects that it
64 /// manages. However, clients can still share objects by manually setting the
65 /// object and retaking ownership prior to destroying the CompilerInstance.
67 /// The compiler instance is intended to simplify clients, but not to lock them
68 /// in to the compiler instance for everything. When possible, utility functions
69 /// come in two forms; a short form that reuses the CompilerInstance objects,
70 /// and a long form that takes explicit instances of any required objects.
71 class CompilerInstance : public ModuleLoader {
72 /// The options used in this compiler instance.
73 IntrusiveRefCntPtr<CompilerInvocation> Invocation;
75 /// The diagnostics engine instance.
76 IntrusiveRefCntPtr<DiagnosticsEngine> Diagnostics;
78 /// The target being compiled for.
79 IntrusiveRefCntPtr<TargetInfo> Target;
81 /// Auxiliary Target info.
82 IntrusiveRefCntPtr<TargetInfo> AuxTarget;
84 /// The virtual file system.
85 IntrusiveRefCntPtr<vfs::FileSystem> VirtualFileSystem;
88 IntrusiveRefCntPtr<FileManager> FileMgr;
90 /// The source manager.
91 IntrusiveRefCntPtr<SourceManager> SourceMgr;
94 IntrusiveRefCntPtr<Preprocessor> PP;
97 IntrusiveRefCntPtr<ASTContext> Context;
100 std::unique_ptr<ASTConsumer> Consumer;
102 /// The code completion consumer.
103 std::unique_ptr<CodeCompleteConsumer> CompletionConsumer;
105 /// \brief The semantic analysis object.
106 std::unique_ptr<Sema> TheSema;
108 /// \brief The frontend timer group.
109 std::unique_ptr<llvm::TimerGroup> FrontendTimerGroup;
111 /// \brief The frontend timer.
112 std::unique_ptr<llvm::Timer> FrontendTimer;
114 /// \brief The ASTReader, if one exists.
115 IntrusiveRefCntPtr<ASTReader> ModuleManager;
117 /// \brief The module dependency collector for crashdumps
118 std::shared_ptr<ModuleDependencyCollector> ModuleDepCollector;
120 /// \brief The module provider.
121 std::shared_ptr<PCHContainerOperations> ThePCHContainerOperations;
123 /// \brief The dependency file generator.
124 std::unique_ptr<DependencyFileGenerator> TheDependencyFileGenerator;
126 std::vector<std::shared_ptr<DependencyCollector>> DependencyCollectors;
128 /// \brief The set of top-level modules that has already been loaded,
129 /// along with the module map
130 llvm::DenseMap<const IdentifierInfo *, Module *> KnownModules;
132 /// \brief The location of the module-import keyword for the last module
134 SourceLocation LastModuleImportLoc;
136 /// \brief The result of the last module import.
138 ModuleLoadResult LastModuleImportResult;
140 /// \brief Whether we should (re)build the global module index once we
141 /// have finished with this translation unit.
142 bool BuildGlobalModuleIndex;
144 /// \brief We have a full global module index, with all modules.
145 bool HaveFullGlobalModuleIndex;
147 /// \brief One or more modules failed to build.
148 bool ModuleBuildFailed;
150 /// \brief Holds information about the output file.
152 /// If TempFilename is not empty we must rename it to Filename at the end.
153 /// TempFilename may be empty and Filename non-empty if creating the temporary
156 std::string Filename;
157 std::string TempFilename;
158 std::unique_ptr<raw_ostream> OS;
160 OutputFile(std::string filename, std::string tempFilename,
161 std::unique_ptr<raw_ostream> OS)
162 : Filename(std::move(filename)), TempFilename(std::move(tempFilename)),
164 OutputFile(OutputFile &&O)
165 : Filename(std::move(O.Filename)),
166 TempFilename(std::move(O.TempFilename)), OS(std::move(O.OS)) {}
169 /// If the output doesn't support seeking (terminal, pipe). we switch
170 /// the stream to a buffer_ostream. These are the buffer and the original
172 std::unique_ptr<llvm::raw_fd_ostream> NonSeekStream;
174 /// The list of active output files.
175 std::list<OutputFile> OutputFiles;
177 CompilerInstance(const CompilerInstance &) = delete;
178 void operator=(const CompilerInstance &) = delete;
180 explicit CompilerInstance(
181 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
182 std::make_shared<PCHContainerOperations>(),
183 bool BuildingModule = false);
184 ~CompilerInstance() override;
186 /// @name High-Level Operations
189 /// ExecuteAction - Execute the provided action against the compiler's
190 /// CompilerInvocation object.
192 /// This function makes the following assumptions:
194 /// - The invocation options should be initialized. This function does not
195 /// handle the '-help' or '-version' options, clients should handle those
198 /// - The diagnostics engine should have already been created by the client.
200 /// - No other CompilerInstance state should have been initialized (this is
201 /// an unchecked error).
203 /// - Clients should have initialized any LLVM target features that may be
206 /// - Clients should eventually call llvm_shutdown() upon the completion of
207 /// this routine to ensure that any managed objects are properly destroyed.
209 /// Note that this routine may write output to 'stderr'.
211 /// \param Act - The action to execute.
212 /// \return - True on success.
214 // FIXME: This function should take the stream to write any debugging /
215 // verbose output to as an argument.
217 // FIXME: Eliminate the llvm_shutdown requirement, that should either be part
218 // of the context or else not CompilerInstance specific.
219 bool ExecuteAction(FrontendAction &Act);
222 /// @name Compiler Invocation and Options
225 bool hasInvocation() const { return Invocation != nullptr; }
227 CompilerInvocation &getInvocation() {
228 assert(Invocation && "Compiler instance has no invocation!");
232 /// setInvocation - Replace the current invocation.
233 void setInvocation(CompilerInvocation *Value);
235 /// \brief Indicates whether we should (re)build the global module index.
236 bool shouldBuildGlobalModuleIndex() const;
238 /// \brief Set the flag indicating whether we should (re)build the global
240 void setBuildGlobalModuleIndex(bool Build) {
241 BuildGlobalModuleIndex = Build;
245 /// @name Forwarding Methods
248 AnalyzerOptionsRef getAnalyzerOpts() {
249 return Invocation->getAnalyzerOpts();
252 CodeGenOptions &getCodeGenOpts() {
253 return Invocation->getCodeGenOpts();
255 const CodeGenOptions &getCodeGenOpts() const {
256 return Invocation->getCodeGenOpts();
259 DependencyOutputOptions &getDependencyOutputOpts() {
260 return Invocation->getDependencyOutputOpts();
262 const DependencyOutputOptions &getDependencyOutputOpts() const {
263 return Invocation->getDependencyOutputOpts();
266 DiagnosticOptions &getDiagnosticOpts() {
267 return Invocation->getDiagnosticOpts();
269 const DiagnosticOptions &getDiagnosticOpts() const {
270 return Invocation->getDiagnosticOpts();
273 FileSystemOptions &getFileSystemOpts() {
274 return Invocation->getFileSystemOpts();
276 const FileSystemOptions &getFileSystemOpts() const {
277 return Invocation->getFileSystemOpts();
280 FrontendOptions &getFrontendOpts() {
281 return Invocation->getFrontendOpts();
283 const FrontendOptions &getFrontendOpts() const {
284 return Invocation->getFrontendOpts();
287 HeaderSearchOptions &getHeaderSearchOpts() {
288 return Invocation->getHeaderSearchOpts();
290 const HeaderSearchOptions &getHeaderSearchOpts() const {
291 return Invocation->getHeaderSearchOpts();
294 LangOptions &getLangOpts() {
295 return *Invocation->getLangOpts();
297 const LangOptions &getLangOpts() const {
298 return *Invocation->getLangOpts();
301 PreprocessorOptions &getPreprocessorOpts() {
302 return Invocation->getPreprocessorOpts();
304 const PreprocessorOptions &getPreprocessorOpts() const {
305 return Invocation->getPreprocessorOpts();
308 PreprocessorOutputOptions &getPreprocessorOutputOpts() {
309 return Invocation->getPreprocessorOutputOpts();
311 const PreprocessorOutputOptions &getPreprocessorOutputOpts() const {
312 return Invocation->getPreprocessorOutputOpts();
315 TargetOptions &getTargetOpts() {
316 return Invocation->getTargetOpts();
318 const TargetOptions &getTargetOpts() const {
319 return Invocation->getTargetOpts();
323 /// @name Diagnostics Engine
326 bool hasDiagnostics() const { return Diagnostics != nullptr; }
328 /// Get the current diagnostics engine.
329 DiagnosticsEngine &getDiagnostics() const {
330 assert(Diagnostics && "Compiler instance has no diagnostics!");
334 /// setDiagnostics - Replace the current diagnostics engine.
335 void setDiagnostics(DiagnosticsEngine *Value);
337 DiagnosticConsumer &getDiagnosticClient() const {
338 assert(Diagnostics && Diagnostics->getClient() &&
339 "Compiler instance has no diagnostic client!");
340 return *Diagnostics->getClient();
344 /// @name Target Info
347 bool hasTarget() const { return Target != nullptr; }
349 TargetInfo &getTarget() const {
350 assert(Target && "Compiler instance has no target!");
354 /// Replace the current Target.
355 void setTarget(TargetInfo *Value);
358 /// @name AuxTarget Info
361 TargetInfo *getAuxTarget() const { return AuxTarget.get(); }
363 /// Replace the current AuxTarget.
364 void setAuxTarget(TargetInfo *Value);
367 /// @name Virtual File System
370 bool hasVirtualFileSystem() const { return VirtualFileSystem != nullptr; }
372 vfs::FileSystem &getVirtualFileSystem() const {
373 assert(hasVirtualFileSystem() &&
374 "Compiler instance has no virtual file system");
375 return *VirtualFileSystem;
378 /// \brief Replace the current virtual file system.
380 /// \note Most clients should use setFileManager, which will implicitly reset
381 /// the virtual file system to the one contained in the file manager.
382 void setVirtualFileSystem(IntrusiveRefCntPtr<vfs::FileSystem> FS) {
383 VirtualFileSystem = FS;
387 /// @name File Manager
390 bool hasFileManager() const { return FileMgr != nullptr; }
392 /// Return the current file manager to the caller.
393 FileManager &getFileManager() const {
394 assert(FileMgr && "Compiler instance has no file manager!");
398 void resetAndLeakFileManager() {
399 BuryPointer(FileMgr.get());
400 FileMgr.resetWithoutRelease();
403 /// \brief Replace the current file manager and virtual file system.
404 void setFileManager(FileManager *Value);
407 /// @name Source Manager
410 bool hasSourceManager() const { return SourceMgr != nullptr; }
412 /// Return the current source manager.
413 SourceManager &getSourceManager() const {
414 assert(SourceMgr && "Compiler instance has no source manager!");
418 void resetAndLeakSourceManager() {
419 BuryPointer(SourceMgr.get());
420 SourceMgr.resetWithoutRelease();
423 /// setSourceManager - Replace the current source manager.
424 void setSourceManager(SourceManager *Value);
427 /// @name Preprocessor
430 bool hasPreprocessor() const { return PP != nullptr; }
432 /// Return the current preprocessor.
433 Preprocessor &getPreprocessor() const {
434 assert(PP && "Compiler instance has no preprocessor!");
438 void resetAndLeakPreprocessor() {
439 BuryPointer(PP.get());
440 PP.resetWithoutRelease();
443 /// Replace the current preprocessor.
444 void setPreprocessor(Preprocessor *Value);
450 bool hasASTContext() const { return Context != nullptr; }
452 ASTContext &getASTContext() const {
453 assert(Context && "Compiler instance has no AST context!");
457 void resetAndLeakASTContext() {
458 BuryPointer(Context.get());
459 Context.resetWithoutRelease();
462 /// setASTContext - Replace the current AST context.
463 void setASTContext(ASTContext *Value);
465 /// \brief Replace the current Sema; the compiler instance takes ownership
467 void setSema(Sema *S);
470 /// @name ASTConsumer
473 bool hasASTConsumer() const { return (bool)Consumer; }
475 ASTConsumer &getASTConsumer() const {
476 assert(Consumer && "Compiler instance has no AST consumer!");
480 /// takeASTConsumer - Remove the current AST consumer and give ownership to
482 std::unique_ptr<ASTConsumer> takeASTConsumer() { return std::move(Consumer); }
484 /// setASTConsumer - Replace the current AST consumer; the compiler instance
485 /// takes ownership of \p Value.
486 void setASTConsumer(std::unique_ptr<ASTConsumer> Value);
489 /// @name Semantic analysis
491 bool hasSema() const { return (bool)TheSema; }
493 Sema &getSema() const {
494 assert(TheSema && "Compiler instance has no Sema object!");
498 std::unique_ptr<Sema> takeSema();
499 void resetAndLeakSema();
502 /// @name Module Management
505 IntrusiveRefCntPtr<ASTReader> getModuleManager() const;
506 void setModuleManager(IntrusiveRefCntPtr<ASTReader> Reader);
508 std::shared_ptr<ModuleDependencyCollector> getModuleDepCollector() const;
509 void setModuleDepCollector(
510 std::shared_ptr<ModuleDependencyCollector> Collector);
512 std::shared_ptr<PCHContainerOperations> getPCHContainerOperations() const {
513 return ThePCHContainerOperations;
516 /// Return the appropriate PCHContainerWriter depending on the
517 /// current CodeGenOptions.
518 const PCHContainerWriter &getPCHContainerWriter() const {
519 assert(Invocation && "cannot determine module format without invocation");
520 StringRef Format = getHeaderSearchOpts().ModuleFormat;
521 auto *Writer = ThePCHContainerOperations->getWriterOrNull(Format);
524 Diagnostics->Report(diag::err_module_format_unhandled) << Format;
525 llvm::report_fatal_error("unknown module format");
530 /// Return the appropriate PCHContainerReader depending on the
531 /// current CodeGenOptions.
532 const PCHContainerReader &getPCHContainerReader() const {
533 assert(Invocation && "cannot determine module format without invocation");
534 StringRef Format = getHeaderSearchOpts().ModuleFormat;
535 auto *Reader = ThePCHContainerOperations->getReaderOrNull(Format);
538 Diagnostics->Report(diag::err_module_format_unhandled) << Format;
539 llvm::report_fatal_error("unknown module format");
545 /// @name Code Completion
548 bool hasCodeCompletionConsumer() const { return (bool)CompletionConsumer; }
550 CodeCompleteConsumer &getCodeCompletionConsumer() const {
551 assert(CompletionConsumer &&
552 "Compiler instance has no code completion consumer!");
553 return *CompletionConsumer;
556 /// setCodeCompletionConsumer - Replace the current code completion consumer;
557 /// the compiler instance takes ownership of \p Value.
558 void setCodeCompletionConsumer(CodeCompleteConsumer *Value);
561 /// @name Frontend timer
564 bool hasFrontendTimer() const { return (bool)FrontendTimer; }
566 llvm::Timer &getFrontendTimer() const {
567 assert(FrontendTimer && "Compiler instance has no frontend timer!");
568 return *FrontendTimer;
572 /// @name Output Files
575 /// addOutputFile - Add an output file onto the list of tracked output files.
577 /// \param OutFile - The output file info.
578 void addOutputFile(OutputFile &&OutFile);
580 /// clearOutputFiles - Clear the output file list, destroying the contained
583 /// \param EraseFiles - If true, attempt to erase the files from disk.
584 void clearOutputFiles(bool EraseFiles);
587 /// @name Construction Utility Methods
590 /// Create the diagnostics engine using the invocation's diagnostic options
591 /// and replace any existing one with it.
593 /// Note that this routine also replaces the diagnostic client,
594 /// allocating one if one is not provided.
596 /// \param Client If non-NULL, a diagnostic client that will be
597 /// attached to (and, then, owned by) the DiagnosticsEngine inside this AST
600 /// \param ShouldOwnClient If Client is non-NULL, specifies whether
601 /// the diagnostic object should take ownership of the client.
602 void createDiagnostics(DiagnosticConsumer *Client = nullptr,
603 bool ShouldOwnClient = true);
605 /// Create a DiagnosticsEngine object with a the TextDiagnosticPrinter.
607 /// If no diagnostic client is provided, this creates a
608 /// DiagnosticConsumer that is owned by the returned diagnostic
609 /// object, if using directly the caller is responsible for
610 /// releasing the returned DiagnosticsEngine's client eventually.
612 /// \param Opts - The diagnostic options; note that the created text
613 /// diagnostic object contains a reference to these options.
615 /// \param Client If non-NULL, a diagnostic client that will be
616 /// attached to (and, then, owned by) the returned DiagnosticsEngine
619 /// \param CodeGenOpts If non-NULL, the code gen options in use, which may be
620 /// used by some diagnostics printers (for logging purposes only).
622 /// \return The new object on success, or null on failure.
623 static IntrusiveRefCntPtr<DiagnosticsEngine>
624 createDiagnostics(DiagnosticOptions *Opts,
625 DiagnosticConsumer *Client = nullptr,
626 bool ShouldOwnClient = true,
627 const CodeGenOptions *CodeGenOpts = nullptr);
629 /// Create the file manager and replace any existing one with it.
630 void createFileManager();
632 /// Create the source manager and replace any existing one with it.
633 void createSourceManager(FileManager &FileMgr);
635 /// Create the preprocessor, using the invocation, file, and source managers,
636 /// and replace any existing one with it.
637 void createPreprocessor(TranslationUnitKind TUKind);
639 std::string getSpecificModuleCachePath();
641 /// Create the AST context.
642 void createASTContext();
644 /// Create an external AST source to read a PCH file and attach it to the AST
646 void createPCHExternalASTSource(StringRef Path, bool DisablePCHValidation,
647 bool AllowPCHWithCompilerErrors,
648 void *DeserializationListener,
649 bool OwnDeserializationListener);
651 /// Create an external AST source to read a PCH file.
653 /// \return - The new object on success, or null on failure.
654 static IntrusiveRefCntPtr<ASTReader> createPCHExternalASTSource(
655 StringRef Path, StringRef Sysroot, bool DisablePCHValidation,
656 bool AllowPCHWithCompilerErrors, Preprocessor &PP, ASTContext &Context,
657 const PCHContainerReader &PCHContainerRdr,
658 ArrayRef<IntrusiveRefCntPtr<ModuleFileExtension>> Extensions,
659 void *DeserializationListener, bool OwnDeserializationListener,
660 bool Preamble, bool UseGlobalModuleIndex);
662 /// Create a code completion consumer using the invocation; note that this
663 /// will cause the source manager to truncate the input source file at the
664 /// completion point.
665 void createCodeCompletionConsumer();
667 /// Create a code completion consumer to print code completion results, at
668 /// \p Filename, \p Line, and \p Column, to the given output stream \p OS.
669 static CodeCompleteConsumer *createCodeCompletionConsumer(
670 Preprocessor &PP, StringRef Filename, unsigned Line, unsigned Column,
671 const CodeCompleteOptions &Opts, raw_ostream &OS);
673 /// \brief Create the Sema object to be used for parsing.
674 void createSema(TranslationUnitKind TUKind,
675 CodeCompleteConsumer *CompletionConsumer);
677 /// Create the frontend timer and replace any existing one with it.
678 void createFrontendTimer();
680 /// Create the default output file (from the invocation's options) and add it
681 /// to the list of tracked output files.
683 /// The files created by this function always use temporary files to write to
684 /// their result (that is, the data is written to a temporary file which will
685 /// atomically replace the target output on success).
687 /// \return - Null on error.
688 raw_pwrite_stream *createDefaultOutputFile(bool Binary = true,
689 StringRef BaseInput = "",
690 StringRef Extension = "");
692 /// Create a new output file and add it to the list of tracked output files,
693 /// optionally deriving the output path name.
695 /// \return - Null on error.
696 raw_pwrite_stream *createOutputFile(StringRef OutputPath, bool Binary,
697 bool RemoveFileOnSignal,
698 StringRef BaseInput, StringRef Extension,
700 bool CreateMissingDirectories = false);
702 /// Create a new output file, optionally deriving the output path name.
704 /// If \p OutputPath is empty, then createOutputFile will derive an output
705 /// path location as \p BaseInput, with any suffix removed, and \p Extension
706 /// appended. If \p OutputPath is not stdout and \p UseTemporary
707 /// is true, createOutputFile will create a new temporary file that must be
708 /// renamed to \p OutputPath in the end.
710 /// \param OutputPath - If given, the path to the output file.
711 /// \param Error [out] - On failure, the error.
712 /// \param BaseInput - If \p OutputPath is empty, the input path name to use
713 /// for deriving the output path.
714 /// \param Extension - The extension to use for derived output names.
715 /// \param Binary - The mode to open the file in.
716 /// \param RemoveFileOnSignal - Whether the file should be registered with
717 /// llvm::sys::RemoveFileOnSignal. Note that this is not safe for
718 /// multithreaded use, as the underlying signal mechanism is not reentrant
719 /// \param UseTemporary - Create a new temporary file that must be renamed to
720 /// OutputPath in the end.
721 /// \param CreateMissingDirectories - When \p UseTemporary is true, create
722 /// missing directories in the output path.
723 /// \param ResultPathName [out] - If given, the result path name will be
724 /// stored here on success.
725 /// \param TempPathName [out] - If given, the temporary file path name
726 /// will be stored here on success.
727 std::unique_ptr<raw_pwrite_stream>
728 createOutputFile(StringRef OutputPath, std::error_code &Error, bool Binary,
729 bool RemoveFileOnSignal, StringRef BaseInput,
730 StringRef Extension, bool UseTemporary,
731 bool CreateMissingDirectories, std::string *ResultPathName,
732 std::string *TempPathName);
734 llvm::raw_null_ostream *createNullOutputFile();
737 /// @name Initialization Utility Methods
740 /// InitializeSourceManager - Initialize the source manager to set InputFile
741 /// as the main file.
743 /// \return True on success.
744 bool InitializeSourceManager(const FrontendInputFile &Input);
746 /// InitializeSourceManager - Initialize the source manager to set InputFile
747 /// as the main file.
749 /// \return True on success.
750 static bool InitializeSourceManager(const FrontendInputFile &Input,
751 DiagnosticsEngine &Diags,
752 FileManager &FileMgr,
753 SourceManager &SourceMgr,
754 const FrontendOptions &Opts);
758 // Create module manager.
759 void createModuleManager();
761 bool loadModuleFile(StringRef FileName);
763 ModuleLoadResult loadModule(SourceLocation ImportLoc, ModuleIdPath Path,
764 Module::NameVisibilityKind Visibility,
765 bool IsInclusionDirective) override;
767 void makeModuleVisible(Module *Mod, Module::NameVisibilityKind Visibility,
768 SourceLocation ImportLoc) override;
770 bool hadModuleLoaderFatalFailure() const {
771 return ModuleLoader::HadFatalFailure;
774 GlobalModuleIndex *loadGlobalModuleIndex(SourceLocation TriggerLoc) override;
776 bool lookupMissingImports(StringRef Name, SourceLocation TriggerLoc) override;
778 void addDependencyCollector(std::shared_ptr<DependencyCollector> Listener) {
779 DependencyCollectors.push_back(std::move(Listener));
783 } // end namespace clang