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 "llvm/ADT/StringMap.h"
     19 #include "llvm/ADT/StringSet.h"
     20 #include "llvm/Support/Allocator.h"
     21 #include <vector>
     22 
     23 namespace clang {
     24 
     25 class ExternalIdentifierLookup;
     26 class FileEntry;
     27 class FileManager;
     28 class IdentifierInfo;
     29 
     30 /// HeaderFileInfo - The preprocessor keeps track of this information for each
     31 /// file that is #included.
     32 struct HeaderFileInfo {
     33   /// isImport - True if this is a #import'd or #pragma once file.
     34   unsigned isImport : 1;
     35 
     36   /// isPragmaOnce - True if this is  #pragma once file.
     37   unsigned isPragmaOnce : 1;
     38 
     39   /// DirInfo - Keep track of whether this is a system header, and if so,
     40   /// whether it is C++ clean or not.  This can be set by the include paths or
     41   /// by #pragma gcc system_header.  This is an instance of
     42   /// SrcMgr::CharacteristicKind.
     43   unsigned DirInfo : 2;
     44 
     45   /// \brief Whether this header file info was supplied by an external source.
     46   unsigned External : 1;
     47 
     48   /// \brief Whether this structure is considered to already have been
     49   /// "resolved", meaning that it was loaded from the external source.
     50   unsigned Resolved : 1;
     51 
     52   /// \brief Whether this is a header inside a framework that is currently
     53   /// being built.
     54   ///
     55   /// When a framework is being built, the headers have not yet been placed
     56   /// into the appropriate framework subdirectories, and therefore are
     57   /// provided via a header map. This bit indicates when this is one of
     58   /// those framework headers.
     59   unsigned IndexHeaderMapHeader : 1;
     60 
     61   /// NumIncludes - This is the number of times the file has been included
     62   /// already.
     63   unsigned short NumIncludes;
     64 
     65   /// \brief The ID number of the controlling macro.
     66   ///
     67   /// This ID number will be non-zero when there is a controlling
     68   /// macro whose IdentifierInfo may not yet have been loaded from
     69   /// external storage.
     70   unsigned ControllingMacroID;
     71 
     72   /// ControllingMacro - If this file has a #ifndef XXX (or equivalent) guard
     73   /// that protects the entire contents of the file, this is the identifier
     74   /// for the macro that controls whether or not it has any effect.
     75   ///
     76   /// Note: Most clients should use getControllingMacro() to access
     77   /// the controlling macro of this header, since
     78   /// getControllingMacro() is able to load a controlling macro from
     79   /// external storage.
     80   const IdentifierInfo *ControllingMacro;
     81 
     82   /// \brief If this header came from a framework include, this is the name
     83   /// of the framework.
     84   StringRef Framework;
     85 
     86   HeaderFileInfo()
     87     : isImport(false), isPragmaOnce(false), DirInfo(SrcMgr::C_User),
     88       External(false), Resolved(false), IndexHeaderMapHeader(false),
     89       NumIncludes(0), ControllingMacroID(0), ControllingMacro(0)  {}
     90 
     91   /// \brief Retrieve the controlling macro for this header file, if
     92   /// any.
     93   const IdentifierInfo *getControllingMacro(ExternalIdentifierLookup *External);
     94 
     95   /// \brief Determine whether this is a non-default header file info, e.g.,
     96   /// it corresponds to an actual header we've included or tried to include.
     97   bool isNonDefault() const {
     98     return isImport || isPragmaOnce || NumIncludes || ControllingMacro ||
     99       ControllingMacroID;
    100   }
    101 };
    102 
    103 /// \brief An external source of header file information, which may supply
    104 /// information about header files already included.
    105 class ExternalHeaderFileInfoSource {
    106 public:
    107   virtual ~ExternalHeaderFileInfoSource();
    108 
    109   /// \brief Retrieve the header file information for the given file entry.
    110   ///
    111   /// \returns Header file information for the given file entry, with the
    112   /// \c External bit set. If the file entry is not known, return a
    113   /// default-constructed \c HeaderFileInfo.
    114   virtual HeaderFileInfo GetHeaderFileInfo(const FileEntry *FE) = 0;
    115 };
    116 
    117 /// HeaderSearch - This class encapsulates the information needed to find the
    118 /// file referenced by a #include or #include_next, (sub-)framework lookup, etc.
    119 class HeaderSearch {
    120   FileManager &FileMgr;
    121   /// #include search path information.  Requests for #include "x" search the
    122   /// directory of the #including file first, then each directory in SearchDirs
    123   /// consecutively. Requests for <x> search the current dir first, then each
    124   /// directory in SearchDirs, starting at AngledDirIdx, consecutively.  If
    125   /// NoCurDirSearch is true, then the check for the file in the current
    126   /// directory is suppressed.
    127   std::vector<DirectoryLookup> SearchDirs;
    128   unsigned AngledDirIdx;
    129   unsigned SystemDirIdx;
    130   bool NoCurDirSearch;
    131 
    132   /// \brief The path to the module cache.
    133   std::string ModuleCachePath;
    134 
    135   /// \brief The name of the module we're building.
    136   std::string BuildingModule;
    137 
    138   /// FileInfo - This contains all of the preprocessor-specific data about files
    139   /// that are included.  The vector is indexed by the FileEntry's UID.
    140   ///
    141   std::vector<HeaderFileInfo> FileInfo;
    142 
    143   /// LookupFileCache - This is keeps track of each lookup performed by
    144   /// LookupFile.  The first part of the value is the starting index in
    145   /// SearchDirs that the cached search was performed from.  If there is a hit
    146   /// and this value doesn't match the current query, the cache has to be
    147   /// ignored.  The second value is the entry in SearchDirs that satisfied the
    148   /// query.
    149   llvm::StringMap<std::pair<unsigned, unsigned>, llvm::BumpPtrAllocator>
    150     LookupFileCache;
    151 
    152 
    153   /// FrameworkMap - This is a collection mapping a framework or subframework
    154   /// name like "Carbon" to the Carbon.framework directory.
    155   llvm::StringMap<const DirectoryEntry *, llvm::BumpPtrAllocator>
    156     FrameworkMap;
    157 
    158   /// HeaderMaps - This is a mapping from FileEntry -> HeaderMap, uniquing
    159   /// headermaps.  This vector owns the headermap.
    160   std::vector<std::pair<const FileEntry*, const HeaderMap*> > HeaderMaps;
    161 
    162   /// \brief Uniqued set of framework names, which is used to track which
    163   /// headers were included as framework headers.
    164   llvm::StringSet<llvm::BumpPtrAllocator> FrameworkNames;
    165 
    166   /// \brief Entity used to resolve the identifier IDs of controlling
    167   /// macros into IdentifierInfo pointers, as needed.
    168   ExternalIdentifierLookup *ExternalLookup;
    169 
    170   /// \brief Entity used to look up stored header file information.
    171   ExternalHeaderFileInfoSource *ExternalSource;
    172 
    173   // Various statistics we track for performance analysis.
    174   unsigned NumIncluded;
    175   unsigned NumMultiIncludeFileOptzn;
    176   unsigned NumFrameworkLookups, NumSubFrameworkLookups;
    177 
    178   // HeaderSearch doesn't support default or copy construction.
    179   explicit HeaderSearch();
    180   explicit HeaderSearch(const HeaderSearch&);
    181   void operator=(const HeaderSearch&);
    182 public:
    183   HeaderSearch(FileManager &FM);
    184   ~HeaderSearch();
    185 
    186   FileManager &getFileMgr() const { return FileMgr; }
    187 
    188   /// SetSearchPaths - Interface for setting the file search paths.
    189   ///
    190   void SetSearchPaths(const std::vector<DirectoryLookup> &dirs,
    191                       unsigned angledDirIdx, unsigned systemDirIdx,
    192                       bool noCurDirSearch) {
    193     assert(angledDirIdx <= systemDirIdx && systemDirIdx <= dirs.size() &&
    194         "Directory indicies are unordered");
    195     SearchDirs = dirs;
    196     AngledDirIdx = angledDirIdx;
    197     SystemDirIdx = systemDirIdx;
    198     NoCurDirSearch = noCurDirSearch;
    199     //LookupFileCache.clear();
    200   }
    201 
    202   /// \brief Set the path to the module cache and the name of the module
    203   /// we're building
    204   void configureModules(StringRef CachePath, StringRef BuildingModule) {
    205     ModuleCachePath = CachePath;
    206     this->BuildingModule = BuildingModule;
    207   }
    208 
    209   /// ClearFileInfo - Forget everything we know about headers so far.
    210   void ClearFileInfo() {
    211     FileInfo.clear();
    212   }
    213 
    214   void SetExternalLookup(ExternalIdentifierLookup *EIL) {
    215     ExternalLookup = EIL;
    216   }
    217 
    218   ExternalIdentifierLookup *getExternalLookup() const {
    219     return ExternalLookup;
    220   }
    221 
    222   /// \brief Set the external source of header information.
    223   void SetExternalSource(ExternalHeaderFileInfoSource *ES) {
    224     ExternalSource = ES;
    225   }
    226 
    227   /// LookupFile - Given a "foo" or <foo> reference, look up the indicated file,
    228   /// return null on failure.
    229   ///
    230   /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member
    231   /// the file was found in, or null if not applicable.
    232   ///
    233   /// \param isAngled indicates whether the file reference is a <> reference.
    234   ///
    235   /// \param CurDir If non-null, the file was found in the specified directory
    236   /// search location.  This is used to implement #include_next.
    237   ///
    238   /// \param CurFileEnt If non-null, indicates where the #including file is, in
    239   /// case a relative search is needed.
    240   ///
    241   /// \param SearchPath If non-null, will be set to the search path relative
    242   /// to which the file was found. If the include path is absolute, SearchPath
    243   /// will be set to an empty string.
    244   ///
    245   /// \param RelativePath If non-null, will be set to the path relative to
    246   /// SearchPath at which the file was found. This only differs from the
    247   /// Filename for framework includes.
    248   ///
    249   /// \param SuggestedModule If non-null, and the file found is semantically
    250   /// part of a known module, this will be set to the name of the module that
    251   /// could be imported instead of preprocessing/parsing the file found.
    252   const FileEntry *LookupFile(StringRef Filename, bool isAngled,
    253                               const DirectoryLookup *FromDir,
    254                               const DirectoryLookup *&CurDir,
    255                               const FileEntry *CurFileEnt,
    256                               SmallVectorImpl<char> *SearchPath,
    257                               SmallVectorImpl<char> *RelativePath,
    258                               StringRef *SuggestedModule);
    259 
    260   /// LookupSubframeworkHeader - Look up a subframework for the specified
    261   /// #include file.  For example, if #include'ing <HIToolbox/HIToolbox.h> from
    262   /// within ".../Carbon.framework/Headers/Carbon.h", check to see if HIToolbox
    263   /// is a subframework within Carbon.framework.  If so, return the FileEntry
    264   /// for the designated file, otherwise return null.
    265   const FileEntry *LookupSubframeworkHeader(
    266       StringRef Filename,
    267       const FileEntry *RelativeFileEnt,
    268       SmallVectorImpl<char> *SearchPath,
    269       SmallVectorImpl<char> *RelativePath);
    270 
    271   /// LookupFrameworkCache - Look up the specified framework name in our
    272   /// framework cache, returning the DirectoryEntry it is in if we know,
    273   /// otherwise, return null.
    274   const DirectoryEntry *&LookupFrameworkCache(StringRef FWName) {
    275     return FrameworkMap.GetOrCreateValue(FWName).getValue();
    276   }
    277 
    278   /// ShouldEnterIncludeFile - Mark the specified file as a target of of a
    279   /// #include, #include_next, or #import directive.  Return false if #including
    280   /// the file will have no effect or true if we should include it.
    281   bool ShouldEnterIncludeFile(const FileEntry *File, bool isImport);
    282 
    283 
    284   /// getFileDirFlavor - Return whether the specified file is a normal header,
    285   /// a system header, or a C++ friendly system header.
    286   SrcMgr::CharacteristicKind getFileDirFlavor(const FileEntry *File) {
    287     return (SrcMgr::CharacteristicKind)getFileInfo(File).DirInfo;
    288   }
    289 
    290   /// MarkFileIncludeOnce - Mark the specified file as a "once only" file, e.g.
    291   /// due to #pragma once.
    292   void MarkFileIncludeOnce(const FileEntry *File) {
    293     HeaderFileInfo &FI = getFileInfo(File);
    294     FI.isImport = true;
    295     FI.isPragmaOnce = true;
    296   }
    297 
    298   /// MarkFileSystemHeader - Mark the specified file as a system header, e.g.
    299   /// due to #pragma GCC system_header.
    300   void MarkFileSystemHeader(const FileEntry *File) {
    301     getFileInfo(File).DirInfo = SrcMgr::C_System;
    302   }
    303 
    304   /// IncrementIncludeCount - Increment the count for the number of times the
    305   /// specified FileEntry has been entered.
    306   void IncrementIncludeCount(const FileEntry *File) {
    307     ++getFileInfo(File).NumIncludes;
    308   }
    309 
    310   /// SetFileControllingMacro - Mark the specified file as having a controlling
    311   /// macro.  This is used by the multiple-include optimization to eliminate
    312   /// no-op #includes.
    313   void SetFileControllingMacro(const FileEntry *File,
    314                                const IdentifierInfo *ControllingMacro) {
    315     getFileInfo(File).ControllingMacro = ControllingMacro;
    316   }
    317 
    318   /// \brief Determine whether this file is intended to be safe from
    319   /// multiple inclusions, e.g., it has #pragma once or a controlling
    320   /// macro.
    321   ///
    322   /// This routine does not consider the effect of #import
    323   bool isFileMultipleIncludeGuarded(const FileEntry *File);
    324 
    325   /// CreateHeaderMap - This method returns a HeaderMap for the specified
    326   /// FileEntry, uniquing them through the the 'HeaderMaps' datastructure.
    327   const HeaderMap *CreateHeaderMap(const FileEntry *FE);
    328 
    329   /// \brief Search in the module cache path for a module with the given
    330   /// name.
    331   ///
    332   /// \param If non-NULL, will be set to the module file name we expected to
    333   /// find (regardless of whether it was actually found or not).
    334   ///
    335   /// \param UmbrellaHeader If non-NULL, and no module was found in the module
    336   /// cache, this routine will search in the framework paths to determine
    337   /// whether a module can be built from an umbrella header. If so, the pointee
    338   /// will be set to the path of the umbrella header.
    339   ///
    340   /// \returns A file describing the named module, if available, or NULL to
    341   /// indicate that the module could not be found.
    342   const FileEntry *lookupModule(StringRef ModuleName,
    343                                 std::string *ModuleFileName = 0,
    344                                 std::string *UmbrellaHeader = 0);
    345 
    346   void IncrementFrameworkLookupCount() { ++NumFrameworkLookups; }
    347 
    348   typedef std::vector<HeaderFileInfo>::const_iterator header_file_iterator;
    349   header_file_iterator header_file_begin() const { return FileInfo.begin(); }
    350   header_file_iterator header_file_end() const { return FileInfo.end(); }
    351   unsigned header_file_size() const { return FileInfo.size(); }
    352 
    353   // Used by ASTReader.
    354   void setHeaderFileInfoForUID(HeaderFileInfo HFI, unsigned UID);
    355 
    356   // Used by external tools
    357   typedef std::vector<DirectoryLookup>::const_iterator search_dir_iterator;
    358   search_dir_iterator search_dir_begin() const { return SearchDirs.begin(); }
    359   search_dir_iterator search_dir_end() const { return SearchDirs.end(); }
    360   unsigned search_dir_size() const { return SearchDirs.size(); }
    361 
    362   search_dir_iterator quoted_dir_begin() const {
    363     return SearchDirs.begin();
    364   }
    365   search_dir_iterator quoted_dir_end() const {
    366     return SearchDirs.begin() + AngledDirIdx;
    367   }
    368 
    369   search_dir_iterator angled_dir_begin() const {
    370     return SearchDirs.begin() + AngledDirIdx;
    371   }
    372   search_dir_iterator angled_dir_end() const {
    373     return SearchDirs.begin() + SystemDirIdx;
    374   }
    375 
    376   search_dir_iterator system_dir_begin() const {
    377     return SearchDirs.begin() + SystemDirIdx;
    378   }
    379   search_dir_iterator system_dir_end() const { return SearchDirs.end(); }
    380 
    381   /// \brief Retrieve a uniqued framework name.
    382   StringRef getUniqueFrameworkName(StringRef Framework);
    383 
    384   void PrintStats();
    385 
    386   size_t getTotalMemory() const;
    387 
    388 private:
    389 
    390   /// getFileInfo - Return the HeaderFileInfo structure for the specified
    391   /// FileEntry.
    392   HeaderFileInfo &getFileInfo(const FileEntry *FE);
    393 };
    394 
    395 }  // end namespace clang
    396 
    397 #endif
    398