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