HeaderSearch.h revision 809d1be9820039b4cf6efa48246a0d70ffa13394
1//===--- HeaderSearch.h - Resolve Header File Locations ---------*- 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// This file defines the HeaderSearch interface. 11// 12//===----------------------------------------------------------------------===// 13 14#ifndef LLVM_CLANG_LEX_HEADERSEARCH_H 15#define LLVM_CLANG_LEX_HEADERSEARCH_H 16 17#include "clang/Lex/DirectoryLookup.h" 18#include "clang/Lex/ModuleMap.h" 19#include "llvm/ADT/ArrayRef.h" 20#include "llvm/ADT/StringMap.h" 21#include "llvm/ADT/StringSet.h" 22#include "llvm/Support/Allocator.h" 23#include "llvm/ADT/OwningPtr.h" 24#include <vector> 25 26namespace clang { 27 28class DiagnosticsEngine; 29class ExternalIdentifierLookup; 30class FileEntry; 31class FileManager; 32class IdentifierInfo; 33 34/// HeaderFileInfo - The preprocessor keeps track of this information for each 35/// file that is \#included. 36struct HeaderFileInfo { 37 /// isImport - True if this is a \#import'd or \#pragma once file. 38 unsigned isImport : 1; 39 40 /// isPragmaOnce - True if this is \#pragma once file. 41 unsigned isPragmaOnce : 1; 42 43 /// DirInfo - Keep track of whether this is a system header, and if so, 44 /// whether it is C++ clean or not. This can be set by the include paths or 45 /// by #pragma gcc system_header. This is an instance of 46 /// SrcMgr::CharacteristicKind. 47 unsigned DirInfo : 2; 48 49 /// \brief Whether this header file info was supplied by an external source. 50 unsigned External : 1; 51 52 /// \brief Whether this structure is considered to already have been 53 /// "resolved", meaning that it was loaded from the external source. 54 unsigned Resolved : 1; 55 56 /// \brief Whether this is a header inside a framework that is currently 57 /// being built. 58 /// 59 /// When a framework is being built, the headers have not yet been placed 60 /// into the appropriate framework subdirectories, and therefore are 61 /// provided via a header map. This bit indicates when this is one of 62 /// those framework headers. 63 unsigned IndexHeaderMapHeader : 1; 64 65 /// NumIncludes - This is the number of times the file has been included 66 /// already. 67 unsigned short NumIncludes; 68 69 /// \brief The ID number of the controlling macro. 70 /// 71 /// This ID number will be non-zero when there is a controlling 72 /// macro whose IdentifierInfo may not yet have been loaded from 73 /// external storage. 74 unsigned ControllingMacroID; 75 76 /// ControllingMacro - If this file has a #ifndef XXX (or equivalent) guard 77 /// that protects the entire contents of the file, this is the identifier 78 /// for the macro that controls whether or not it has any effect. 79 /// 80 /// Note: Most clients should use getControllingMacro() to access 81 /// the controlling macro of this header, since 82 /// getControllingMacro() is able to load a controlling macro from 83 /// external storage. 84 const IdentifierInfo *ControllingMacro; 85 86 /// \brief If this header came from a framework include, this is the name 87 /// of the framework. 88 StringRef Framework; 89 90 HeaderFileInfo() 91 : isImport(false), isPragmaOnce(false), DirInfo(SrcMgr::C_User), 92 External(false), Resolved(false), IndexHeaderMapHeader(false), 93 NumIncludes(0), ControllingMacroID(0), ControllingMacro(0) {} 94 95 /// \brief Retrieve the controlling macro for this header file, if 96 /// any. 97 const IdentifierInfo *getControllingMacro(ExternalIdentifierLookup *External); 98 99 /// \brief Determine whether this is a non-default header file info, e.g., 100 /// it corresponds to an actual header we've included or tried to include. 101 bool isNonDefault() const { 102 return isImport || isPragmaOnce || NumIncludes || ControllingMacro || 103 ControllingMacroID; 104 } 105}; 106 107/// \brief An external source of header file information, which may supply 108/// information about header files already included. 109class ExternalHeaderFileInfoSource { 110public: 111 virtual ~ExternalHeaderFileInfoSource(); 112 113 /// \brief Retrieve the header file information for the given file entry. 114 /// 115 /// \returns Header file information for the given file entry, with the 116 /// \c External bit set. If the file entry is not known, return a 117 /// default-constructed \c HeaderFileInfo. 118 virtual HeaderFileInfo GetHeaderFileInfo(const FileEntry *FE) = 0; 119}; 120 121/// HeaderSearch - This class encapsulates the information needed to find the 122/// file referenced by a #include or #include_next, (sub-)framework lookup, etc. 123class HeaderSearch { 124 /// This structure is used to record entries in our framework cache. 125 struct FrameworkCacheEntry { 126 /// The directory entry which should be used for the cached framework. 127 const DirectoryEntry *Directory; 128 129 /// Whether this framework has been "user-specified" to be treated as if it 130 /// were a system framework (even if it was found outside a system framework 131 /// directory). 132 bool IsUserSpecifiedSystemFramework; 133 }; 134 135 FileManager &FileMgr; 136 DiagnosticsEngine &Diags; 137 /// #include search path information. Requests for #include "x" search the 138 /// directory of the #including file first, then each directory in SearchDirs 139 /// consecutively. Requests for <x> search the current dir first, then each 140 /// directory in SearchDirs, starting at AngledDirIdx, consecutively. If 141 /// NoCurDirSearch is true, then the check for the file in the current 142 /// directory is suppressed. 143 std::vector<DirectoryLookup> SearchDirs; 144 unsigned AngledDirIdx; 145 unsigned SystemDirIdx; 146 bool NoCurDirSearch; 147 148 /// #include prefixes for which the 'system header' property is overridden. 149 /// For a #include "x" or #include <x> directive, the last string in this 150 /// list which is a prefix of 'x' determines whether the file is treated as 151 /// a system header. 152 std::vector<std::pair<std::string, bool> > SystemHeaderPrefixes; 153 154 /// \brief The path to the module cache. 155 std::string ModuleCachePath; 156 157 /// FileInfo - This contains all of the preprocessor-specific data about files 158 /// that are included. The vector is indexed by the FileEntry's UID. 159 /// 160 std::vector<HeaderFileInfo> FileInfo; 161 162 /// LookupFileCache - This is keeps track of each lookup performed by 163 /// LookupFile. The first part of the value is the starting index in 164 /// SearchDirs that the cached search was performed from. If there is a hit 165 /// and this value doesn't match the current query, the cache has to be 166 /// ignored. The second value is the entry in SearchDirs that satisfied the 167 /// query. 168 llvm::StringMap<std::pair<unsigned, unsigned>, llvm::BumpPtrAllocator> 169 LookupFileCache; 170 171 /// FrameworkMap - This is a collection mapping a framework or subframework 172 /// name like "Carbon" to the Carbon.framework directory. 173 llvm::StringMap<FrameworkCacheEntry, llvm::BumpPtrAllocator> FrameworkMap; 174 175 /// IncludeAliases - maps include file names (including the quotes or 176 /// angle brackets) to other include file names. This is used to support the 177 /// include_alias pragma for Microsoft compatibility. 178 typedef llvm::StringMap<std::string, llvm::BumpPtrAllocator> 179 IncludeAliasMap; 180 OwningPtr<IncludeAliasMap> IncludeAliases; 181 182 /// HeaderMaps - This is a mapping from FileEntry -> HeaderMap, uniquing 183 /// headermaps. This vector owns the headermap. 184 std::vector<std::pair<const FileEntry*, const HeaderMap*> > HeaderMaps; 185 186 /// \brief The mapping between modules and headers. 187 ModuleMap ModMap; 188 189 /// \brief Describes whether a given directory has a module map in it. 190 llvm::DenseMap<const DirectoryEntry *, bool> DirectoryHasModuleMap; 191 192 /// \brief Uniqued set of framework names, which is used to track which 193 /// headers were included as framework headers. 194 llvm::StringSet<llvm::BumpPtrAllocator> FrameworkNames; 195 196 /// \brief Entity used to resolve the identifier IDs of controlling 197 /// macros into IdentifierInfo pointers, as needed. 198 ExternalIdentifierLookup *ExternalLookup; 199 200 /// \brief Entity used to look up stored header file information. 201 ExternalHeaderFileInfoSource *ExternalSource; 202 203 // Various statistics we track for performance analysis. 204 unsigned NumIncluded; 205 unsigned NumMultiIncludeFileOptzn; 206 unsigned NumFrameworkLookups, NumSubFrameworkLookups; 207 208 // HeaderSearch doesn't support default or copy construction. 209 explicit HeaderSearch(); 210 explicit HeaderSearch(const HeaderSearch&); 211 void operator=(const HeaderSearch&); 212 213 friend class DirectoryLookup; 214 215public: 216 HeaderSearch(FileManager &FM, DiagnosticsEngine &Diags, 217 const LangOptions &LangOpts, const TargetInfo *Target); 218 ~HeaderSearch(); 219 220 FileManager &getFileMgr() const { return FileMgr; } 221 222 /// SetSearchPaths - Interface for setting the file search paths. 223 /// 224 void SetSearchPaths(const std::vector<DirectoryLookup> &dirs, 225 unsigned angledDirIdx, unsigned systemDirIdx, 226 bool noCurDirSearch) { 227 assert(angledDirIdx <= systemDirIdx && systemDirIdx <= dirs.size() && 228 "Directory indicies are unordered"); 229 SearchDirs = dirs; 230 AngledDirIdx = angledDirIdx; 231 SystemDirIdx = systemDirIdx; 232 NoCurDirSearch = noCurDirSearch; 233 //LookupFileCache.clear(); 234 } 235 236 /// AddSearchPath - Add an additional search path. 237 void AddSearchPath(const DirectoryLookup &dir, bool isAngled) { 238 unsigned idx = isAngled ? SystemDirIdx : AngledDirIdx; 239 SearchDirs.insert(SearchDirs.begin() + idx, dir); 240 if (!isAngled) 241 AngledDirIdx++; 242 SystemDirIdx++; 243 } 244 245 /// SetSystemHeaderPrefixes - Set the list of system header prefixes. 246 void SetSystemHeaderPrefixes(ArrayRef<std::pair<std::string, bool> > P) { 247 SystemHeaderPrefixes.assign(P.begin(), P.end()); 248 } 249 250 /// HasIncludeAliasMap - Checks whether the map exists or not 251 bool HasIncludeAliasMap() const { 252 return IncludeAliases; 253 } 254 255 /// AddIncludeAlias - Map the source include name to the dest include name. 256 /// The Source should include the angle brackets or quotes, the dest 257 /// should not. This allows for distinction between <> and "" headers. 258 void AddIncludeAlias(StringRef Source, StringRef Dest) { 259 if (!IncludeAliases) 260 IncludeAliases.reset(new IncludeAliasMap); 261 (*IncludeAliases)[Source] = Dest; 262 } 263 264 /// MapHeaderToIncludeAlias - Maps one header file name to a different header 265 /// file name, for use with the include_alias pragma. Note that the source 266 /// file name should include the angle brackets or quotes. Returns StringRef 267 /// as null if the header cannot be mapped. 268 StringRef MapHeaderToIncludeAlias(StringRef Source) { 269 assert(IncludeAliases && "Trying to map headers when there's no map"); 270 271 // Do any filename replacements before anything else 272 IncludeAliasMap::const_iterator Iter = IncludeAliases->find(Source); 273 if (Iter != IncludeAliases->end()) 274 return Iter->second; 275 return StringRef(); 276 } 277 278 /// \brief Set the path to the module cache. 279 void setModuleCachePath(StringRef CachePath) { 280 ModuleCachePath = CachePath; 281 } 282 283 /// \brief Retrieve the path to the module cache. 284 StringRef getModuleCachePath() const { return ModuleCachePath; } 285 286 /// ClearFileInfo - Forget everything we know about headers so far. 287 void ClearFileInfo() { 288 FileInfo.clear(); 289 } 290 291 void SetExternalLookup(ExternalIdentifierLookup *EIL) { 292 ExternalLookup = EIL; 293 } 294 295 ExternalIdentifierLookup *getExternalLookup() const { 296 return ExternalLookup; 297 } 298 299 /// \brief Set the external source of header information. 300 void SetExternalSource(ExternalHeaderFileInfoSource *ES) { 301 ExternalSource = ES; 302 } 303 304 /// \brief Set the target information for the header search, if not 305 /// already known. 306 void setTarget(const TargetInfo &Target); 307 308 /// LookupFile - Given a "foo" or <foo> reference, look up the indicated file, 309 /// return null on failure. 310 /// 311 /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member 312 /// the file was found in, or null if not applicable. 313 /// 314 /// \param isAngled indicates whether the file reference is a <> reference. 315 /// 316 /// \param CurDir If non-null, the file was found in the specified directory 317 /// search location. This is used to implement #include_next. 318 /// 319 /// \param CurFileEnt If non-null, indicates where the #including file is, in 320 /// case a relative search is needed. 321 /// 322 /// \param SearchPath If non-null, will be set to the search path relative 323 /// to which the file was found. If the include path is absolute, SearchPath 324 /// will be set to an empty string. 325 /// 326 /// \param RelativePath If non-null, will be set to the path relative to 327 /// SearchPath at which the file was found. This only differs from the 328 /// Filename for framework includes. 329 /// 330 /// \param SuggestedModule If non-null, and the file found is semantically 331 /// part of a known module, this will be set to the module that should 332 /// be imported instead of preprocessing/parsing the file found. 333 const FileEntry *LookupFile(StringRef Filename, bool isAngled, 334 const DirectoryLookup *FromDir, 335 const DirectoryLookup *&CurDir, 336 const FileEntry *CurFileEnt, 337 SmallVectorImpl<char> *SearchPath, 338 SmallVectorImpl<char> *RelativePath, 339 Module **SuggestedModule, 340 bool SkipCache = false); 341 342 /// LookupSubframeworkHeader - Look up a subframework for the specified 343 /// #include file. For example, if #include'ing <HIToolbox/HIToolbox.h> from 344 /// within ".../Carbon.framework/Headers/Carbon.h", check to see if HIToolbox 345 /// is a subframework within Carbon.framework. If so, return the FileEntry 346 /// for the designated file, otherwise return null. 347 const FileEntry *LookupSubframeworkHeader( 348 StringRef Filename, 349 const FileEntry *RelativeFileEnt, 350 SmallVectorImpl<char> *SearchPath, 351 SmallVectorImpl<char> *RelativePath); 352 353 /// LookupFrameworkCache - Look up the specified framework name in our 354 /// framework cache, returning the DirectoryEntry it is in if we know, 355 /// otherwise, return null. 356 FrameworkCacheEntry &LookupFrameworkCache(StringRef FWName) { 357 return FrameworkMap.GetOrCreateValue(FWName).getValue(); 358 } 359 360 /// ShouldEnterIncludeFile - Mark the specified file as a target of of a 361 /// #include, #include_next, or #import directive. Return false if #including 362 /// the file will have no effect or true if we should include it. 363 bool ShouldEnterIncludeFile(const FileEntry *File, bool isImport); 364 365 366 /// getFileDirFlavor - Return whether the specified file is a normal header, 367 /// a system header, or a C++ friendly system header. 368 SrcMgr::CharacteristicKind getFileDirFlavor(const FileEntry *File) { 369 return (SrcMgr::CharacteristicKind)getFileInfo(File).DirInfo; 370 } 371 372 /// MarkFileIncludeOnce - Mark the specified file as a "once only" file, e.g. 373 /// due to #pragma once. 374 void MarkFileIncludeOnce(const FileEntry *File) { 375 HeaderFileInfo &FI = getFileInfo(File); 376 FI.isImport = true; 377 FI.isPragmaOnce = true; 378 } 379 380 /// MarkFileSystemHeader - Mark the specified file as a system header, e.g. 381 /// due to #pragma GCC system_header. 382 void MarkFileSystemHeader(const FileEntry *File) { 383 getFileInfo(File).DirInfo = SrcMgr::C_System; 384 } 385 386 /// IncrementIncludeCount - Increment the count for the number of times the 387 /// specified FileEntry has been entered. 388 void IncrementIncludeCount(const FileEntry *File) { 389 ++getFileInfo(File).NumIncludes; 390 } 391 392 /// SetFileControllingMacro - Mark the specified file as having a controlling 393 /// macro. This is used by the multiple-include optimization to eliminate 394 /// no-op \#includes. 395 void SetFileControllingMacro(const FileEntry *File, 396 const IdentifierInfo *ControllingMacro) { 397 getFileInfo(File).ControllingMacro = ControllingMacro; 398 } 399 400 /// \brief Determine whether this file is intended to be safe from 401 /// multiple inclusions, e.g., it has \#pragma once or a controlling 402 /// macro. 403 /// 404 /// This routine does not consider the effect of \#import 405 bool isFileMultipleIncludeGuarded(const FileEntry *File); 406 407 /// CreateHeaderMap - This method returns a HeaderMap for the specified 408 /// FileEntry, uniquing them through the the 'HeaderMaps' datastructure. 409 const HeaderMap *CreateHeaderMap(const FileEntry *FE); 410 411 /// \brief Retrieve the name of the module file that should be used to 412 /// load the given module. 413 /// 414 /// \param Module The module whose module file name will be returned. 415 /// 416 /// \returns The name of the module file that corresponds to this module, 417 /// or an empty string if this module does not correspond to any module file. 418 std::string getModuleFileName(Module *Module); 419 420 /// \brief Retrieve the name of the module file that should be used to 421 /// load a module with the given name. 422 /// 423 /// \param Module The module whose module file name will be returned. 424 /// 425 /// \returns The name of the module file that corresponds to this module, 426 /// or an empty string if this module does not correspond to any module file. 427 std::string getModuleFileName(StringRef ModuleName); 428 429 /// \brief Lookup a module Search for a module with the given name. 430 /// 431 /// \param ModuleName The name of the module we're looking for. 432 /// 433 /// \param AllowSearch Whether we are allowed to search in the various 434 /// search directories to produce a module definition. If not, this lookup 435 /// will only return an already-known module. 436 /// 437 /// \returns The module with the given name. 438 Module *lookupModule(StringRef ModuleName, bool AllowSearch = true); 439 440 void IncrementFrameworkLookupCount() { ++NumFrameworkLookups; } 441 442 /// \brief Determine whether there is a module map that may map the header 443 /// with the given file name to a (sub)module. 444 /// 445 /// \param Filename The name of the file. 446 /// 447 /// \param Root The "root" directory, at which we should stop looking for 448 /// module maps. 449 bool hasModuleMap(StringRef Filename, const DirectoryEntry *Root); 450 451 /// \brief Retrieve the module that corresponds to the given file, if any. 452 /// 453 /// \param File The header that we wish to map to a module. 454 Module *findModuleForHeader(const FileEntry *File); 455 456 /// \brief Read the contents of the given module map file. 457 /// 458 /// \param File The module map file. 459 /// 460 /// \param OnlyModule If non-NULL, this will receive the 461 /// 462 /// \returns true if an error occurred, false otherwise. 463 bool loadModuleMapFile(const FileEntry *File); 464 465 /// \brief Collect the set of all known, top-level modules. 466 /// 467 /// \param Modules Will be filled with the set of known, top-level modules. 468 void collectAllModules(llvm::SmallVectorImpl<Module *> &Modules); 469 470private: 471 /// \brief Retrieve a module with the given name, which may be part of the 472 /// given framework. 473 /// 474 /// \param Name The name of the module to retrieve. 475 /// 476 /// \param Dir The framework directory (e.g., ModuleName.framework). 477 /// 478 /// \param IsSystem Whether the framework directory is part of the system 479 /// frameworks. 480 /// 481 /// \returns The module, if found; otherwise, null. 482 Module *loadFrameworkModule(StringRef Name, 483 const DirectoryEntry *Dir, 484 bool IsSystem); 485 486public: 487 /// \brief Retrieve the module map. 488 ModuleMap &getModuleMap() { return ModMap; } 489 490 unsigned header_file_size() const { return FileInfo.size(); } 491 492 // Used by ASTReader. 493 void setHeaderFileInfoForUID(HeaderFileInfo HFI, unsigned UID); 494 495 /// getFileInfo - Return the HeaderFileInfo structure for the specified 496 /// FileEntry. 497 const HeaderFileInfo &getFileInfo(const FileEntry *FE) const { 498 return const_cast<HeaderSearch*>(this)->getFileInfo(FE); 499 } 500 501 // Used by external tools 502 typedef std::vector<DirectoryLookup>::const_iterator search_dir_iterator; 503 search_dir_iterator search_dir_begin() const { return SearchDirs.begin(); } 504 search_dir_iterator search_dir_end() const { return SearchDirs.end(); } 505 unsigned search_dir_size() const { return SearchDirs.size(); } 506 507 search_dir_iterator quoted_dir_begin() const { 508 return SearchDirs.begin(); 509 } 510 search_dir_iterator quoted_dir_end() const { 511 return SearchDirs.begin() + AngledDirIdx; 512 } 513 514 search_dir_iterator angled_dir_begin() const { 515 return SearchDirs.begin() + AngledDirIdx; 516 } 517 search_dir_iterator angled_dir_end() const { 518 return SearchDirs.begin() + SystemDirIdx; 519 } 520 521 search_dir_iterator system_dir_begin() const { 522 return SearchDirs.begin() + SystemDirIdx; 523 } 524 search_dir_iterator system_dir_end() const { return SearchDirs.end(); } 525 526 /// \brief Retrieve a uniqued framework name. 527 StringRef getUniqueFrameworkName(StringRef Framework); 528 529 void PrintStats(); 530 531 size_t getTotalMemory() const; 532 533 static std::string NormalizeDashIncludePath(StringRef File, 534 FileManager &FileMgr); 535 536private: 537 /// \brief Describes what happened when we tried to load a module map file. 538 enum LoadModuleMapResult { 539 /// \brief The module map file had already been loaded. 540 LMM_AlreadyLoaded, 541 /// \brief The module map file was loaded by this invocation. 542 LMM_NewlyLoaded, 543 /// \brief There is was directory with the given name. 544 LMM_NoDirectory, 545 /// \brief There was either no module map file or the module map file was 546 /// invalid. 547 LMM_InvalidModuleMap 548 }; 549 550 /// \brief Try to load the module map file in the given directory. 551 /// 552 /// \param DirName The name of the directory where we will look for a module 553 /// map file. 554 /// 555 /// \returns The result of attempting to load the module map file from the 556 /// named directory. 557 LoadModuleMapResult loadModuleMapFile(StringRef DirName); 558 559 /// \brief Try to load the module map file in the given directory. 560 /// 561 /// \param Dir The directory where we will look for a module map file. 562 /// 563 /// \returns The result of attempting to load the module map file from the 564 /// named directory. 565 LoadModuleMapResult loadModuleMapFile(const DirectoryEntry *Dir); 566 567 /// getFileInfo - Return the HeaderFileInfo structure for the specified 568 /// FileEntry. 569 HeaderFileInfo &getFileInfo(const FileEntry *FE); 570}; 571 572} // end namespace clang 573 574#endif 575