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