1 //===--- HeaderSearch.h - Resolve Header File Locations ---------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines the HeaderSearch interface.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_CLANG_LEX_HEADERSEARCH_H
15 #define LLVM_CLANG_LEX_HEADERSEARCH_H
17 #include "clang/Lex/DirectoryLookup.h"
18 #include "llvm/ADT/StringMap.h"
19 #include "llvm/ADT/StringSet.h"
20 #include "llvm/Support/Allocator.h"
25 class ExternalIdentifierLookup;
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;
36 /// isPragmaOnce - True if this is #pragma once file.
37 unsigned isPragmaOnce : 1;
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.
45 /// \brief Whether this header file info was supplied by an external source.
46 unsigned External : 1;
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;
52 /// \brief Whether this is a header inside a framework that is currently
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;
61 /// NumIncludes - This is the number of times the file has been included
63 unsigned short NumIncludes;
65 /// \brief The ID number of the controlling macro.
67 /// This ID number will be non-zero when there is a controlling
68 /// macro whose IdentifierInfo may not yet have been loaded from
70 unsigned ControllingMacroID;
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.
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
80 const IdentifierInfo *ControllingMacro;
82 /// \brief If this header came from a framework include, this is the name
87 : isImport(false), isPragmaOnce(false), DirInfo(SrcMgr::C_User),
88 External(false), Resolved(false), IndexHeaderMapHeader(false),
89 NumIncludes(0), ControllingMacroID(0), ControllingMacro(0) {}
91 /// \brief Retrieve the controlling macro for this header file, if
93 const IdentifierInfo *getControllingMacro(ExternalIdentifierLookup *External);
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 ||
103 /// \brief An external source of header file information, which may supply
104 /// information about header files already included.
105 class ExternalHeaderFileInfoSource {
107 virtual ~ExternalHeaderFileInfoSource();
109 /// \brief Retrieve the header file information for the given file entry.
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;
117 /// HeaderSearch - This class encapsulates the information needed to find the
118 /// file referenced by a #include or #include_next, (sub-)framework lookup, etc.
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;
132 /// \brief The path to the module cache.
133 std::string ModuleCachePath;
135 /// \brief The name of the module we're building.
136 std::string BuildingModule;
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.
141 std::vector<HeaderFileInfo> FileInfo;
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
149 llvm::StringMap<std::pair<unsigned, unsigned>, llvm::BumpPtrAllocator>
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>
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;
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;
166 /// \brief Entity used to resolve the identifier IDs of controlling
167 /// macros into IdentifierInfo pointers, as needed.
168 ExternalIdentifierLookup *ExternalLookup;
170 /// \brief Entity used to look up stored header file information.
171 ExternalHeaderFileInfoSource *ExternalSource;
173 // Various statistics we track for performance analysis.
174 unsigned NumIncluded;
175 unsigned NumMultiIncludeFileOptzn;
176 unsigned NumFrameworkLookups, NumSubFrameworkLookups;
178 // HeaderSearch doesn't support default or copy construction.
179 explicit HeaderSearch();
180 explicit HeaderSearch(const HeaderSearch&);
181 void operator=(const HeaderSearch&);
183 HeaderSearch(FileManager &FM);
186 FileManager &getFileMgr() const { return FileMgr; }
188 /// SetSearchPaths - Interface for setting the file search paths.
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");
196 AngledDirIdx = angledDirIdx;
197 SystemDirIdx = systemDirIdx;
198 NoCurDirSearch = noCurDirSearch;
199 //LookupFileCache.clear();
202 /// \brief Set the path to the module cache and the name of the module
204 void configureModules(StringRef CachePath, StringRef BuildingModule) {
205 ModuleCachePath = CachePath;
206 this->BuildingModule = BuildingModule;
209 /// ClearFileInfo - Forget everything we know about headers so far.
210 void ClearFileInfo() {
214 void SetExternalLookup(ExternalIdentifierLookup *EIL) {
215 ExternalLookup = EIL;
218 ExternalIdentifierLookup *getExternalLookup() const {
219 return ExternalLookup;
222 /// \brief Set the external source of header information.
223 void SetExternalSource(ExternalHeaderFileInfoSource *ES) {
227 /// LookupFile - Given a "foo" or <foo> reference, look up the indicated file,
228 /// return null on failure.
230 /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member
231 /// the file was found in, or null if not applicable.
233 /// \param isAngled indicates whether the file reference is a <> reference.
235 /// \param CurDir If non-null, the file was found in the specified directory
236 /// search location. This is used to implement #include_next.
238 /// \param CurFileEnt If non-null, indicates where the #including file is, in
239 /// case a relative search is needed.
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.
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.
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);
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(
267 const FileEntry *RelativeFileEnt,
268 SmallVectorImpl<char> *SearchPath,
269 SmallVectorImpl<char> *RelativePath);
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();
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);
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;
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);
295 FI.isPragmaOnce = true;
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;
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;
310 /// SetFileControllingMacro - Mark the specified file as having a controlling
311 /// macro. This is used by the multiple-include optimization to eliminate
313 void SetFileControllingMacro(const FileEntry *File,
314 const IdentifierInfo *ControllingMacro) {
315 getFileInfo(File).ControllingMacro = ControllingMacro;
318 /// \brief Determine whether this file is intended to be safe from
319 /// multiple inclusions, e.g., it has #pragma once or a controlling
322 /// This routine does not consider the effect of #import
323 bool isFileMultipleIncludeGuarded(const FileEntry *File);
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);
329 /// \brief Search in the module cache path for a module with the given
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).
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.
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);
346 void IncrementFrameworkLookupCount() { ++NumFrameworkLookups; }
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(); }
353 // Used by ASTReader.
354 void setHeaderFileInfoForUID(HeaderFileInfo HFI, unsigned UID);
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(); }
362 search_dir_iterator quoted_dir_begin() const {
363 return SearchDirs.begin();
365 search_dir_iterator quoted_dir_end() const {
366 return SearchDirs.begin() + AngledDirIdx;
369 search_dir_iterator angled_dir_begin() const {
370 return SearchDirs.begin() + AngledDirIdx;
372 search_dir_iterator angled_dir_end() const {
373 return SearchDirs.begin() + SystemDirIdx;
376 search_dir_iterator system_dir_begin() const {
377 return SearchDirs.begin() + SystemDirIdx;
379 search_dir_iterator system_dir_end() const { return SearchDirs.end(); }
381 /// \brief Retrieve a uniqued framework name.
382 StringRef getUniqueFrameworkName(StringRef Framework);
386 size_t getTotalMemory() const;
390 /// getFileInfo - Return the HeaderFileInfo structure for the specified
392 HeaderFileInfo &getFileInfo(const FileEntry *FE);
395 } // end namespace clang