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