CompilerInstance.h revision 6aa52ec6b969faabf3764baf79d89810b8249a7e
1//===-- CompilerInstance.h - Clang Compiler Instance ------------*- 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#ifndef LLVM_CLANG_FRONTEND_COMPILERINSTANCE_H_ 11#define LLVM_CLANG_FRONTEND_COMPILERINSTANCE_H_ 12 13#include "clang/Frontend/CompilerInvocation.h" 14#include "clang/Lex/ModuleLoader.h" 15#include "llvm/ADT/IntrusiveRefCntPtr.h" 16#include "llvm/ADT/StringRef.h" 17#include "llvm/ADT/OwningPtr.h" 18#include <cassert> 19#include <list> 20#include <string> 21 22namespace llvm { 23class raw_fd_ostream; 24class Timer; 25} 26 27namespace clang { 28class ASTContext; 29class ASTConsumer; 30class ASTReader; 31class CodeCompleteConsumer; 32class Diagnostic; 33class DiagnosticClient; 34class ExternalASTSource; 35class FileManager; 36class FrontendAction; 37class Preprocessor; 38class Sema; 39class SourceManager; 40class TargetInfo; 41 42/// CompilerInstance - Helper class for managing a single instance of the Clang 43/// compiler. 44/// 45/// The CompilerInstance serves two purposes: 46/// (1) It manages the various objects which are necessary to run the compiler, 47/// for example the preprocessor, the target information, and the AST 48/// context. 49/// (2) It provides utility routines for constructing and manipulating the 50/// common Clang objects. 51/// 52/// The compiler instance generally owns the instance of all the objects that it 53/// manages. However, clients can still share objects by manually setting the 54/// object and retaking ownership prior to destroying the CompilerInstance. 55/// 56/// The compiler instance is intended to simplify clients, but not to lock them 57/// in to the compiler instance for everything. When possible, utility functions 58/// come in two forms; a short form that reuses the CompilerInstance objects, 59/// and a long form that takes explicit instances of any required objects. 60class CompilerInstance : public ModuleLoader { 61 /// The options used in this compiler instance. 62 llvm::IntrusiveRefCntPtr<CompilerInvocation> Invocation; 63 64 /// The diagnostics engine instance. 65 llvm::IntrusiveRefCntPtr<Diagnostic> Diagnostics; 66 67 /// The target being compiled for. 68 llvm::IntrusiveRefCntPtr<TargetInfo> Target; 69 70 /// The file manager. 71 llvm::IntrusiveRefCntPtr<FileManager> FileMgr; 72 73 /// The source manager. 74 llvm::IntrusiveRefCntPtr<SourceManager> SourceMgr; 75 76 /// The preprocessor. 77 llvm::IntrusiveRefCntPtr<Preprocessor> PP; 78 79 /// The AST context. 80 llvm::IntrusiveRefCntPtr<ASTContext> Context; 81 82 /// The AST consumer. 83 llvm::OwningPtr<ASTConsumer> Consumer; 84 85 /// The code completion consumer. 86 llvm::OwningPtr<CodeCompleteConsumer> CompletionConsumer; 87 88 /// \brief The semantic analysis object. 89 llvm::OwningPtr<Sema> TheSema; 90 91 /// \brief The frontend timer 92 llvm::OwningPtr<llvm::Timer> FrontendTimer; 93 94 /// \brief Non-owning reference to the ASTReader, if one exists. 95 ASTReader *ModuleManager; 96 97 /// \brief Holds information about the output file. 98 /// 99 /// If TempFilename is not empty we must rename it to Filename at the end. 100 /// TempFilename may be empty and Filename non empty if creating the temporary 101 /// failed. 102 struct OutputFile { 103 std::string Filename; 104 std::string TempFilename; 105 raw_ostream *OS; 106 107 OutputFile(const std::string &filename, const std::string &tempFilename, 108 raw_ostream *os) 109 : Filename(filename), TempFilename(tempFilename), OS(os) { } 110 }; 111 112 /// The list of active output files. 113 std::list<OutputFile> OutputFiles; 114 115 void operator=(const CompilerInstance &); // DO NOT IMPLEMENT 116 CompilerInstance(const CompilerInstance&); // DO NOT IMPLEMENT 117public: 118 CompilerInstance(); 119 ~CompilerInstance(); 120 121 /// @name High-Level Operations 122 /// { 123 124 /// ExecuteAction - Execute the provided action against the compiler's 125 /// CompilerInvocation object. 126 /// 127 /// This function makes the following assumptions: 128 /// 129 /// - The invocation options should be initialized. This function does not 130 /// handle the '-help' or '-version' options, clients should handle those 131 /// directly. 132 /// 133 /// - The diagnostics engine should have already been created by the client. 134 /// 135 /// - No other CompilerInstance state should have been initialized (this is 136 /// an unchecked error). 137 /// 138 /// - Clients should have initialized any LLVM target features that may be 139 /// required. 140 /// 141 /// - Clients should eventually call llvm_shutdown() upon the completion of 142 /// this routine to ensure that any managed objects are properly destroyed. 143 /// 144 /// Note that this routine may write output to 'stderr'. 145 /// 146 /// \param Act - The action to execute. 147 /// \return - True on success. 148 // 149 // FIXME: This function should take the stream to write any debugging / 150 // verbose output to as an argument. 151 // 152 // FIXME: Eliminate the llvm_shutdown requirement, that should either be part 153 // of the context or else not CompilerInstance specific. 154 bool ExecuteAction(FrontendAction &Act); 155 156 /// } 157 /// @name Compiler Invocation and Options 158 /// { 159 160 bool hasInvocation() const { return Invocation != 0; } 161 162 CompilerInvocation &getInvocation() { 163 assert(Invocation && "Compiler instance has no invocation!"); 164 return *Invocation; 165 } 166 167 /// setInvocation - Replace the current invocation. 168 void setInvocation(CompilerInvocation *Value); 169 170 /// } 171 /// @name Forwarding Methods 172 /// { 173 174 AnalyzerOptions &getAnalyzerOpts() { 175 return Invocation->getAnalyzerOpts(); 176 } 177 const AnalyzerOptions &getAnalyzerOpts() const { 178 return Invocation->getAnalyzerOpts(); 179 } 180 181 CodeGenOptions &getCodeGenOpts() { 182 return Invocation->getCodeGenOpts(); 183 } 184 const CodeGenOptions &getCodeGenOpts() const { 185 return Invocation->getCodeGenOpts(); 186 } 187 188 DependencyOutputOptions &getDependencyOutputOpts() { 189 return Invocation->getDependencyOutputOpts(); 190 } 191 const DependencyOutputOptions &getDependencyOutputOpts() const { 192 return Invocation->getDependencyOutputOpts(); 193 } 194 195 DiagnosticOptions &getDiagnosticOpts() { 196 return Invocation->getDiagnosticOpts(); 197 } 198 const DiagnosticOptions &getDiagnosticOpts() const { 199 return Invocation->getDiagnosticOpts(); 200 } 201 202 const FileSystemOptions &getFileSystemOpts() const { 203 return Invocation->getFileSystemOpts(); 204 } 205 206 FrontendOptions &getFrontendOpts() { 207 return Invocation->getFrontendOpts(); 208 } 209 const FrontendOptions &getFrontendOpts() const { 210 return Invocation->getFrontendOpts(); 211 } 212 213 HeaderSearchOptions &getHeaderSearchOpts() { 214 return Invocation->getHeaderSearchOpts(); 215 } 216 const HeaderSearchOptions &getHeaderSearchOpts() const { 217 return Invocation->getHeaderSearchOpts(); 218 } 219 220 LangOptions &getLangOpts() { 221 return Invocation->getLangOpts(); 222 } 223 const LangOptions &getLangOpts() const { 224 return Invocation->getLangOpts(); 225 } 226 227 PreprocessorOptions &getPreprocessorOpts() { 228 return Invocation->getPreprocessorOpts(); 229 } 230 const PreprocessorOptions &getPreprocessorOpts() const { 231 return Invocation->getPreprocessorOpts(); 232 } 233 234 PreprocessorOutputOptions &getPreprocessorOutputOpts() { 235 return Invocation->getPreprocessorOutputOpts(); 236 } 237 const PreprocessorOutputOptions &getPreprocessorOutputOpts() const { 238 return Invocation->getPreprocessorOutputOpts(); 239 } 240 241 TargetOptions &getTargetOpts() { 242 return Invocation->getTargetOpts(); 243 } 244 const TargetOptions &getTargetOpts() const { 245 return Invocation->getTargetOpts(); 246 } 247 248 /// } 249 /// @name Diagnostics Engine 250 /// { 251 252 bool hasDiagnostics() const { return Diagnostics != 0; } 253 254 /// Get the current diagnostics engine. 255 Diagnostic &getDiagnostics() const { 256 assert(Diagnostics && "Compiler instance has no diagnostics!"); 257 return *Diagnostics; 258 } 259 260 /// setDiagnostics - Replace the current diagnostics engine. 261 void setDiagnostics(Diagnostic *Value); 262 263 DiagnosticClient &getDiagnosticClient() const { 264 assert(Diagnostics && Diagnostics->getClient() && 265 "Compiler instance has no diagnostic client!"); 266 return *Diagnostics->getClient(); 267 } 268 269 /// } 270 /// @name Target Info 271 /// { 272 273 bool hasTarget() const { return Target != 0; } 274 275 TargetInfo &getTarget() const { 276 assert(Target && "Compiler instance has no target!"); 277 return *Target; 278 } 279 280 /// Replace the current diagnostics engine. 281 void setTarget(TargetInfo *Value); 282 283 /// } 284 /// @name File Manager 285 /// { 286 287 bool hasFileManager() const { return FileMgr != 0; } 288 289 /// Return the current file manager to the caller. 290 FileManager &getFileManager() const { 291 assert(FileMgr && "Compiler instance has no file manager!"); 292 return *FileMgr; 293 } 294 295 void resetAndLeakFileManager() { 296 FileMgr.resetWithoutRelease(); 297 } 298 299 /// setFileManager - Replace the current file manager. 300 void setFileManager(FileManager *Value); 301 302 /// } 303 /// @name Source Manager 304 /// { 305 306 bool hasSourceManager() const { return SourceMgr != 0; } 307 308 /// Return the current source manager. 309 SourceManager &getSourceManager() const { 310 assert(SourceMgr && "Compiler instance has no source manager!"); 311 return *SourceMgr; 312 } 313 314 void resetAndLeakSourceManager() { 315 SourceMgr.resetWithoutRelease(); 316 } 317 318 /// setSourceManager - Replace the current source manager. 319 void setSourceManager(SourceManager *Value); 320 321 /// } 322 /// @name Preprocessor 323 /// { 324 325 bool hasPreprocessor() const { return PP != 0; } 326 327 /// Return the current preprocessor. 328 Preprocessor &getPreprocessor() const { 329 assert(PP && "Compiler instance has no preprocessor!"); 330 return *PP; 331 } 332 333 void resetAndLeakPreprocessor() { 334 PP.resetWithoutRelease(); 335 } 336 337 /// Replace the current preprocessor. 338 void setPreprocessor(Preprocessor *Value); 339 340 /// } 341 /// @name ASTContext 342 /// { 343 344 bool hasASTContext() const { return Context != 0; } 345 346 ASTContext &getASTContext() const { 347 assert(Context && "Compiler instance has no AST context!"); 348 return *Context; 349 } 350 351 void resetAndLeakASTContext() { 352 Context.resetWithoutRelease(); 353 } 354 355 /// setASTContext - Replace the current AST context. 356 void setASTContext(ASTContext *Value); 357 358 /// \brief Replace the current Sema; the compiler instance takes ownership 359 /// of S. 360 void setSema(Sema *S); 361 362 /// } 363 /// @name ASTConsumer 364 /// { 365 366 bool hasASTConsumer() const { return Consumer != 0; } 367 368 ASTConsumer &getASTConsumer() const { 369 assert(Consumer && "Compiler instance has no AST consumer!"); 370 return *Consumer; 371 } 372 373 /// takeASTConsumer - Remove the current AST consumer and give ownership to 374 /// the caller. 375 ASTConsumer *takeASTConsumer() { return Consumer.take(); } 376 377 /// setASTConsumer - Replace the current AST consumer; the compiler instance 378 /// takes ownership of \arg Value. 379 void setASTConsumer(ASTConsumer *Value); 380 381 /// } 382 /// @name Semantic analysis 383 /// { 384 bool hasSema() const { return TheSema != 0; } 385 386 Sema &getSema() const { 387 assert(TheSema && "Compiler instance has no Sema object!"); 388 return *TheSema; 389 } 390 391 Sema *takeSema() { return TheSema.take(); } 392 393 /// } 394 /// @name Module Management 395 /// { 396 397 ASTReader *getModuleManager() const { return ModuleManager; } 398 399 /// } 400 /// @name Code Completion 401 /// { 402 403 bool hasCodeCompletionConsumer() const { return CompletionConsumer != 0; } 404 405 CodeCompleteConsumer &getCodeCompletionConsumer() const { 406 assert(CompletionConsumer && 407 "Compiler instance has no code completion consumer!"); 408 return *CompletionConsumer; 409 } 410 411 /// takeCodeCompletionConsumer - Remove the current code completion consumer 412 /// and give ownership to the caller. 413 CodeCompleteConsumer *takeCodeCompletionConsumer() { 414 return CompletionConsumer.take(); 415 } 416 417 /// setCodeCompletionConsumer - Replace the current code completion consumer; 418 /// the compiler instance takes ownership of \arg Value. 419 void setCodeCompletionConsumer(CodeCompleteConsumer *Value); 420 421 /// } 422 /// @name Frontend timer 423 /// { 424 425 bool hasFrontendTimer() const { return FrontendTimer != 0; } 426 427 llvm::Timer &getFrontendTimer() const { 428 assert(FrontendTimer && "Compiler instance has no frontend timer!"); 429 return *FrontendTimer; 430 } 431 432 /// } 433 /// @name Output Files 434 /// { 435 436 /// addOutputFile - Add an output file onto the list of tracked output files. 437 /// 438 /// \param OutFile - The output file info. 439 void addOutputFile(const OutputFile &OutFile); 440 441 /// clearOutputFiles - Clear the output file list, destroying the contained 442 /// output streams. 443 /// 444 /// \param EraseFiles - If true, attempt to erase the files from disk. 445 void clearOutputFiles(bool EraseFiles); 446 447 /// } 448 /// @name Construction Utility Methods 449 /// { 450 451 /// Create the diagnostics engine using the invocation's diagnostic options 452 /// and replace any existing one with it. 453 /// 454 /// Note that this routine also replaces the diagnostic client, 455 /// allocating one if one is not provided. 456 /// 457 /// \param Client If non-NULL, a diagnostic client that will be 458 /// attached to (and, then, owned by) the Diagnostic inside this AST 459 /// unit. 460 void createDiagnostics(int Argc, const char* const *Argv, 461 DiagnosticClient *Client = 0); 462 463 /// Create a Diagnostic object with a the TextDiagnosticPrinter. 464 /// 465 /// The \arg Argc and \arg Argv arguments are used only for logging purposes, 466 /// when the diagnostic options indicate that the compiler should output 467 /// logging information. 468 /// 469 /// If no diagnostic client is provided, this creates a 470 /// DiagnosticClient that is owned by the returned diagnostic 471 /// object, if using directly the caller is responsible for 472 /// releasing the returned Diagnostic's client eventually. 473 /// 474 /// \param Opts - The diagnostic options; note that the created text 475 /// diagnostic object contains a reference to these options and its lifetime 476 /// must extend past that of the diagnostic engine. 477 /// 478 /// \param Client If non-NULL, a diagnostic client that will be 479 /// attached to (and, then, owned by) the returned Diagnostic 480 /// object. 481 /// 482 /// \param CodeGenOpts If non-NULL, the code gen options in use, which may be 483 /// used by some diagnostics printers (for logging purposes only). 484 /// 485 /// \return The new object on success, or null on failure. 486 static llvm::IntrusiveRefCntPtr<Diagnostic> 487 createDiagnostics(const DiagnosticOptions &Opts, int Argc, 488 const char* const *Argv, 489 DiagnosticClient *Client = 0, 490 const CodeGenOptions *CodeGenOpts = 0); 491 492 /// Create the file manager and replace any existing one with it. 493 void createFileManager(); 494 495 /// Create the source manager and replace any existing one with it. 496 void createSourceManager(FileManager &FileMgr); 497 498 /// Create the preprocessor, using the invocation, file, and source managers, 499 /// and replace any existing one with it. 500 void createPreprocessor(); 501 502 /// Create the AST context. 503 void createASTContext(); 504 505 /// Create an external AST source to read a PCH file and attach it to the AST 506 /// context. 507 void createPCHExternalASTSource(StringRef Path, 508 bool DisablePCHValidation, 509 bool DisableStatCache, 510 void *DeserializationListener); 511 512 /// Create an external AST source to read a PCH file. 513 /// 514 /// \return - The new object on success, or null on failure. 515 static ExternalASTSource * 516 createPCHExternalASTSource(StringRef Path, const std::string &Sysroot, 517 bool DisablePCHValidation, 518 bool DisableStatCache, 519 Preprocessor &PP, ASTContext &Context, 520 void *DeserializationListener, bool Preamble); 521 522 /// Create a code completion consumer using the invocation; note that this 523 /// will cause the source manager to truncate the input source file at the 524 /// completion point. 525 void createCodeCompletionConsumer(); 526 527 /// Create a code completion consumer to print code completion results, at 528 /// \arg Filename, \arg Line, and \arg Column, to the given output stream \arg 529 /// OS. 530 static CodeCompleteConsumer * 531 createCodeCompletionConsumer(Preprocessor &PP, const std::string &Filename, 532 unsigned Line, unsigned Column, 533 bool ShowMacros, 534 bool ShowCodePatterns, bool ShowGlobals, 535 raw_ostream &OS); 536 537 /// \brief Create the Sema object to be used for parsing. 538 void createSema(TranslationUnitKind TUKind, 539 CodeCompleteConsumer *CompletionConsumer); 540 541 /// Create the frontend timer and replace any existing one with it. 542 void createFrontendTimer(); 543 544 /// Create the default output file (from the invocation's options) and add it 545 /// to the list of tracked output files. 546 /// 547 /// \return - Null on error. 548 llvm::raw_fd_ostream * 549 createDefaultOutputFile(bool Binary = true, StringRef BaseInput = "", 550 StringRef Extension = ""); 551 552 /// Create a new output file and add it to the list of tracked output files, 553 /// optionally deriving the output path name. 554 /// 555 /// \return - Null on error. 556 llvm::raw_fd_ostream * 557 createOutputFile(StringRef OutputPath, 558 bool Binary = true, bool RemoveFileOnSignal = true, 559 StringRef BaseInput = "", 560 StringRef Extension = "", 561 bool UseTemporary = false); 562 563 /// Create a new output file, optionally deriving the output path name. 564 /// 565 /// If \arg OutputPath is empty, then createOutputFile will derive an output 566 /// path location as \arg BaseInput, with any suffix removed, and \arg 567 /// Extension appended. If OutputPath is not stdout and \arg UseTemporary 568 /// is true, createOutputFile will create a new temporary file that must be 569 /// renamed to OutputPath in the end. 570 /// 571 /// \param OutputPath - If given, the path to the output file. 572 /// \param Error [out] - On failure, the error message. 573 /// \param BaseInput - If \arg OutputPath is empty, the input path name to use 574 /// for deriving the output path. 575 /// \param Extension - The extension to use for derived output names. 576 /// \param Binary - The mode to open the file in. 577 /// \param RemoveFileOnSignal - Whether the file should be registered with 578 /// llvm::sys::RemoveFileOnSignal. Note that this is not safe for 579 /// multithreaded use, as the underlying signal mechanism is not reentrant 580 /// \param UseTemporary - Create a new temporary file that must be renamed to 581 /// OutputPath in the end 582 /// \param ResultPathName [out] - If given, the result path name will be 583 /// stored here on success. 584 /// \param TempPathName [out] - If given, the temporary file path name 585 /// will be stored here on success. 586 static llvm::raw_fd_ostream * 587 createOutputFile(StringRef OutputPath, std::string &Error, 588 bool Binary = true, bool RemoveFileOnSignal = true, 589 StringRef BaseInput = "", 590 StringRef Extension = "", 591 bool UseTemporary = false, 592 std::string *ResultPathName = 0, 593 std::string *TempPathName = 0); 594 595 /// } 596 /// @name Initialization Utility Methods 597 /// { 598 599 /// InitializeSourceManager - Initialize the source manager to set InputFile 600 /// as the main file. 601 /// 602 /// \return True on success. 603 bool InitializeSourceManager(StringRef InputFile); 604 605 /// InitializeSourceManager - Initialize the source manager to set InputFile 606 /// as the main file. 607 /// 608 /// \return True on success. 609 static bool InitializeSourceManager(StringRef InputFile, 610 Diagnostic &Diags, 611 FileManager &FileMgr, 612 SourceManager &SourceMgr, 613 const FrontendOptions &Opts); 614 615 /// } 616 617 virtual ModuleKey loadModule(SourceLocation ImportLoc, 618 IdentifierInfo &ModuleName, 619 SourceLocation ModuleNameLoc); 620}; 621 622} // end namespace clang 623 624#endif 625