1 //===- HeaderSearch.h - Resolve Header File Locations -----------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // This file defines the HeaderSearch interface. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef LLVM_CLANG_LEX_HEADERSEARCH_H 14 #define LLVM_CLANG_LEX_HEADERSEARCH_H 15 16 #include "clang/Basic/SourceLocation.h" 17 #include "clang/Basic/SourceManager.h" 18 #include "clang/Lex/DirectoryLookup.h" 19 #include "clang/Lex/HeaderMap.h" 20 #include "clang/Lex/ModuleMap.h" 21 #include "llvm/ADT/ArrayRef.h" 22 #include "llvm/ADT/DenseMap.h" 23 #include "llvm/ADT/SmallString.h" 24 #include "llvm/ADT/StringMap.h" 25 #include "llvm/ADT/StringRef.h" 26 #include "llvm/ADT/StringSet.h" 27 #include "llvm/Support/Allocator.h" 28 #include <cassert> 29 #include <cstddef> 30 #include <memory> 31 #include <string> 32 #include <utility> 33 #include <vector> 34 35 namespace llvm { 36 37 class Triple; 38 39 } // namespace llvm 40 41 namespace clang { 42 43 class DiagnosticsEngine; 44 class DirectoryEntry; 45 class ExternalPreprocessorSource; 46 class FileEntry; 47 class FileManager; 48 class HeaderSearch; 49 class HeaderSearchOptions; 50 class IdentifierInfo; 51 class LangOptions; 52 class Module; 53 class Preprocessor; 54 class TargetInfo; 55 56 /// The preprocessor keeps track of this information for each 57 /// file that is \#included. 58 struct HeaderFileInfo { 59 // TODO: Whether the file was imported is not a property of the file itself. 60 // It's a preprocessor state, move it there. 61 /// True if this is a \#import'd file. 62 unsigned isImport : 1; 63 64 /// True if this is a \#pragma once file. 65 unsigned isPragmaOnce : 1; 66 67 /// Keep track of whether this is a system header, and if so, 68 /// whether it is C++ clean or not. This can be set by the include paths or 69 /// by \#pragma gcc system_header. This is an instance of 70 /// SrcMgr::CharacteristicKind. 71 unsigned DirInfo : 3; 72 73 /// Whether this header file info was supplied by an external source, 74 /// and has not changed since. 75 unsigned External : 1; 76 77 /// Whether this header is part of a module. 78 unsigned isModuleHeader : 1; 79 80 /// Whether this header is part of the module that we are building. 81 unsigned isCompilingModuleHeader : 1; 82 83 /// Whether this structure is considered to already have been 84 /// "resolved", meaning that it was loaded from the external source. 85 unsigned Resolved : 1; 86 87 /// Whether this is a header inside a framework that is currently 88 /// being built. 89 /// 90 /// When a framework is being built, the headers have not yet been placed 91 /// into the appropriate framework subdirectories, and therefore are 92 /// provided via a header map. This bit indicates when this is one of 93 /// those framework headers. 94 unsigned IndexHeaderMapHeader : 1; 95 96 /// Whether this file has been looked up as a header. 97 unsigned IsValid : 1; 98 99 /// The ID number of the controlling macro. 100 /// 101 /// This ID number will be non-zero when there is a controlling 102 /// macro whose IdentifierInfo may not yet have been loaded from 103 /// external storage. 104 unsigned ControllingMacroID = 0; 105 106 /// If this file has a \#ifndef XXX (or equivalent) guard that 107 /// protects the entire contents of the file, this is the identifier 108 /// for the macro that controls whether or not it has any effect. 109 /// 110 /// Note: Most clients should use getControllingMacro() to access 111 /// the controlling macro of this header, since 112 /// getControllingMacro() is able to load a controlling macro from 113 /// external storage. 114 const IdentifierInfo *ControllingMacro = nullptr; 115 116 /// If this header came from a framework include, this is the name 117 /// of the framework. 118 StringRef Framework; 119 120 HeaderFileInfo() 121 : isImport(false), isPragmaOnce(false), DirInfo(SrcMgr::C_User), 122 External(false), isModuleHeader(false), isCompilingModuleHeader(false), 123 Resolved(false), IndexHeaderMapHeader(false), IsValid(false) {} 124 125 /// Retrieve the controlling macro for this header file, if 126 /// any. 127 const IdentifierInfo * 128 getControllingMacro(ExternalPreprocessorSource *External); 129 }; 130 131 /// An external source of header file information, which may supply 132 /// information about header files already included. 133 class ExternalHeaderFileInfoSource { 134 public: 135 virtual ~ExternalHeaderFileInfoSource(); 136 137 /// Retrieve the header file information for the given file entry. 138 /// 139 /// \returns Header file information for the given file entry, with the 140 /// \c External bit set. If the file entry is not known, return a 141 /// default-constructed \c HeaderFileInfo. 142 virtual HeaderFileInfo GetHeaderFileInfo(const FileEntry *FE) = 0; 143 }; 144 145 /// This structure is used to record entries in our framework cache. 146 struct FrameworkCacheEntry { 147 /// The directory entry which should be used for the cached framework. 148 Optional<DirectoryEntryRef> Directory; 149 150 /// Whether this framework has been "user-specified" to be treated as if it 151 /// were a system framework (even if it was found outside a system framework 152 /// directory). 153 bool IsUserSpecifiedSystemFramework; 154 }; 155 156 namespace detail { 157 template <bool Const, typename T> 158 using Qualified = std::conditional_t<Const, const T, T>; 159 160 /// Forward iterator over the search directories of \c HeaderSearch. 161 template <bool IsConst> 162 struct SearchDirIteratorImpl 163 : llvm::iterator_facade_base<SearchDirIteratorImpl<IsConst>, 164 std::forward_iterator_tag, 165 Qualified<IsConst, DirectoryLookup>> { 166 /// Const -> non-const iterator conversion. 167 template <typename Enable = std::enable_if<IsConst, bool>> 168 SearchDirIteratorImpl(const SearchDirIteratorImpl<false> &Other) 169 : HS(Other.HS), Idx(Other.Idx) {} 170 171 SearchDirIteratorImpl(const SearchDirIteratorImpl &) = default; 172 173 SearchDirIteratorImpl &operator=(const SearchDirIteratorImpl &) = default; 174 175 bool operator==(const SearchDirIteratorImpl &RHS) const { 176 return HS == RHS.HS && Idx == RHS.Idx; 177 } 178 179 SearchDirIteratorImpl &operator++() { 180 assert(*this && "Invalid iterator."); 181 ++Idx; 182 return *this; 183 } 184 185 Qualified<IsConst, DirectoryLookup> &operator*() const { 186 assert(*this && "Invalid iterator."); 187 return HS->SearchDirs[Idx]; 188 } 189 190 /// Creates an invalid iterator. 191 SearchDirIteratorImpl(std::nullptr_t) : HS(nullptr), Idx(0) {} 192 193 /// Checks whether the iterator is valid. 194 explicit operator bool() const { return HS != nullptr; } 195 196 private: 197 /// The parent \c HeaderSearch. This is \c nullptr for invalid iterator. 198 Qualified<IsConst, HeaderSearch> *HS; 199 200 /// The index of the current element. 201 size_t Idx; 202 203 /// The constructor that creates a valid iterator. 204 SearchDirIteratorImpl(Qualified<IsConst, HeaderSearch> &HS, size_t Idx) 205 : HS(&HS), Idx(Idx) {} 206 207 /// Only HeaderSearch is allowed to instantiate valid iterators. 208 friend HeaderSearch; 209 210 /// Enables const -> non-const conversion. 211 friend SearchDirIteratorImpl<!IsConst>; 212 }; 213 } // namespace detail 214 215 using ConstSearchDirIterator = detail::SearchDirIteratorImpl<true>; 216 using SearchDirIterator = detail::SearchDirIteratorImpl<false>; 217 218 using ConstSearchDirRange = llvm::iterator_range<ConstSearchDirIterator>; 219 using SearchDirRange = llvm::iterator_range<SearchDirIterator>; 220 221 /// Encapsulates the information needed to find the file referenced 222 /// by a \#include or \#include_next, (sub-)framework lookup, etc. 223 class HeaderSearch { 224 friend class DirectoryLookup; 225 226 friend ConstSearchDirIterator; 227 friend SearchDirIterator; 228 229 /// Header-search options used to initialize this header search. 230 std::shared_ptr<HeaderSearchOptions> HSOpts; 231 232 /// Mapping from SearchDir to HeaderSearchOptions::UserEntries indices. 233 llvm::DenseMap<unsigned, unsigned> SearchDirToHSEntry; 234 235 DiagnosticsEngine &Diags; 236 FileManager &FileMgr; 237 238 /// \#include search path information. Requests for \#include "x" search the 239 /// directory of the \#including file first, then each directory in SearchDirs 240 /// consecutively. Requests for <x> search the current dir first, then each 241 /// directory in SearchDirs, starting at AngledDirIdx, consecutively. If 242 /// NoCurDirSearch is true, then the check for the file in the current 243 /// directory is suppressed. 244 std::vector<DirectoryLookup> SearchDirs; 245 /// Whether the DirectoryLookup at the corresponding index in SearchDirs has 246 /// been successfully used to lookup a file. 247 std::vector<bool> SearchDirsUsage; 248 unsigned AngledDirIdx = 0; 249 unsigned SystemDirIdx = 0; 250 bool NoCurDirSearch = false; 251 252 /// \#include prefixes for which the 'system header' property is 253 /// overridden. 254 /// 255 /// For a \#include "x" or \#include \<x> directive, the last string in this 256 /// list which is a prefix of 'x' determines whether the file is treated as 257 /// a system header. 258 std::vector<std::pair<std::string, bool>> SystemHeaderPrefixes; 259 260 /// The hash used for module cache paths. 261 std::string ModuleHash; 262 263 /// The path to the module cache. 264 std::string ModuleCachePath; 265 266 /// All of the preprocessor-specific data about files that are 267 /// included, indexed by the FileEntry's UID. 268 mutable std::vector<HeaderFileInfo> FileInfo; 269 270 /// Keeps track of each lookup performed by LookupFile. 271 struct LookupFileCacheInfo { 272 /// Starting search directory iterator that the cached search was performed 273 /// from. If there is a hit and this value doesn't match the current query, 274 /// the cache has to be ignored. 275 ConstSearchDirIterator StartIt = nullptr; 276 277 /// The search directory iterator that satisfied the query. 278 ConstSearchDirIterator HitIt = nullptr; 279 280 /// This is non-null if the original filename was mapped to a framework 281 /// include via a headermap. 282 const char *MappedName = nullptr; 283 284 /// Default constructor -- Initialize all members with zero. 285 LookupFileCacheInfo() = default; 286 287 void reset(ConstSearchDirIterator NewStartIt) { 288 StartIt = NewStartIt; 289 MappedName = nullptr; 290 } 291 }; 292 llvm::StringMap<LookupFileCacheInfo, llvm::BumpPtrAllocator> LookupFileCache; 293 294 /// Collection mapping a framework or subframework 295 /// name like "Carbon" to the Carbon.framework directory. 296 llvm::StringMap<FrameworkCacheEntry, llvm::BumpPtrAllocator> FrameworkMap; 297 298 /// Maps include file names (including the quotes or 299 /// angle brackets) to other include file names. This is used to support the 300 /// include_alias pragma for Microsoft compatibility. 301 using IncludeAliasMap = 302 llvm::StringMap<std::string, llvm::BumpPtrAllocator>; 303 std::unique_ptr<IncludeAliasMap> IncludeAliases; 304 305 /// This is a mapping from FileEntry -> HeaderMap, uniquing headermaps. 306 std::vector<std::pair<const FileEntry *, std::unique_ptr<HeaderMap>>> HeaderMaps; 307 308 /// The mapping between modules and headers. 309 mutable ModuleMap ModMap; 310 311 /// Describes whether a given directory has a module map in it. 312 llvm::DenseMap<const DirectoryEntry *, bool> DirectoryHasModuleMap; 313 314 /// Set of module map files we've already loaded, and a flag indicating 315 /// whether they were valid or not. 316 llvm::DenseMap<const FileEntry *, bool> LoadedModuleMaps; 317 318 // A map of discovered headers with their associated include file name. 319 llvm::DenseMap<const FileEntry *, llvm::SmallString<64>> IncludeNames; 320 321 /// Uniqued set of framework names, which is used to track which 322 /// headers were included as framework headers. 323 llvm::StringSet<llvm::BumpPtrAllocator> FrameworkNames; 324 325 /// Entity used to resolve the identifier IDs of controlling 326 /// macros into IdentifierInfo pointers, and keep the identifire up to date, 327 /// as needed. 328 ExternalPreprocessorSource *ExternalLookup = nullptr; 329 330 /// Entity used to look up stored header file information. 331 ExternalHeaderFileInfoSource *ExternalSource = nullptr; 332 333 public: 334 HeaderSearch(std::shared_ptr<HeaderSearchOptions> HSOpts, 335 SourceManager &SourceMgr, DiagnosticsEngine &Diags, 336 const LangOptions &LangOpts, const TargetInfo *Target); 337 HeaderSearch(const HeaderSearch &) = delete; 338 HeaderSearch &operator=(const HeaderSearch &) = delete; 339 340 /// Retrieve the header-search options with which this header search 341 /// was initialized. 342 HeaderSearchOptions &getHeaderSearchOpts() const { return *HSOpts; } 343 344 FileManager &getFileMgr() const { return FileMgr; } 345 346 DiagnosticsEngine &getDiags() const { return Diags; } 347 348 /// Interface for setting the file search paths. 349 void SetSearchPaths(std::vector<DirectoryLookup> dirs, unsigned angledDirIdx, 350 unsigned systemDirIdx, bool noCurDirSearch, 351 llvm::DenseMap<unsigned, unsigned> searchDirToHSEntry); 352 353 /// Add an additional search path. 354 void AddSearchPath(const DirectoryLookup &dir, bool isAngled); 355 356 /// Add an additional system search path. 357 void AddSystemSearchPath(const DirectoryLookup &dir) { 358 SearchDirs.push_back(dir); 359 SearchDirsUsage.push_back(false); 360 } 361 362 /// Set the list of system header prefixes. 363 void SetSystemHeaderPrefixes(ArrayRef<std::pair<std::string, bool>> P) { 364 SystemHeaderPrefixes.assign(P.begin(), P.end()); 365 } 366 367 /// Checks whether the map exists or not. 368 bool HasIncludeAliasMap() const { return (bool)IncludeAliases; } 369 370 /// Map the source include name to the dest include name. 371 /// 372 /// The Source should include the angle brackets or quotes, the dest 373 /// should not. This allows for distinction between <> and "" headers. 374 void AddIncludeAlias(StringRef Source, StringRef Dest) { 375 if (!IncludeAliases) 376 IncludeAliases.reset(new IncludeAliasMap); 377 (*IncludeAliases)[Source] = std::string(Dest); 378 } 379 380 /// Maps one header file name to a different header 381 /// file name, for use with the include_alias pragma. Note that the source 382 /// file name should include the angle brackets or quotes. Returns StringRef 383 /// as null if the header cannot be mapped. 384 StringRef MapHeaderToIncludeAlias(StringRef Source) { 385 assert(IncludeAliases && "Trying to map headers when there's no map"); 386 387 // Do any filename replacements before anything else 388 IncludeAliasMap::const_iterator Iter = IncludeAliases->find(Source); 389 if (Iter != IncludeAliases->end()) 390 return Iter->second; 391 return {}; 392 } 393 394 /// Set the hash to use for module cache paths. 395 void setModuleHash(StringRef Hash) { ModuleHash = std::string(Hash); } 396 397 /// Set the path to the module cache. 398 void setModuleCachePath(StringRef CachePath) { 399 ModuleCachePath = std::string(CachePath); 400 } 401 402 /// Retrieve the module hash. 403 StringRef getModuleHash() const { return ModuleHash; } 404 405 /// Retrieve the path to the module cache. 406 StringRef getModuleCachePath() const { return ModuleCachePath; } 407 408 /// Consider modules when including files from this directory. 409 void setDirectoryHasModuleMap(const DirectoryEntry* Dir) { 410 DirectoryHasModuleMap[Dir] = true; 411 } 412 413 /// Forget everything we know about headers so far. 414 void ClearFileInfo() { 415 FileInfo.clear(); 416 } 417 418 void SetExternalLookup(ExternalPreprocessorSource *EPS) { 419 ExternalLookup = EPS; 420 } 421 422 ExternalPreprocessorSource *getExternalLookup() const { 423 return ExternalLookup; 424 } 425 426 /// Set the external source of header information. 427 void SetExternalSource(ExternalHeaderFileInfoSource *ES) { 428 ExternalSource = ES; 429 } 430 431 /// Set the target information for the header search, if not 432 /// already known. 433 void setTarget(const TargetInfo &Target); 434 435 /// Given a "foo" or \<foo> reference, look up the indicated file, 436 /// return null on failure. 437 /// 438 /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member 439 /// the file was found in, or null if not applicable. 440 /// 441 /// \param IncludeLoc Used for diagnostics if valid. 442 /// 443 /// \param isAngled indicates whether the file reference is a <> reference. 444 /// 445 /// \param CurDir If non-null, the file was found in the specified directory 446 /// search location. This is used to implement \#include_next. 447 /// 448 /// \param Includers Indicates where the \#including file(s) are, in case 449 /// relative searches are needed. In reverse order of inclusion. 450 /// 451 /// \param SearchPath If non-null, will be set to the search path relative 452 /// to which the file was found. If the include path is absolute, SearchPath 453 /// will be set to an empty string. 454 /// 455 /// \param RelativePath If non-null, will be set to the path relative to 456 /// SearchPath at which the file was found. This only differs from the 457 /// Filename for framework includes. 458 /// 459 /// \param SuggestedModule If non-null, and the file found is semantically 460 /// part of a known module, this will be set to the module that should 461 /// be imported instead of preprocessing/parsing the file found. 462 /// 463 /// \param IsMapped If non-null, and the search involved header maps, set to 464 /// true. 465 /// 466 /// \param IsFrameworkFound If non-null, will be set to true if a framework is 467 /// found in any of searched SearchDirs. Will be set to false if a framework 468 /// is found only through header maps. Doesn't guarantee the requested file is 469 /// found. 470 Optional<FileEntryRef> LookupFile( 471 StringRef Filename, SourceLocation IncludeLoc, bool isAngled, 472 ConstSearchDirIterator FromDir, ConstSearchDirIterator *CurDir, 473 ArrayRef<std::pair<const FileEntry *, const DirectoryEntry *>> Includers, 474 SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath, 475 Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule, 476 bool *IsMapped, bool *IsFrameworkFound, bool SkipCache = false, 477 bool BuildSystemModule = false); 478 479 /// Look up a subframework for the specified \#include file. 480 /// 481 /// For example, if \#include'ing <HIToolbox/HIToolbox.h> from 482 /// within ".../Carbon.framework/Headers/Carbon.h", check to see if 483 /// HIToolbox is a subframework within Carbon.framework. If so, return 484 /// the FileEntry for the designated file, otherwise return null. 485 Optional<FileEntryRef> LookupSubframeworkHeader( 486 StringRef Filename, const FileEntry *ContextFileEnt, 487 SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath, 488 Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule); 489 490 /// Look up the specified framework name in our framework cache. 491 /// \returns The DirectoryEntry it is in if we know, null otherwise. 492 FrameworkCacheEntry &LookupFrameworkCache(StringRef FWName) { 493 return FrameworkMap[FWName]; 494 } 495 496 /// Mark the specified file as a target of a \#include, 497 /// \#include_next, or \#import directive. 498 /// 499 /// \return false if \#including the file will have no effect or true 500 /// if we should include it. 501 bool ShouldEnterIncludeFile(Preprocessor &PP, const FileEntry *File, 502 bool isImport, bool ModulesEnabled, Module *M, 503 bool &IsFirstIncludeOfFile); 504 505 /// Return whether the specified file is a normal header, 506 /// a system header, or a C++ friendly system header. 507 SrcMgr::CharacteristicKind getFileDirFlavor(const FileEntry *File) { 508 return (SrcMgr::CharacteristicKind)getFileInfo(File).DirInfo; 509 } 510 511 /// Mark the specified file as a "once only" file due to 512 /// \#pragma once. 513 void MarkFileIncludeOnce(const FileEntry *File) { 514 HeaderFileInfo &FI = getFileInfo(File); 515 FI.isPragmaOnce = true; 516 } 517 518 /// Mark the specified file as a system header, e.g. due to 519 /// \#pragma GCC system_header. 520 void MarkFileSystemHeader(const FileEntry *File) { 521 getFileInfo(File).DirInfo = SrcMgr::C_System; 522 } 523 524 /// Mark the specified file as part of a module. 525 void MarkFileModuleHeader(const FileEntry *FE, 526 ModuleMap::ModuleHeaderRole Role, 527 bool isCompilingModuleHeader); 528 529 /// Mark the specified file as having a controlling macro. 530 /// 531 /// This is used by the multiple-include optimization to eliminate 532 /// no-op \#includes. 533 void SetFileControllingMacro(const FileEntry *File, 534 const IdentifierInfo *ControllingMacro) { 535 getFileInfo(File).ControllingMacro = ControllingMacro; 536 } 537 538 /// Determine whether this file is intended to be safe from 539 /// multiple inclusions, e.g., it has \#pragma once or a controlling 540 /// macro. 541 /// 542 /// This routine does not consider the effect of \#import 543 bool isFileMultipleIncludeGuarded(const FileEntry *File); 544 545 /// Determine whether the given file is known to have ever been \#imported. 546 bool hasFileBeenImported(const FileEntry *File) { 547 const HeaderFileInfo *FI = getExistingFileInfo(File); 548 return FI && FI->isImport; 549 } 550 551 /// Determine which HeaderSearchOptions::UserEntries have been successfully 552 /// used so far and mark their index with 'true' in the resulting bit vector. 553 /// Note: implicit module maps don't contribute to entry usage. 554 std::vector<bool> computeUserEntryUsage() const; 555 556 /// This method returns a HeaderMap for the specified 557 /// FileEntry, uniquing them through the 'HeaderMaps' datastructure. 558 const HeaderMap *CreateHeaderMap(const FileEntry *FE); 559 560 /// Get filenames for all registered header maps. 561 void getHeaderMapFileNames(SmallVectorImpl<std::string> &Names) const; 562 563 /// Retrieve the name of the cached module file that should be used 564 /// to load the given module. 565 /// 566 /// \param Module The module whose module file name will be returned. 567 /// 568 /// \returns The name of the module file that corresponds to this module, 569 /// or an empty string if this module does not correspond to any module file. 570 std::string getCachedModuleFileName(Module *Module); 571 572 /// Retrieve the name of the prebuilt module file that should be used 573 /// to load a module with the given name. 574 /// 575 /// \param ModuleName The module whose module file name will be returned. 576 /// 577 /// \param FileMapOnly If true, then only look in the explicit module name 578 // to file name map and skip the directory search. 579 /// 580 /// \returns The name of the module file that corresponds to this module, 581 /// or an empty string if this module does not correspond to any module file. 582 std::string getPrebuiltModuleFileName(StringRef ModuleName, 583 bool FileMapOnly = false); 584 585 /// Retrieve the name of the prebuilt module file that should be used 586 /// to load the given module. 587 /// 588 /// \param Module The module whose module file name will be returned. 589 /// 590 /// \returns The name of the module file that corresponds to this module, 591 /// or an empty string if this module does not correspond to any module file. 592 std::string getPrebuiltImplicitModuleFileName(Module *Module); 593 594 /// Retrieve the name of the (to-be-)cached module file that should 595 /// be used to load a module with the given name. 596 /// 597 /// \param ModuleName The module whose module file name will be returned. 598 /// 599 /// \param ModuleMapPath A path that when combined with \c ModuleName 600 /// uniquely identifies this module. See Module::ModuleMap. 601 /// 602 /// \returns The name of the module file that corresponds to this module, 603 /// or an empty string if this module does not correspond to any module file. 604 std::string getCachedModuleFileName(StringRef ModuleName, 605 StringRef ModuleMapPath); 606 607 /// Lookup a module Search for a module with the given name. 608 /// 609 /// \param ModuleName The name of the module we're looking for. 610 /// 611 /// \param ImportLoc Location of the module include/import. 612 /// 613 /// \param AllowSearch Whether we are allowed to search in the various 614 /// search directories to produce a module definition. If not, this lookup 615 /// will only return an already-known module. 616 /// 617 /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps 618 /// in subdirectories. 619 /// 620 /// \returns The module with the given name. 621 Module *lookupModule(StringRef ModuleName, 622 SourceLocation ImportLoc = SourceLocation(), 623 bool AllowSearch = true, 624 bool AllowExtraModuleMapSearch = false); 625 626 /// Try to find a module map file in the given directory, returning 627 /// \c nullptr if none is found. 628 const FileEntry *lookupModuleMapFile(const DirectoryEntry *Dir, 629 bool IsFramework); 630 631 /// Determine whether there is a module map that may map the header 632 /// with the given file name to a (sub)module. 633 /// Always returns false if modules are disabled. 634 /// 635 /// \param Filename The name of the file. 636 /// 637 /// \param Root The "root" directory, at which we should stop looking for 638 /// module maps. 639 /// 640 /// \param IsSystem Whether the directories we're looking at are system 641 /// header directories. 642 bool hasModuleMap(StringRef Filename, const DirectoryEntry *Root, 643 bool IsSystem); 644 645 /// Retrieve the module that corresponds to the given file, if any. 646 /// 647 /// \param File The header that we wish to map to a module. 648 /// \param AllowTextual Whether we want to find textual headers too. 649 ModuleMap::KnownHeader findModuleForHeader(const FileEntry *File, 650 bool AllowTextual = false) const; 651 652 /// Retrieve all the modules corresponding to the given file. 653 /// 654 /// \ref findModuleForHeader should typically be used instead of this. 655 ArrayRef<ModuleMap::KnownHeader> 656 findAllModulesForHeader(const FileEntry *File) const; 657 658 /// Read the contents of the given module map file. 659 /// 660 /// \param File The module map file. 661 /// \param IsSystem Whether this file is in a system header directory. 662 /// \param ID If the module map file is already mapped (perhaps as part of 663 /// processing a preprocessed module), the ID of the file. 664 /// \param Offset [inout] An offset within ID to start parsing. On exit, 665 /// filled by the end of the parsed contents (either EOF or the 666 /// location of an end-of-module-map pragma). 667 /// \param OriginalModuleMapFile The original path to the module map file, 668 /// used to resolve paths within the module (this is required when 669 /// building the module from preprocessed source). 670 /// \returns true if an error occurred, false otherwise. 671 bool loadModuleMapFile(const FileEntry *File, bool IsSystem, 672 FileID ID = FileID(), unsigned *Offset = nullptr, 673 StringRef OriginalModuleMapFile = StringRef()); 674 675 /// Collect the set of all known, top-level modules. 676 /// 677 /// \param Modules Will be filled with the set of known, top-level modules. 678 void collectAllModules(SmallVectorImpl<Module *> &Modules); 679 680 /// Load all known, top-level system modules. 681 void loadTopLevelSystemModules(); 682 683 private: 684 /// Lookup a module with the given module name and search-name. 685 /// 686 /// \param ModuleName The name of the module we're looking for. 687 /// 688 /// \param SearchName The "search-name" to derive filesystem paths from 689 /// when looking for the module map; this is usually equal to ModuleName, 690 /// but for compatibility with some buggy frameworks, additional attempts 691 /// may be made to find the module under a related-but-different search-name. 692 /// 693 /// \param ImportLoc Location of the module include/import. 694 /// 695 /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps 696 /// in subdirectories. 697 /// 698 /// \returns The module named ModuleName. 699 Module *lookupModule(StringRef ModuleName, StringRef SearchName, 700 SourceLocation ImportLoc, 701 bool AllowExtraModuleMapSearch = false); 702 703 /// Retrieve the name of the (to-be-)cached module file that should 704 /// be used to load a module with the given name. 705 /// 706 /// \param ModuleName The module whose module file name will be returned. 707 /// 708 /// \param ModuleMapPath A path that when combined with \c ModuleName 709 /// uniquely identifies this module. See Module::ModuleMap. 710 /// 711 /// \param CachePath A path to the module cache. 712 /// 713 /// \returns The name of the module file that corresponds to this module, 714 /// or an empty string if this module does not correspond to any module file. 715 std::string getCachedModuleFileNameImpl(StringRef ModuleName, 716 StringRef ModuleMapPath, 717 StringRef CachePath); 718 719 /// Retrieve a module with the given name, which may be part of the 720 /// given framework. 721 /// 722 /// \param Name The name of the module to retrieve. 723 /// 724 /// \param Dir The framework directory (e.g., ModuleName.framework). 725 /// 726 /// \param IsSystem Whether the framework directory is part of the system 727 /// frameworks. 728 /// 729 /// \returns The module, if found; otherwise, null. 730 Module *loadFrameworkModule(StringRef Name, DirectoryEntryRef Dir, 731 bool IsSystem); 732 733 /// Load all of the module maps within the immediate subdirectories 734 /// of the given search directory. 735 void loadSubdirectoryModuleMaps(DirectoryLookup &SearchDir); 736 737 /// Find and suggest a usable module for the given file. 738 /// 739 /// \return \c true if the file can be used, \c false if we are not permitted to 740 /// find this file due to requirements from \p RequestingModule. 741 bool findUsableModuleForHeader(const FileEntry *File, 742 const DirectoryEntry *Root, 743 Module *RequestingModule, 744 ModuleMap::KnownHeader *SuggestedModule, 745 bool IsSystemHeaderDir); 746 747 /// Find and suggest a usable module for the given file, which is part of 748 /// the specified framework. 749 /// 750 /// \return \c true if the file can be used, \c false if we are not permitted to 751 /// find this file due to requirements from \p RequestingModule. 752 bool findUsableModuleForFrameworkHeader( 753 const FileEntry *File, StringRef FrameworkName, Module *RequestingModule, 754 ModuleMap::KnownHeader *SuggestedModule, bool IsSystemFramework); 755 756 /// Look up the file with the specified name and determine its owning 757 /// module. 758 Optional<FileEntryRef> 759 getFileAndSuggestModule(StringRef FileName, SourceLocation IncludeLoc, 760 const DirectoryEntry *Dir, bool IsSystemHeaderDir, 761 Module *RequestingModule, 762 ModuleMap::KnownHeader *SuggestedModule); 763 764 /// Cache the result of a successful lookup at the given include location 765 /// using the search path at \c HitIt. 766 void cacheLookupSuccess(LookupFileCacheInfo &CacheLookup, 767 ConstSearchDirIterator HitIt, 768 SourceLocation IncludeLoc); 769 770 /// Note that a lookup at the given include location was successful using the 771 /// search path at index `HitIdx`. 772 void noteLookupUsage(unsigned HitIdx, SourceLocation IncludeLoc); 773 774 public: 775 /// Retrieve the module map. 776 ModuleMap &getModuleMap() { return ModMap; } 777 778 /// Retrieve the module map. 779 const ModuleMap &getModuleMap() const { return ModMap; } 780 781 unsigned header_file_size() const { return FileInfo.size(); } 782 783 /// Return the HeaderFileInfo structure for the specified FileEntry, 784 /// in preparation for updating it in some way. 785 HeaderFileInfo &getFileInfo(const FileEntry *FE); 786 787 /// Return the HeaderFileInfo structure for the specified FileEntry, 788 /// if it has ever been filled in. 789 /// \param WantExternal Whether the caller wants purely-external header file 790 /// info (where \p External is true). 791 const HeaderFileInfo *getExistingFileInfo(const FileEntry *FE, 792 bool WantExternal = true) const; 793 794 SearchDirIterator search_dir_begin() { return {*this, 0}; } 795 SearchDirIterator search_dir_end() { return {*this, SearchDirs.size()}; } 796 SearchDirRange search_dir_range() { 797 return {search_dir_begin(), search_dir_end()}; 798 } 799 800 ConstSearchDirIterator search_dir_begin() const { return quoted_dir_begin(); } 801 ConstSearchDirIterator search_dir_end() const { return system_dir_end(); } 802 ConstSearchDirRange search_dir_range() const { 803 return {search_dir_begin(), search_dir_end()}; 804 } 805 806 unsigned search_dir_size() const { return SearchDirs.size(); } 807 808 ConstSearchDirIterator quoted_dir_begin() const { return {*this, 0}; } 809 ConstSearchDirIterator quoted_dir_end() const { return angled_dir_begin(); } 810 811 ConstSearchDirIterator angled_dir_begin() const { 812 return {*this, AngledDirIdx}; 813 } 814 ConstSearchDirIterator angled_dir_end() const { return system_dir_begin(); } 815 816 ConstSearchDirIterator system_dir_begin() const { 817 return {*this, SystemDirIdx}; 818 } 819 ConstSearchDirIterator system_dir_end() const { 820 return {*this, SearchDirs.size()}; 821 } 822 823 /// Get the index of the given search directory. 824 unsigned searchDirIdx(const DirectoryLookup &DL) const; 825 826 /// Retrieve a uniqued framework name. 827 StringRef getUniqueFrameworkName(StringRef Framework); 828 829 /// Retrieve the include name for the header. 830 /// 831 /// \param File The entry for a given header. 832 /// \returns The name of how the file was included when the header's location 833 /// was resolved. 834 StringRef getIncludeNameForHeader(const FileEntry *File) const; 835 836 /// Suggest a path by which the specified file could be found, for use in 837 /// diagnostics to suggest a #include. Returned path will only contain forward 838 /// slashes as separators. MainFile is the absolute path of the file that we 839 /// are generating the diagnostics for. It will try to shorten the path using 840 /// MainFile location, if none of the include search directories were prefix 841 /// of File. 842 /// 843 /// \param IsSystem If non-null, filled in to indicate whether the suggested 844 /// path is relative to a system header directory. 845 std::string suggestPathToFileForDiagnostics(const FileEntry *File, 846 llvm::StringRef MainFile, 847 bool *IsSystem = nullptr); 848 849 /// Suggest a path by which the specified file could be found, for use in 850 /// diagnostics to suggest a #include. Returned path will only contain forward 851 /// slashes as separators. MainFile is the absolute path of the file that we 852 /// are generating the diagnostics for. It will try to shorten the path using 853 /// MainFile location, if none of the include search directories were prefix 854 /// of File. 855 /// 856 /// \param WorkingDir If non-empty, this will be prepended to search directory 857 /// paths that are relative. 858 std::string suggestPathToFileForDiagnostics(llvm::StringRef File, 859 llvm::StringRef WorkingDir, 860 llvm::StringRef MainFile, 861 bool *IsSystem = nullptr); 862 863 void PrintStats(); 864 865 size_t getTotalMemory() const; 866 867 private: 868 /// Describes what happened when we tried to load a module map file. 869 enum LoadModuleMapResult { 870 /// The module map file had already been loaded. 871 LMM_AlreadyLoaded, 872 873 /// The module map file was loaded by this invocation. 874 LMM_NewlyLoaded, 875 876 /// There is was directory with the given name. 877 LMM_NoDirectory, 878 879 /// There was either no module map file or the module map file was 880 /// invalid. 881 LMM_InvalidModuleMap 882 }; 883 884 LoadModuleMapResult loadModuleMapFileImpl(const FileEntry *File, 885 bool IsSystem, 886 DirectoryEntryRef Dir, 887 FileID ID = FileID(), 888 unsigned *Offset = nullptr); 889 890 /// Try to load the module map file in the given directory. 891 /// 892 /// \param DirName The name of the directory where we will look for a module 893 /// map file. 894 /// \param IsSystem Whether this is a system header directory. 895 /// \param IsFramework Whether this is a framework directory. 896 /// 897 /// \returns The result of attempting to load the module map file from the 898 /// named directory. 899 LoadModuleMapResult loadModuleMapFile(StringRef DirName, bool IsSystem, 900 bool IsFramework); 901 902 /// Try to load the module map file in the given directory. 903 /// 904 /// \param Dir The directory where we will look for a module map file. 905 /// \param IsSystem Whether this is a system header directory. 906 /// \param IsFramework Whether this is a framework directory. 907 /// 908 /// \returns The result of attempting to load the module map file from the 909 /// named directory. 910 LoadModuleMapResult loadModuleMapFile(DirectoryEntryRef Dir, bool IsSystem, 911 bool IsFramework); 912 }; 913 914 /// Apply the header search options to get given HeaderSearch object. 915 void ApplyHeaderSearchOptions(HeaderSearch &HS, 916 const HeaderSearchOptions &HSOpts, 917 const LangOptions &Lang, 918 const llvm::Triple &triple); 919 920 } // namespace clang 921 922 #endif // LLVM_CLANG_LEX_HEADERSEARCH_H 923