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