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 OptionalDirectoryEntryRef 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 /// Maps HeaderMap keys to SearchDir indices. When HeaderMaps are used 253 /// heavily, SearchDirs can start with thousands of HeaderMaps, so this Index 254 /// lets us avoid scanning them all to find a match. 255 llvm::StringMap<unsigned, llvm::BumpPtrAllocator> SearchDirHeaderMapIndex; 256 257 /// The index of the first SearchDir that isn't a header map. 258 unsigned FirstNonHeaderMapSearchDirIdx = 0; 259 260 /// \#include prefixes for which the 'system header' property is 261 /// overridden. 262 /// 263 /// For a \#include "x" or \#include \<x> directive, the last string in this 264 /// list which is a prefix of 'x' determines whether the file is treated as 265 /// a system header. 266 std::vector<std::pair<std::string, bool>> SystemHeaderPrefixes; 267 268 /// The hash used for module cache paths. 269 std::string ModuleHash; 270 271 /// The path to the module cache. 272 std::string ModuleCachePath; 273 274 /// All of the preprocessor-specific data about files that are 275 /// included, indexed by the FileEntry's UID. 276 mutable std::vector<HeaderFileInfo> FileInfo; 277 278 /// Keeps track of each lookup performed by LookupFile. 279 struct LookupFileCacheInfo { 280 // The requesting module for the lookup we cached. 281 const Module *RequestingModule = nullptr; 282 283 /// Starting search directory iterator that the cached search was performed 284 /// from. If there is a hit and this value doesn't match the current query, 285 /// the cache has to be ignored. 286 ConstSearchDirIterator StartIt = nullptr; 287 288 /// The search directory iterator that satisfied the query. 289 ConstSearchDirIterator HitIt = nullptr; 290 291 /// This is non-null if the original filename was mapped to a framework 292 /// include via a headermap. 293 const char *MappedName = nullptr; 294 295 /// Default constructor -- Initialize all members with zero. 296 LookupFileCacheInfo() = default; 297 298 void reset(const Module *NewRequestingModule, 299 ConstSearchDirIterator NewStartIt) { 300 RequestingModule = NewRequestingModule; 301 StartIt = NewStartIt; 302 MappedName = nullptr; 303 } 304 }; 305 llvm::StringMap<LookupFileCacheInfo, llvm::BumpPtrAllocator> LookupFileCache; 306 307 /// Collection mapping a framework or subframework 308 /// name like "Carbon" to the Carbon.framework directory. 309 llvm::StringMap<FrameworkCacheEntry, llvm::BumpPtrAllocator> FrameworkMap; 310 311 /// Maps include file names (including the quotes or 312 /// angle brackets) to other include file names. This is used to support the 313 /// include_alias pragma for Microsoft compatibility. 314 using IncludeAliasMap = 315 llvm::StringMap<std::string, llvm::BumpPtrAllocator>; 316 std::unique_ptr<IncludeAliasMap> IncludeAliases; 317 318 /// This is a mapping from FileEntry -> HeaderMap, uniquing headermaps. 319 std::vector<std::pair<const FileEntry *, std::unique_ptr<HeaderMap>>> HeaderMaps; 320 321 /// The mapping between modules and headers. 322 mutable ModuleMap ModMap; 323 324 /// Describes whether a given directory has a module map in it. 325 llvm::DenseMap<const DirectoryEntry *, bool> DirectoryHasModuleMap; 326 327 /// Set of module map files we've already loaded, and a flag indicating 328 /// whether they were valid or not. 329 llvm::DenseMap<const FileEntry *, bool> LoadedModuleMaps; 330 331 // A map of discovered headers with their associated include file name. 332 llvm::DenseMap<const FileEntry *, llvm::SmallString<64>> IncludeNames; 333 334 /// Uniqued set of framework names, which is used to track which 335 /// headers were included as framework headers. 336 llvm::StringSet<llvm::BumpPtrAllocator> FrameworkNames; 337 338 /// Entity used to resolve the identifier IDs of controlling 339 /// macros into IdentifierInfo pointers, and keep the identifire up to date, 340 /// as needed. 341 ExternalPreprocessorSource *ExternalLookup = nullptr; 342 343 /// Entity used to look up stored header file information. 344 ExternalHeaderFileInfoSource *ExternalSource = nullptr; 345 346 /// Scan all of the header maps at the beginning of SearchDirs and 347 /// map their keys to the SearchDir index of their header map. 348 void indexInitialHeaderMaps(); 349 350 public: 351 HeaderSearch(std::shared_ptr<HeaderSearchOptions> HSOpts, 352 SourceManager &SourceMgr, DiagnosticsEngine &Diags, 353 const LangOptions &LangOpts, const TargetInfo *Target); 354 HeaderSearch(const HeaderSearch &) = delete; 355 HeaderSearch &operator=(const HeaderSearch &) = delete; 356 357 /// Retrieve the header-search options with which this header search 358 /// was initialized. 359 HeaderSearchOptions &getHeaderSearchOpts() const { return *HSOpts; } 360 361 FileManager &getFileMgr() const { return FileMgr; } 362 363 DiagnosticsEngine &getDiags() const { return Diags; } 364 365 /// Interface for setting the file search paths. 366 void SetSearchPaths(std::vector<DirectoryLookup> dirs, unsigned angledDirIdx, 367 unsigned systemDirIdx, bool noCurDirSearch, 368 llvm::DenseMap<unsigned, unsigned> searchDirToHSEntry); 369 370 /// Add an additional search path. 371 void AddSearchPath(const DirectoryLookup &dir, bool isAngled); 372 373 /// Add an additional system search path. 374 void AddSystemSearchPath(const DirectoryLookup &dir) { 375 SearchDirs.push_back(dir); 376 SearchDirsUsage.push_back(false); 377 } 378 379 /// Set the list of system header prefixes. 380 void SetSystemHeaderPrefixes(ArrayRef<std::pair<std::string, bool>> P) { 381 SystemHeaderPrefixes.assign(P.begin(), P.end()); 382 } 383 384 /// Checks whether the map exists or not. 385 bool HasIncludeAliasMap() const { return (bool)IncludeAliases; } 386 387 /// Map the source include name to the dest include name. 388 /// 389 /// The Source should include the angle brackets or quotes, the dest 390 /// should not. This allows for distinction between <> and "" headers. 391 void AddIncludeAlias(StringRef Source, StringRef Dest) { 392 if (!IncludeAliases) 393 IncludeAliases.reset(new IncludeAliasMap); 394 (*IncludeAliases)[Source] = std::string(Dest); 395 } 396 397 /// Maps one header file name to a different header 398 /// file name, for use with the include_alias pragma. Note that the source 399 /// file name should include the angle brackets or quotes. Returns StringRef 400 /// as null if the header cannot be mapped. 401 StringRef MapHeaderToIncludeAlias(StringRef Source) { 402 assert(IncludeAliases && "Trying to map headers when there's no map"); 403 404 // Do any filename replacements before anything else 405 IncludeAliasMap::const_iterator Iter = IncludeAliases->find(Source); 406 if (Iter != IncludeAliases->end()) 407 return Iter->second; 408 return {}; 409 } 410 411 /// Set the hash to use for module cache paths. 412 void setModuleHash(StringRef Hash) { ModuleHash = std::string(Hash); } 413 414 /// Set the path to the module cache. 415 void setModuleCachePath(StringRef CachePath) { 416 ModuleCachePath = std::string(CachePath); 417 } 418 419 /// Retrieve the module hash. 420 StringRef getModuleHash() const { return ModuleHash; } 421 422 /// Retrieve the path to the module cache. 423 StringRef getModuleCachePath() const { return ModuleCachePath; } 424 425 /// Consider modules when including files from this directory. 426 void setDirectoryHasModuleMap(const DirectoryEntry* Dir) { 427 DirectoryHasModuleMap[Dir] = true; 428 } 429 430 /// Forget everything we know about headers so far. 431 void ClearFileInfo() { 432 FileInfo.clear(); 433 } 434 435 void SetExternalLookup(ExternalPreprocessorSource *EPS) { 436 ExternalLookup = EPS; 437 } 438 439 ExternalPreprocessorSource *getExternalLookup() const { 440 return ExternalLookup; 441 } 442 443 /// Set the external source of header information. 444 void SetExternalSource(ExternalHeaderFileInfoSource *ES) { 445 ExternalSource = ES; 446 } 447 448 /// Set the target information for the header search, if not 449 /// already known. 450 void setTarget(const TargetInfo &Target); 451 452 /// Given a "foo" or \<foo> reference, look up the indicated file, 453 /// return null on failure. 454 /// 455 /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member 456 /// the file was found in, or null if not applicable. 457 /// 458 /// \param IncludeLoc Used for diagnostics if valid. 459 /// 460 /// \param isAngled indicates whether the file reference is a <> reference. 461 /// 462 /// \param CurDir If non-null, the file was found in the specified directory 463 /// search location. This is used to implement \#include_next. 464 /// 465 /// \param Includers Indicates where the \#including file(s) are, in case 466 /// relative searches are needed. In reverse order of inclusion. 467 /// 468 /// \param SearchPath If non-null, will be set to the search path relative 469 /// to which the file was found. If the include path is absolute, SearchPath 470 /// will be set to an empty string. 471 /// 472 /// \param RelativePath If non-null, will be set to the path relative to 473 /// SearchPath at which the file was found. This only differs from the 474 /// Filename for framework includes. 475 /// 476 /// \param SuggestedModule If non-null, and the file found is semantically 477 /// part of a known module, this will be set to the module that should 478 /// be imported instead of preprocessing/parsing the file found. 479 /// 480 /// \param IsMapped If non-null, and the search involved header maps, set to 481 /// true. 482 /// 483 /// \param IsFrameworkFound If non-null, will be set to true if a framework is 484 /// found in any of searched SearchDirs. Will be set to false if a framework 485 /// is found only through header maps. Doesn't guarantee the requested file is 486 /// found. 487 OptionalFileEntryRef LookupFile( 488 StringRef Filename, SourceLocation IncludeLoc, bool isAngled, 489 ConstSearchDirIterator FromDir, ConstSearchDirIterator *CurDir, 490 ArrayRef<std::pair<const FileEntry *, DirectoryEntryRef>> Includers, 491 SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath, 492 Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule, 493 bool *IsMapped, bool *IsFrameworkFound, bool SkipCache = false, 494 bool BuildSystemModule = false, bool OpenFile = true, 495 bool CacheFailures = true); 496 497 /// Look up a subframework for the specified \#include file. 498 /// 499 /// For example, if \#include'ing <HIToolbox/HIToolbox.h> from 500 /// within ".../Carbon.framework/Headers/Carbon.h", check to see if 501 /// HIToolbox is a subframework within Carbon.framework. If so, return 502 /// the FileEntry for the designated file, otherwise return null. 503 OptionalFileEntryRef LookupSubframeworkHeader( 504 StringRef Filename, const FileEntry *ContextFileEnt, 505 SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath, 506 Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule); 507 508 /// Look up the specified framework name in our framework cache. 509 /// \returns The DirectoryEntry it is in if we know, null otherwise. 510 FrameworkCacheEntry &LookupFrameworkCache(StringRef FWName) { 511 return FrameworkMap[FWName]; 512 } 513 514 /// Mark the specified file as a target of a \#include, 515 /// \#include_next, or \#import directive. 516 /// 517 /// \return false if \#including the file will have no effect or true 518 /// if we should include it. 519 bool ShouldEnterIncludeFile(Preprocessor &PP, const FileEntry *File, 520 bool isImport, bool ModulesEnabled, Module *M, 521 bool &IsFirstIncludeOfFile); 522 523 /// Return whether the specified file is a normal header, 524 /// a system header, or a C++ friendly system header. 525 SrcMgr::CharacteristicKind getFileDirFlavor(const FileEntry *File) { 526 return (SrcMgr::CharacteristicKind)getFileInfo(File).DirInfo; 527 } 528 529 /// Mark the specified file as a "once only" file due to 530 /// \#pragma once. 531 void MarkFileIncludeOnce(const FileEntry *File) { 532 HeaderFileInfo &FI = getFileInfo(File); 533 FI.isPragmaOnce = true; 534 } 535 536 /// Mark the specified file as a system header, e.g. due to 537 /// \#pragma GCC system_header. 538 void MarkFileSystemHeader(const FileEntry *File) { 539 getFileInfo(File).DirInfo = SrcMgr::C_System; 540 } 541 542 /// Mark the specified file as part of a module. 543 void MarkFileModuleHeader(const FileEntry *FE, 544 ModuleMap::ModuleHeaderRole Role, 545 bool isCompilingModuleHeader); 546 547 /// Mark the specified file as having a controlling macro. 548 /// 549 /// This is used by the multiple-include optimization to eliminate 550 /// no-op \#includes. 551 void SetFileControllingMacro(const FileEntry *File, 552 const IdentifierInfo *ControllingMacro) { 553 getFileInfo(File).ControllingMacro = ControllingMacro; 554 } 555 556 /// Determine whether this file is intended to be safe from 557 /// multiple inclusions, e.g., it has \#pragma once or a controlling 558 /// macro. 559 /// 560 /// This routine does not consider the effect of \#import 561 bool isFileMultipleIncludeGuarded(const FileEntry *File) const; 562 563 /// Determine whether the given file is known to have ever been \#imported. 564 bool hasFileBeenImported(const FileEntry *File) const { 565 const HeaderFileInfo *FI = getExistingFileInfo(File); 566 return FI && FI->isImport; 567 } 568 569 /// Determine which HeaderSearchOptions::UserEntries have been successfully 570 /// used so far and mark their index with 'true' in the resulting bit vector. 571 /// Note: implicit module maps don't contribute to entry usage. 572 std::vector<bool> computeUserEntryUsage() const; 573 574 /// This method returns a HeaderMap for the specified 575 /// FileEntry, uniquing them through the 'HeaderMaps' datastructure. 576 const HeaderMap *CreateHeaderMap(const FileEntry *FE); 577 578 /// Get filenames for all registered header maps. 579 void getHeaderMapFileNames(SmallVectorImpl<std::string> &Names) const; 580 581 /// Retrieve the name of the cached module file that should be used 582 /// to load the given module. 583 /// 584 /// \param Module The module whose module file name will be returned. 585 /// 586 /// \returns The name of the module file that corresponds to this module, 587 /// or an empty string if this module does not correspond to any module file. 588 std::string getCachedModuleFileName(Module *Module); 589 590 /// Retrieve the name of the prebuilt module file that should be used 591 /// to load a module with the given name. 592 /// 593 /// \param ModuleName The module whose module file name will be returned. 594 /// 595 /// \param FileMapOnly If true, then only look in the explicit module name 596 // to file name map and skip the directory search. 597 /// 598 /// \returns The name of the module file that corresponds to this module, 599 /// or an empty string if this module does not correspond to any module file. 600 std::string getPrebuiltModuleFileName(StringRef ModuleName, 601 bool FileMapOnly = false); 602 603 /// Retrieve the name of the prebuilt module file that should be used 604 /// to load the given module. 605 /// 606 /// \param Module The module whose module file name will be returned. 607 /// 608 /// \returns The name of the module file that corresponds to this module, 609 /// or an empty string if this module does not correspond to any module file. 610 std::string getPrebuiltImplicitModuleFileName(Module *Module); 611 612 /// Retrieve the name of the (to-be-)cached module file that should 613 /// be used to load a module with the given name. 614 /// 615 /// \param ModuleName The module whose module file name will be returned. 616 /// 617 /// \param ModuleMapPath A path that when combined with \c ModuleName 618 /// uniquely identifies this module. See Module::ModuleMap. 619 /// 620 /// \returns The name of the module file that corresponds to this module, 621 /// or an empty string if this module does not correspond to any module file. 622 std::string getCachedModuleFileName(StringRef ModuleName, 623 StringRef ModuleMapPath); 624 625 /// Lookup a module Search for a module with the given name. 626 /// 627 /// \param ModuleName The name of the module we're looking for. 628 /// 629 /// \param ImportLoc Location of the module include/import. 630 /// 631 /// \param AllowSearch Whether we are allowed to search in the various 632 /// search directories to produce a module definition. If not, this lookup 633 /// will only return an already-known module. 634 /// 635 /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps 636 /// in subdirectories. 637 /// 638 /// \returns The module with the given name. 639 Module *lookupModule(StringRef ModuleName, 640 SourceLocation ImportLoc = SourceLocation(), 641 bool AllowSearch = true, 642 bool AllowExtraModuleMapSearch = false); 643 644 /// Try to find a module map file in the given directory, returning 645 /// \c nullopt if none is found. 646 OptionalFileEntryRef lookupModuleMapFile(DirectoryEntryRef Dir, 647 bool IsFramework); 648 649 /// Determine whether there is a module map that may map the header 650 /// with the given file name to a (sub)module. 651 /// Always returns false if modules are disabled. 652 /// 653 /// \param Filename The name of the file. 654 /// 655 /// \param Root The "root" directory, at which we should stop looking for 656 /// module maps. 657 /// 658 /// \param IsSystem Whether the directories we're looking at are system 659 /// header directories. 660 bool hasModuleMap(StringRef Filename, const DirectoryEntry *Root, 661 bool IsSystem); 662 663 /// Retrieve the module that corresponds to the given file, if any. 664 /// 665 /// \param File The header that we wish to map to a module. 666 /// \param AllowTextual Whether we want to find textual headers too. 667 ModuleMap::KnownHeader findModuleForHeader(FileEntryRef File, 668 bool AllowTextual = false, 669 bool AllowExcluded = false) const; 670 671 /// Retrieve all the modules corresponding to the given file. 672 /// 673 /// \param AllowCreation Whether to allow inference of a new submodule, or to 674 /// only return existing known modules. 675 /// 676 /// \ref findModuleForHeader should typically be used instead of this. 677 ArrayRef<ModuleMap::KnownHeader> 678 findAllModulesForHeader(FileEntryRef File) const; 679 680 /// Like \ref findAllModulesForHeader, but do not attempt to infer module 681 /// ownership from umbrella headers if we've not already done so. 682 ArrayRef<ModuleMap::KnownHeader> 683 findResolvedModulesForHeader(const FileEntry *File) const; 684 685 /// Read the contents of the given module map file. 686 /// 687 /// \param File The module map file. 688 /// \param IsSystem Whether this file is in a system header directory. 689 /// \param ID If the module map file is already mapped (perhaps as part of 690 /// processing a preprocessed module), the ID of the file. 691 /// \param Offset [inout] An offset within ID to start parsing. On exit, 692 /// filled by the end of the parsed contents (either EOF or the 693 /// location of an end-of-module-map pragma). 694 /// \param OriginalModuleMapFile The original path to the module map file, 695 /// used to resolve paths within the module (this is required when 696 /// building the module from preprocessed source). 697 /// \returns true if an error occurred, false otherwise. 698 bool loadModuleMapFile(FileEntryRef File, bool IsSystem, FileID ID = FileID(), 699 unsigned *Offset = nullptr, 700 StringRef OriginalModuleMapFile = StringRef()); 701 702 /// Collect the set of all known, top-level modules. 703 /// 704 /// \param Modules Will be filled with the set of known, top-level modules. 705 void collectAllModules(SmallVectorImpl<Module *> &Modules); 706 707 /// Load all known, top-level system modules. 708 void loadTopLevelSystemModules(); 709 710 private: 711 /// Lookup a module with the given module name and search-name. 712 /// 713 /// \param ModuleName The name of the module we're looking for. 714 /// 715 /// \param SearchName The "search-name" to derive filesystem paths from 716 /// when looking for the module map; this is usually equal to ModuleName, 717 /// but for compatibility with some buggy frameworks, additional attempts 718 /// may be made to find the module under a related-but-different search-name. 719 /// 720 /// \param ImportLoc Location of the module include/import. 721 /// 722 /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps 723 /// in subdirectories. 724 /// 725 /// \returns The module named ModuleName. 726 Module *lookupModule(StringRef ModuleName, StringRef SearchName, 727 SourceLocation ImportLoc, 728 bool AllowExtraModuleMapSearch = false); 729 730 /// Retrieve the name of the (to-be-)cached module file that should 731 /// be used to load a module with the given name. 732 /// 733 /// \param ModuleName The module whose module file name will be returned. 734 /// 735 /// \param ModuleMapPath A path that when combined with \c ModuleName 736 /// uniquely identifies this module. See Module::ModuleMap. 737 /// 738 /// \param CachePath A path to the module cache. 739 /// 740 /// \returns The name of the module file that corresponds to this module, 741 /// or an empty string if this module does not correspond to any module file. 742 std::string getCachedModuleFileNameImpl(StringRef ModuleName, 743 StringRef ModuleMapPath, 744 StringRef CachePath); 745 746 /// Retrieve a module with the given name, which may be part of the 747 /// given framework. 748 /// 749 /// \param Name The name of the module to retrieve. 750 /// 751 /// \param Dir The framework directory (e.g., ModuleName.framework). 752 /// 753 /// \param IsSystem Whether the framework directory is part of the system 754 /// frameworks. 755 /// 756 /// \returns The module, if found; otherwise, null. 757 Module *loadFrameworkModule(StringRef Name, DirectoryEntryRef Dir, 758 bool IsSystem); 759 760 /// Load all of the module maps within the immediate subdirectories 761 /// of the given search directory. 762 void loadSubdirectoryModuleMaps(DirectoryLookup &SearchDir); 763 764 /// Find and suggest a usable module for the given file. 765 /// 766 /// \return \c true if the file can be used, \c false if we are not permitted to 767 /// find this file due to requirements from \p RequestingModule. 768 bool findUsableModuleForHeader(FileEntryRef File, const DirectoryEntry *Root, 769 Module *RequestingModule, 770 ModuleMap::KnownHeader *SuggestedModule, 771 bool IsSystemHeaderDir); 772 773 /// Find and suggest a usable module for the given file, which is part of 774 /// the specified framework. 775 /// 776 /// \return \c true if the file can be used, \c false if we are not permitted to 777 /// find this file due to requirements from \p RequestingModule. 778 bool findUsableModuleForFrameworkHeader( 779 FileEntryRef File, StringRef FrameworkName, Module *RequestingModule, 780 ModuleMap::KnownHeader *SuggestedModule, bool IsSystemFramework); 781 782 /// Look up the file with the specified name and determine its owning 783 /// module. 784 OptionalFileEntryRef 785 getFileAndSuggestModule(StringRef FileName, SourceLocation IncludeLoc, 786 const DirectoryEntry *Dir, bool IsSystemHeaderDir, 787 Module *RequestingModule, 788 ModuleMap::KnownHeader *SuggestedModule, 789 bool OpenFile = true, bool CacheFailures = true); 790 791 /// Cache the result of a successful lookup at the given include location 792 /// using the search path at \c HitIt. 793 void cacheLookupSuccess(LookupFileCacheInfo &CacheLookup, 794 ConstSearchDirIterator HitIt, 795 SourceLocation IncludeLoc); 796 797 /// Note that a lookup at the given include location was successful using the 798 /// search path at index `HitIdx`. 799 void noteLookupUsage(unsigned HitIdx, SourceLocation IncludeLoc); 800 801 public: 802 /// Retrieve the module map. 803 ModuleMap &getModuleMap() { return ModMap; } 804 805 /// Retrieve the module map. 806 const ModuleMap &getModuleMap() const { return ModMap; } 807 808 unsigned header_file_size() const { return FileInfo.size(); } 809 810 /// Return the HeaderFileInfo structure for the specified FileEntry, 811 /// in preparation for updating it in some way. 812 HeaderFileInfo &getFileInfo(const FileEntry *FE); 813 814 /// Return the HeaderFileInfo structure for the specified FileEntry, 815 /// if it has ever been filled in. 816 /// \param WantExternal Whether the caller wants purely-external header file 817 /// info (where \p External is true). 818 const HeaderFileInfo *getExistingFileInfo(const FileEntry *FE, 819 bool WantExternal = true) const; 820 821 SearchDirIterator search_dir_begin() { return {*this, 0}; } 822 SearchDirIterator search_dir_end() { return {*this, SearchDirs.size()}; } 823 SearchDirRange search_dir_range() { 824 return {search_dir_begin(), search_dir_end()}; 825 } 826 827 ConstSearchDirIterator search_dir_begin() const { return quoted_dir_begin(); } 828 ConstSearchDirIterator search_dir_nth(size_t n) const { 829 assert(n < SearchDirs.size()); 830 return {*this, n}; 831 } 832 ConstSearchDirIterator search_dir_end() const { return system_dir_end(); } 833 ConstSearchDirRange search_dir_range() const { 834 return {search_dir_begin(), search_dir_end()}; 835 } 836 837 unsigned search_dir_size() const { return SearchDirs.size(); } 838 839 ConstSearchDirIterator quoted_dir_begin() const { return {*this, 0}; } 840 ConstSearchDirIterator quoted_dir_end() const { return angled_dir_begin(); } 841 842 ConstSearchDirIterator angled_dir_begin() const { 843 return {*this, AngledDirIdx}; 844 } 845 ConstSearchDirIterator angled_dir_end() const { return system_dir_begin(); } 846 847 ConstSearchDirIterator system_dir_begin() const { 848 return {*this, SystemDirIdx}; 849 } 850 ConstSearchDirIterator system_dir_end() const { 851 return {*this, SearchDirs.size()}; 852 } 853 854 /// Get the index of the given search directory. 855 unsigned searchDirIdx(const DirectoryLookup &DL) const; 856 857 /// Retrieve a uniqued framework name. 858 StringRef getUniqueFrameworkName(StringRef Framework); 859 860 /// Retrieve the include name for the header. 861 /// 862 /// \param File The entry for a given header. 863 /// \returns The name of how the file was included when the header's location 864 /// was resolved. 865 StringRef getIncludeNameForHeader(const FileEntry *File) const; 866 867 /// Suggest a path by which the specified file could be found, for use in 868 /// diagnostics to suggest a #include. Returned path will only contain forward 869 /// slashes as separators. MainFile is the absolute path of the file that we 870 /// are generating the diagnostics for. It will try to shorten the path using 871 /// MainFile location, if none of the include search directories were prefix 872 /// of File. 873 /// 874 /// \param IsSystem If non-null, filled in to indicate whether the suggested 875 /// path is relative to a system header directory. 876 std::string suggestPathToFileForDiagnostics(const FileEntry *File, 877 llvm::StringRef MainFile, 878 bool *IsSystem = nullptr) const; 879 880 /// Suggest a path by which the specified file could be found, for use in 881 /// diagnostics to suggest a #include. Returned path will only contain forward 882 /// slashes as separators. MainFile is the absolute path of the file that we 883 /// are generating the diagnostics for. It will try to shorten the path using 884 /// MainFile location, if none of the include search directories were prefix 885 /// of File. 886 /// 887 /// \param WorkingDir If non-empty, this will be prepended to search directory 888 /// paths that are relative. 889 std::string suggestPathToFileForDiagnostics(llvm::StringRef File, 890 llvm::StringRef WorkingDir, 891 llvm::StringRef MainFile, 892 bool *IsSystem = nullptr) const; 893 894 void PrintStats(); 895 896 size_t getTotalMemory() const; 897 898 private: 899 /// Describes what happened when we tried to load a module map file. 900 enum LoadModuleMapResult { 901 /// The module map file had already been loaded. 902 LMM_AlreadyLoaded, 903 904 /// The module map file was loaded by this invocation. 905 LMM_NewlyLoaded, 906 907 /// There is was directory with the given name. 908 LMM_NoDirectory, 909 910 /// There was either no module map file or the module map file was 911 /// invalid. 912 LMM_InvalidModuleMap 913 }; 914 915 LoadModuleMapResult loadModuleMapFileImpl(FileEntryRef File, bool IsSystem, 916 DirectoryEntryRef Dir, 917 FileID ID = FileID(), 918 unsigned *Offset = nullptr); 919 920 /// Try to load the module map file in the given directory. 921 /// 922 /// \param DirName The name of the directory where we will look for a module 923 /// map file. 924 /// \param IsSystem Whether this is a system header directory. 925 /// \param IsFramework Whether this is a framework directory. 926 /// 927 /// \returns The result of attempting to load the module map file from the 928 /// named directory. 929 LoadModuleMapResult loadModuleMapFile(StringRef DirName, bool IsSystem, 930 bool IsFramework); 931 932 /// Try to load the module map file in the given directory. 933 /// 934 /// \param Dir The directory where we will look for a module map file. 935 /// \param IsSystem Whether this is a system header directory. 936 /// \param IsFramework Whether this is a framework directory. 937 /// 938 /// \returns The result of attempting to load the module map file from the 939 /// named directory. 940 LoadModuleMapResult loadModuleMapFile(DirectoryEntryRef Dir, bool IsSystem, 941 bool IsFramework); 942 }; 943 944 /// Apply the header search options to get given HeaderSearch object. 945 void ApplyHeaderSearchOptions(HeaderSearch &HS, 946 const HeaderSearchOptions &HSOpts, 947 const LangOptions &Lang, 948 const llvm::Triple &triple); 949 950 } // namespace clang 951 952 #endif // LLVM_CLANG_LEX_HEADERSEARCH_H 953