clang  12.0.0git
HeaderSearch.h
Go to the documentation of this file.
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 
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/StringMap.h"
24 #include "llvm/ADT/StringSet.h"
25 #include "llvm/ADT/StringRef.h"
26 #include "llvm/Support/Allocator.h"
27 #include <cassert>
28 #include <cstddef>
29 #include <memory>
30 #include <string>
31 #include <utility>
32 #include <vector>
33 
34 namespace clang {
35 
36 class DiagnosticsEngine;
37 class DirectoryEntry;
38 class ExternalPreprocessorSource;
39 class FileEntry;
40 class FileManager;
41 class HeaderSearchOptions;
42 class IdentifierInfo;
43 class LangOptions;
44 class Module;
45 class Preprocessor;
46 class TargetInfo;
47 
48 /// The preprocessor keeps track of this information for each
49 /// file that is \#included.
51  /// True if this is a \#import'd or \#pragma once file.
52  unsigned isImport : 1;
53 
54  /// True if this is a \#pragma once file.
55  unsigned isPragmaOnce : 1;
56 
57  /// Keep track of whether this is a system header, and if so,
58  /// whether it is C++ clean or not. This can be set by the include paths or
59  /// by \#pragma gcc system_header. This is an instance of
60  /// SrcMgr::CharacteristicKind.
61  unsigned DirInfo : 3;
62 
63  /// Whether this header file info was supplied by an external source,
64  /// and has not changed since.
65  unsigned External : 1;
66 
67  /// Whether this header is part of a module.
68  unsigned isModuleHeader : 1;
69 
70  /// Whether this header is part of the module that we are building.
72 
73  /// Whether this structure is considered to already have been
74  /// "resolved", meaning that it was loaded from the external source.
75  unsigned Resolved : 1;
76 
77  /// Whether this is a header inside a framework that is currently
78  /// being built.
79  ///
80  /// When a framework is being built, the headers have not yet been placed
81  /// into the appropriate framework subdirectories, and therefore are
82  /// provided via a header map. This bit indicates when this is one of
83  /// those framework headers.
84  unsigned IndexHeaderMapHeader : 1;
85 
86  /// Whether this file has been looked up as a header.
87  unsigned IsValid : 1;
88 
89  /// The number of times the file has been included already.
90  unsigned short NumIncludes = 0;
91 
92  /// The ID number of the controlling macro.
93  ///
94  /// This ID number will be non-zero when there is a controlling
95  /// macro whose IdentifierInfo may not yet have been loaded from
96  /// external storage.
97  unsigned ControllingMacroID = 0;
98 
99  /// If this file has a \#ifndef XXX (or equivalent) guard that
100  /// protects the entire contents of the file, this is the identifier
101  /// for the macro that controls whether or not it has any effect.
102  ///
103  /// Note: Most clients should use getControllingMacro() to access
104  /// the controlling macro of this header, since
105  /// getControllingMacro() is able to load a controlling macro from
106  /// external storage.
108 
109  /// If this header came from a framework include, this is the name
110  /// of the framework.
111  StringRef Framework;
112 
117 
118  /// Retrieve the controlling macro for this header file, if
119  /// any.
120  const IdentifierInfo *
122 
123  /// Determine whether this is a non-default header file info, e.g.,
124  /// it corresponds to an actual header we've included or tried to include.
125  bool isNonDefault() const {
128  }
129 };
130 
131 /// An external source of header file information, which may supply
132 /// information about header files already included.
134 public:
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.
147  /// The directory entry which should be used for the cached framework.
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).
154 };
155 
156 /// Encapsulates the information needed to find the file referenced
157 /// by a \#include or \#include_next, (sub-)framework lookup, etc.
159  friend class DirectoryLookup;
160 
161  /// Header-search options used to initialize this header search.
162  std::shared_ptr<HeaderSearchOptions> HSOpts;
163 
164  DiagnosticsEngine &Diags;
165  FileManager &FileMgr;
166 
167  /// \#include search path information. Requests for \#include "x" search the
168  /// directory of the \#including file first, then each directory in SearchDirs
169  /// consecutively. Requests for <x> search the current dir first, then each
170  /// directory in SearchDirs, starting at AngledDirIdx, consecutively. If
171  /// NoCurDirSearch is true, then the check for the file in the current
172  /// directory is suppressed.
173  std::vector<DirectoryLookup> SearchDirs;
174  unsigned AngledDirIdx = 0;
175  unsigned SystemDirIdx = 0;
176  bool NoCurDirSearch = false;
177 
178  /// \#include prefixes for which the 'system header' property is
179  /// overridden.
180  ///
181  /// For a \#include "x" or \#include <x> directive, the last string in this
182  /// list which is a prefix of 'x' determines whether the file is treated as
183  /// a system header.
184  std::vector<std::pair<std::string, bool>> SystemHeaderPrefixes;
185 
186  /// The hash used for module cache paths.
187  std::string ModuleHash;
188 
189  /// The path to the module cache.
190  std::string ModuleCachePath;
191 
192  /// All of the preprocessor-specific data about files that are
193  /// included, indexed by the FileEntry's UID.
194  mutable std::vector<HeaderFileInfo> FileInfo;
195 
196  /// Keeps track of each lookup performed by LookupFile.
197  struct LookupFileCacheInfo {
198  /// Starting index in SearchDirs that the cached search was performed from.
199  /// If there is a hit and this value doesn't match the current query, the
200  /// cache has to be ignored.
201  unsigned StartIdx = 0;
202 
203  /// The entry in SearchDirs that satisfied the query.
204  unsigned HitIdx = 0;
205 
206  /// This is non-null if the original filename was mapped to a framework
207  /// include via a headermap.
208  const char *MappedName = nullptr;
209 
210  /// Default constructor -- Initialize all members with zero.
211  LookupFileCacheInfo() = default;
212 
213  void reset(unsigned StartIdx) {
214  this->StartIdx = StartIdx;
215  this->MappedName = nullptr;
216  }
217  };
218  llvm::StringMap<LookupFileCacheInfo, llvm::BumpPtrAllocator> LookupFileCache;
219 
220  /// Collection mapping a framework or subframework
221  /// name like "Carbon" to the Carbon.framework directory.
222  llvm::StringMap<FrameworkCacheEntry, llvm::BumpPtrAllocator> FrameworkMap;
223 
224  /// Maps include file names (including the quotes or
225  /// angle brackets) to other include file names. This is used to support the
226  /// include_alias pragma for Microsoft compatibility.
227  using IncludeAliasMap =
228  llvm::StringMap<std::string, llvm::BumpPtrAllocator>;
229  std::unique_ptr<IncludeAliasMap> IncludeAliases;
230 
231  /// This is a mapping from FileEntry -> HeaderMap, uniquing headermaps.
232  std::vector<std::pair<const FileEntry *, std::unique_ptr<HeaderMap>>> HeaderMaps;
233 
234  /// The mapping between modules and headers.
235  mutable ModuleMap ModMap;
236 
237  /// Describes whether a given directory has a module map in it.
238  llvm::DenseMap<const DirectoryEntry *, bool> DirectoryHasModuleMap;
239 
240  /// Set of module map files we've already loaded, and a flag indicating
241  /// whether they were valid or not.
242  llvm::DenseMap<const FileEntry *, bool> LoadedModuleMaps;
243 
244  /// Uniqued set of framework names, which is used to track which
245  /// headers were included as framework headers.
246  llvm::StringSet<llvm::BumpPtrAllocator> FrameworkNames;
247 
248  /// Entity used to resolve the identifier IDs of controlling
249  /// macros into IdentifierInfo pointers, and keep the identifire up to date,
250  /// as needed.
251  ExternalPreprocessorSource *ExternalLookup = nullptr;
252 
253  /// Entity used to look up stored header file information.
254  ExternalHeaderFileInfoSource *ExternalSource = nullptr;
255 
256 public:
257  HeaderSearch(std::shared_ptr<HeaderSearchOptions> HSOpts,
258  SourceManager &SourceMgr, DiagnosticsEngine &Diags,
259  const LangOptions &LangOpts, const TargetInfo *Target);
260  HeaderSearch(const HeaderSearch &) = delete;
261  HeaderSearch &operator=(const HeaderSearch &) = delete;
262 
263  /// Retrieve the header-search options with which this header search
264  /// was initialized.
265  HeaderSearchOptions &getHeaderSearchOpts() const { return *HSOpts; }
266 
267  FileManager &getFileMgr() const { return FileMgr; }
268 
269  DiagnosticsEngine &getDiags() const { return Diags; }
270 
271  /// Interface for setting the file search paths.
272  void SetSearchPaths(const std::vector<DirectoryLookup> &dirs,
273  unsigned angledDirIdx, unsigned systemDirIdx,
274  bool noCurDirSearch) {
275  assert(angledDirIdx <= systemDirIdx && systemDirIdx <= dirs.size() &&
276  "Directory indices are unordered");
277  SearchDirs = dirs;
278  AngledDirIdx = angledDirIdx;
279  SystemDirIdx = systemDirIdx;
280  NoCurDirSearch = noCurDirSearch;
281  //LookupFileCache.clear();
282  }
283 
284  /// Add an additional search path.
285  void AddSearchPath(const DirectoryLookup &dir, bool isAngled) {
286  unsigned idx = isAngled ? SystemDirIdx : AngledDirIdx;
287  SearchDirs.insert(SearchDirs.begin() + idx, dir);
288  if (!isAngled)
289  AngledDirIdx++;
290  SystemDirIdx++;
291  }
292 
293  /// Set the list of system header prefixes.
294  void SetSystemHeaderPrefixes(ArrayRef<std::pair<std::string, bool>> P) {
295  SystemHeaderPrefixes.assign(P.begin(), P.end());
296  }
297 
298  /// Checks whether the map exists or not.
299  bool HasIncludeAliasMap() const { return (bool)IncludeAliases; }
300 
301  /// Map the source include name to the dest include name.
302  ///
303  /// The Source should include the angle brackets or quotes, the dest
304  /// should not. This allows for distinction between <> and "" headers.
305  void AddIncludeAlias(StringRef Source, StringRef Dest) {
306  if (!IncludeAliases)
307  IncludeAliases.reset(new IncludeAliasMap);
308  (*IncludeAliases)[Source] = std::string(Dest);
309  }
310 
311  /// Maps one header file name to a different header
312  /// file name, for use with the include_alias pragma. Note that the source
313  /// file name should include the angle brackets or quotes. Returns StringRef
314  /// as null if the header cannot be mapped.
315  StringRef MapHeaderToIncludeAlias(StringRef Source) {
316  assert(IncludeAliases && "Trying to map headers when there's no map");
317 
318  // Do any filename replacements before anything else
319  IncludeAliasMap::const_iterator Iter = IncludeAliases->find(Source);
320  if (Iter != IncludeAliases->end())
321  return Iter->second;
322  return {};
323  }
324 
325  /// Set the hash to use for module cache paths.
326  void setModuleHash(StringRef Hash) { ModuleHash = std::string(Hash); }
327 
328  /// Set the path to the module cache.
329  void setModuleCachePath(StringRef CachePath) {
330  ModuleCachePath = std::string(CachePath);
331  }
332 
333  /// Retrieve the module hash.
334  StringRef getModuleHash() const { return ModuleHash; }
335 
336  /// Retrieve the path to the module cache.
337  StringRef getModuleCachePath() const { return ModuleCachePath; }
338 
339  /// Consider modules when including files from this directory.
341  DirectoryHasModuleMap[Dir] = true;
342  }
343 
344  /// Forget everything we know about headers so far.
345  void ClearFileInfo() {
346  FileInfo.clear();
347  }
348 
350  ExternalLookup = EPS;
351  }
352 
354  return ExternalLookup;
355  }
356 
357  /// Set the external source of header information.
359  ExternalSource = ES;
360  }
361 
362  /// Set the target information for the header search, if not
363  /// already known.
364  void setTarget(const TargetInfo &Target);
365 
366  /// Given a "foo" or <foo> reference, look up the indicated file,
367  /// return null on failure.
368  ///
369  /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member
370  /// the file was found in, or null if not applicable.
371  ///
372  /// \param IncludeLoc Used for diagnostics if valid.
373  ///
374  /// \param isAngled indicates whether the file reference is a <> reference.
375  ///
376  /// \param CurDir If non-null, the file was found in the specified directory
377  /// search location. This is used to implement \#include_next.
378  ///
379  /// \param Includers Indicates where the \#including file(s) are, in case
380  /// relative searches are needed. In reverse order of inclusion.
381  ///
382  /// \param SearchPath If non-null, will be set to the search path relative
383  /// to which the file was found. If the include path is absolute, SearchPath
384  /// will be set to an empty string.
385  ///
386  /// \param RelativePath If non-null, will be set to the path relative to
387  /// SearchPath at which the file was found. This only differs from the
388  /// Filename for framework includes.
389  ///
390  /// \param SuggestedModule If non-null, and the file found is semantically
391  /// part of a known module, this will be set to the module that should
392  /// be imported instead of preprocessing/parsing the file found.
393  ///
394  /// \param IsMapped If non-null, and the search involved header maps, set to
395  /// true.
396  ///
397  /// \param IsFrameworkFound If non-null, will be set to true if a framework is
398  /// found in any of searched SearchDirs. Will be set to false if a framework
399  /// is found only through header maps. Doesn't guarantee the requested file is
400  /// found.
401  Optional<FileEntryRef> LookupFile(
402  StringRef Filename, SourceLocation IncludeLoc, bool isAngled,
403  const DirectoryLookup *FromDir, const DirectoryLookup *&CurDir,
404  ArrayRef<std::pair<const FileEntry *, const DirectoryEntry *>> Includers,
405  SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath,
406  Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule,
407  bool *IsMapped, bool *IsFrameworkFound, bool SkipCache = false,
408  bool BuildSystemModule = false);
409 
410  /// Look up a subframework for the specified \#include file.
411  ///
412  /// For example, if \#include'ing <HIToolbox/HIToolbox.h> from
413  /// within ".../Carbon.framework/Headers/Carbon.h", check to see if
414  /// HIToolbox is a subframework within Carbon.framework. If so, return
415  /// the FileEntry for the designated file, otherwise return null.
416  Optional<FileEntryRef> LookupSubframeworkHeader(
417  StringRef Filename, const FileEntry *ContextFileEnt,
418  SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath,
419  Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule);
420 
421  /// Look up the specified framework name in our framework cache.
422  /// \returns The DirectoryEntry it is in if we know, null otherwise.
424  return FrameworkMap[FWName];
425  }
426 
427  /// Mark the specified file as a target of a \#include,
428  /// \#include_next, or \#import directive.
429  ///
430  /// \return false if \#including the file will have no effect or true
431  /// if we should include it.
432  bool ShouldEnterIncludeFile(Preprocessor &PP, const FileEntry *File,
433  bool isImport, bool ModulesEnabled,
434  Module *M);
435 
436  /// Return whether the specified file is a normal header,
437  /// a system header, or a C++ friendly system header.
439  return (SrcMgr::CharacteristicKind)getFileInfo(File).DirInfo;
440  }
441 
442  /// Mark the specified file as a "once only" file, e.g. due to
443  /// \#pragma once.
444  void MarkFileIncludeOnce(const FileEntry *File) {
445  HeaderFileInfo &FI = getFileInfo(File);
446  FI.isImport = true;
447  FI.isPragmaOnce = true;
448  }
449 
450  /// Mark the specified file as a system header, e.g. due to
451  /// \#pragma GCC system_header.
452  void MarkFileSystemHeader(const FileEntry *File) {
453  getFileInfo(File).DirInfo = SrcMgr::C_System;
454  }
455 
456  /// Mark the specified file as part of a module.
457  void MarkFileModuleHeader(const FileEntry *FE,
459  bool isCompilingModuleHeader);
460 
461  /// Increment the count for the number of times the specified
462  /// FileEntry has been entered.
463  void IncrementIncludeCount(const FileEntry *File) {
464  ++getFileInfo(File).NumIncludes;
465  }
466 
467  /// Mark the specified file as having a controlling macro.
468  ///
469  /// This is used by the multiple-include optimization to eliminate
470  /// no-op \#includes.
472  const IdentifierInfo *ControllingMacro) {
473  getFileInfo(File).ControllingMacro = ControllingMacro;
474  }
475 
476  /// Return true if this is the first time encountering this header.
477  bool FirstTimeLexingFile(const FileEntry *File) {
478  return getFileInfo(File).NumIncludes == 1;
479  }
480 
481  /// Determine whether this file is intended to be safe from
482  /// multiple inclusions, e.g., it has \#pragma once or a controlling
483  /// macro.
484  ///
485  /// This routine does not consider the effect of \#import
486  bool isFileMultipleIncludeGuarded(const FileEntry *File);
487 
488  /// Determine whether the given file is known to have ever been \#imported
489  /// (or if it has been \#included and we've encountered a \#pragma once).
490  bool hasFileBeenImported(const FileEntry *File) {
491  const HeaderFileInfo *FI = getExistingFileInfo(File);
492  return FI && FI->isImport;
493  }
494 
495  /// This method returns a HeaderMap for the specified
496  /// FileEntry, uniquing them through the 'HeaderMaps' datastructure.
497  const HeaderMap *CreateHeaderMap(const FileEntry *FE);
498 
499  /// Get filenames for all registered header maps.
500  void getHeaderMapFileNames(SmallVectorImpl<std::string> &Names) const;
501 
502  /// Retrieve the name of the cached module file that should be used
503  /// to load the given module.
504  ///
505  /// \param Module The module whose module file name will be returned.
506  ///
507  /// \returns The name of the module file that corresponds to this module,
508  /// or an empty string if this module does not correspond to any module file.
509  std::string getCachedModuleFileName(Module *Module);
510 
511  /// Retrieve the name of the prebuilt module file that should be used
512  /// to load a module with the given name.
513  ///
514  /// \param ModuleName The module whose module file name will be returned.
515  ///
516  /// \param FileMapOnly If true, then only look in the explicit module name
517  // to file name map and skip the directory search.
518  ///
519  /// \returns The name of the module file that corresponds to this module,
520  /// or an empty string if this module does not correspond to any module file.
521  std::string getPrebuiltModuleFileName(StringRef ModuleName,
522  bool FileMapOnly = false);
523 
524  /// Retrieve the name of the prebuilt module file that should be used
525  /// to load the given module.
526  ///
527  /// \param Module The module whose module file name will be returned.
528  ///
529  /// \returns The name of the module file that corresponds to this module,
530  /// or an empty string if this module does not correspond to any module file.
531  std::string getPrebuiltImplicitModuleFileName(Module *Module);
532 
533  /// Retrieve the name of the (to-be-)cached module file that should
534  /// be used to load a module with the given name.
535  ///
536  /// \param ModuleName The module whose module file name will be returned.
537  ///
538  /// \param ModuleMapPath A path that when combined with \c ModuleName
539  /// uniquely identifies this module. See Module::ModuleMap.
540  ///
541  /// \returns The name of the module file that corresponds to this module,
542  /// or an empty string if this module does not correspond to any module file.
543  std::string getCachedModuleFileName(StringRef ModuleName,
544  StringRef ModuleMapPath);
545 
546  /// Lookup a module Search for a module with the given name.
547  ///
548  /// \param ModuleName The name of the module we're looking for.
549  ///
550  /// \param AllowSearch Whether we are allowed to search in the various
551  /// search directories to produce a module definition. If not, this lookup
552  /// will only return an already-known module.
553  ///
554  /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps
555  /// in subdirectories.
556  ///
557  /// \returns The module with the given name.
558  Module *lookupModule(StringRef ModuleName, bool AllowSearch = true,
559  bool AllowExtraModuleMapSearch = false);
560 
561  /// Try to find a module map file in the given directory, returning
562  /// \c nullptr if none is found.
563  const FileEntry *lookupModuleMapFile(const DirectoryEntry *Dir,
564  bool IsFramework);
565 
566  /// Determine whether there is a module map that may map the header
567  /// with the given file name to a (sub)module.
568  /// Always returns false if modules are disabled.
569  ///
570  /// \param Filename The name of the file.
571  ///
572  /// \param Root The "root" directory, at which we should stop looking for
573  /// module maps.
574  ///
575  /// \param IsSystem Whether the directories we're looking at are system
576  /// header directories.
577  bool hasModuleMap(StringRef Filename, const DirectoryEntry *Root,
578  bool IsSystem);
579 
580  /// Retrieve the module that corresponds to the given file, if any.
581  ///
582  /// \param File The header that we wish to map to a module.
583  /// \param AllowTextual Whether we want to find textual headers too.
584  ModuleMap::KnownHeader findModuleForHeader(const FileEntry *File,
585  bool AllowTextual = false) const;
586 
587  /// Retrieve all the modules corresponding to the given file.
588  ///
589  /// \ref findModuleForHeader should typically be used instead of this.
591  findAllModulesForHeader(const FileEntry *File) const;
592 
593  /// Read the contents of the given module map file.
594  ///
595  /// \param File The module map file.
596  /// \param IsSystem Whether this file is in a system header directory.
597  /// \param ID If the module map file is already mapped (perhaps as part of
598  /// processing a preprocessed module), the ID of the file.
599  /// \param Offset [inout] An offset within ID to start parsing. On exit,
600  /// filled by the end of the parsed contents (either EOF or the
601  /// location of an end-of-module-map pragma).
602  /// \param OriginalModuleMapFile The original path to the module map file,
603  /// used to resolve paths within the module (this is required when
604  /// building the module from preprocessed source).
605  /// \returns true if an error occurred, false otherwise.
606  bool loadModuleMapFile(const FileEntry *File, bool IsSystem,
607  FileID ID = FileID(), unsigned *Offset = nullptr,
608  StringRef OriginalModuleMapFile = StringRef());
609 
610  /// Collect the set of all known, top-level modules.
611  ///
612  /// \param Modules Will be filled with the set of known, top-level modules.
613  void collectAllModules(SmallVectorImpl<Module *> &Modules);
614 
615  /// Load all known, top-level system modules.
616  void loadTopLevelSystemModules();
617 
618 private:
619  /// Lookup a module with the given module name and search-name.
620  ///
621  /// \param ModuleName The name of the module we're looking for.
622  ///
623  /// \param SearchName The "search-name" to derive filesystem paths from
624  /// when looking for the module map; this is usually equal to ModuleName,
625  /// but for compatibility with some buggy frameworks, additional attempts
626  /// may be made to find the module under a related-but-different search-name.
627  ///
628  /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps
629  /// in subdirectories.
630  ///
631  /// \returns The module named ModuleName.
632  Module *lookupModule(StringRef ModuleName, StringRef SearchName,
633  bool AllowExtraModuleMapSearch = false);
634 
635  /// Retrieve the name of the (to-be-)cached module file that should
636  /// be used to load a module with the given name.
637  ///
638  /// \param ModuleName The module whose module file name will be returned.
639  ///
640  /// \param ModuleMapPath A path that when combined with \c ModuleName
641  /// uniquely identifies this module. See Module::ModuleMap.
642  ///
643  /// \param CachePath A path to the module cache.
644  ///
645  /// \returns The name of the module file that corresponds to this module,
646  /// or an empty string if this module does not correspond to any module file.
647  std::string getCachedModuleFileNameImpl(StringRef ModuleName,
648  StringRef ModuleMapPath,
649  StringRef CachePath);
650 
651  /// Retrieve a module with the given name, which may be part of the
652  /// given framework.
653  ///
654  /// \param Name The name of the module to retrieve.
655  ///
656  /// \param Dir The framework directory (e.g., ModuleName.framework).
657  ///
658  /// \param IsSystem Whether the framework directory is part of the system
659  /// frameworks.
660  ///
661  /// \returns The module, if found; otherwise, null.
662  Module *loadFrameworkModule(StringRef Name,
663  const DirectoryEntry *Dir,
664  bool IsSystem);
665 
666  /// Load all of the module maps within the immediate subdirectories
667  /// of the given search directory.
668  void loadSubdirectoryModuleMaps(DirectoryLookup &SearchDir);
669 
670  /// Find and suggest a usable module for the given file.
671  ///
672  /// \return \c true if the file can be used, \c false if we are not permitted to
673  /// find this file due to requirements from \p RequestingModule.
674  bool findUsableModuleForHeader(const FileEntry *File,
675  const DirectoryEntry *Root,
676  Module *RequestingModule,
677  ModuleMap::KnownHeader *SuggestedModule,
678  bool IsSystemHeaderDir);
679 
680  /// Find and suggest a usable module for the given file, which is part of
681  /// the specified framework.
682  ///
683  /// \return \c true if the file can be used, \c false if we are not permitted to
684  /// find this file due to requirements from \p RequestingModule.
685  bool findUsableModuleForFrameworkHeader(
686  const FileEntry *File, StringRef FrameworkName, Module *RequestingModule,
687  ModuleMap::KnownHeader *SuggestedModule, bool IsSystemFramework);
688 
689  /// Look up the file with the specified name and determine its owning
690  /// module.
692  getFileAndSuggestModule(StringRef FileName, SourceLocation IncludeLoc,
693  const DirectoryEntry *Dir, bool IsSystemHeaderDir,
694  Module *RequestingModule,
695  ModuleMap::KnownHeader *SuggestedModule);
696 
697 public:
698  /// Retrieve the module map.
699  ModuleMap &getModuleMap() { return ModMap; }
700 
701  /// Retrieve the module map.
702  const ModuleMap &getModuleMap() const { return ModMap; }
703 
704  unsigned header_file_size() const { return FileInfo.size(); }
705 
706  /// Return the HeaderFileInfo structure for the specified FileEntry,
707  /// in preparation for updating it in some way.
708  HeaderFileInfo &getFileInfo(const FileEntry *FE);
709 
710  /// Return the HeaderFileInfo structure for the specified FileEntry,
711  /// if it has ever been filled in.
712  /// \param WantExternal Whether the caller wants purely-external header file
713  /// info (where \p External is true).
714  const HeaderFileInfo *getExistingFileInfo(const FileEntry *FE,
715  bool WantExternal = true) const;
716 
717  // Used by external tools
718  using search_dir_iterator = std::vector<DirectoryLookup>::const_iterator;
719 
720  search_dir_iterator search_dir_begin() const { return SearchDirs.begin(); }
721  search_dir_iterator search_dir_end() const { return SearchDirs.end(); }
722  unsigned search_dir_size() const { return SearchDirs.size(); }
723 
725  return SearchDirs.begin();
726  }
727 
729  return SearchDirs.begin() + AngledDirIdx;
730  }
731 
733  return SearchDirs.begin() + AngledDirIdx;
734  }
735 
737  return SearchDirs.begin() + SystemDirIdx;
738  }
739 
741  return SearchDirs.begin() + SystemDirIdx;
742  }
743 
744  search_dir_iterator system_dir_end() const { return SearchDirs.end(); }
745 
746  /// Retrieve a uniqued framework name.
747  StringRef getUniqueFrameworkName(StringRef Framework);
748 
749  /// Suggest a path by which the specified file could be found, for use in
750  /// diagnostics to suggest a #include. Returned path will only contain forward
751  /// slashes as separators. MainFile is the absolute path of the file that we
752  /// are generating the diagnostics for. It will try to shorten the path using
753  /// MainFile location, if none of the include search directories were prefix
754  /// of File.
755  ///
756  /// \param IsSystem If non-null, filled in to indicate whether the suggested
757  /// path is relative to a system header directory.
758  std::string suggestPathToFileForDiagnostics(const FileEntry *File,
759  llvm::StringRef MainFile,
760  bool *IsSystem = nullptr);
761 
762  /// Suggest a path by which the specified file could be found, for use in
763  /// diagnostics to suggest a #include. Returned path will only contain forward
764  /// slashes as separators. MainFile is the absolute path of the file that we
765  /// are generating the diagnostics for. It will try to shorten the path using
766  /// MainFile location, if none of the include search directories were prefix
767  /// of File.
768  ///
769  /// \param WorkingDir If non-empty, this will be prepended to search directory
770  /// paths that are relative.
771  std::string suggestPathToFileForDiagnostics(llvm::StringRef File,
772  llvm::StringRef WorkingDir,
773  llvm::StringRef MainFile,
774  bool *IsSystem = nullptr);
775 
776  void PrintStats();
777 
778  size_t getTotalMemory() const;
779 
780 private:
781  /// Describes what happened when we tried to load a module map file.
782  enum LoadModuleMapResult {
783  /// The module map file had already been loaded.
784  LMM_AlreadyLoaded,
785 
786  /// The module map file was loaded by this invocation.
787  LMM_NewlyLoaded,
788 
789  /// There is was directory with the given name.
790  LMM_NoDirectory,
791 
792  /// There was either no module map file or the module map file was
793  /// invalid.
794  LMM_InvalidModuleMap
795  };
796 
797  LoadModuleMapResult loadModuleMapFileImpl(const FileEntry *File,
798  bool IsSystem,
799  const DirectoryEntry *Dir,
800  FileID ID = FileID(),
801  unsigned *Offset = nullptr);
802 
803  /// Try to load the module map file in the given directory.
804  ///
805  /// \param DirName The name of the directory where we will look for a module
806  /// map file.
807  /// \param IsSystem Whether this is a system header directory.
808  /// \param IsFramework Whether this is a framework directory.
809  ///
810  /// \returns The result of attempting to load the module map file from the
811  /// named directory.
812  LoadModuleMapResult loadModuleMapFile(StringRef DirName, bool IsSystem,
813  bool IsFramework);
814 
815  /// Try to load the module map file in the given directory.
816  ///
817  /// \param Dir The directory where we will look for a module map file.
818  /// \param IsSystem Whether this is a system header directory.
819  /// \param IsFramework Whether this is a framework directory.
820  ///
821  /// \returns The result of attempting to load the module map file from the
822  /// named directory.
823  LoadModuleMapResult loadModuleMapFile(const DirectoryEntry *Dir,
824  bool IsSystem, bool IsFramework);
825 };
826 
827 } // namespace clang
828 
829 #endif // LLVM_CLANG_LEX_HEADERSEARCH_H
unsigned DirInfo
Keep track of whether this is a system header, and if so, whether it is C++ clean or not.
Definition: HeaderSearch.h:61
Implements support for file system lookup, file system caching, and directory search management.
Definition: FileManager.h:53
unsigned isPragmaOnce
True if this is a #pragma once file.
Definition: HeaderSearch.h:55
Defines the SourceManager interface.
void SetSearchPaths(const std::vector< DirectoryLookup > &dirs, unsigned angledDirIdx, unsigned systemDirIdx, bool noCurDirSearch)
Interface for setting the file search paths.
Definition: HeaderSearch.h:272
StringRef P
search_dir_iterator angled_dir_end() const
Definition: HeaderSearch.h:736
FrameworkCacheEntry & LookupFrameworkCache(StringRef FWName)
Look up the specified framework name in our framework cache.
Definition: HeaderSearch.h:423
bool HasIncludeAliasMap() const
Checks whether the map exists or not.
Definition: HeaderSearch.h:299
CharacteristicKind
Indicates whether a file or directory holds normal user code, system code, or system code which is im...
Definition: SourceManager.h:78
ModuleMap & getModuleMap()
Retrieve the module map.
Definition: HeaderSearch.h:699
unsigned isCompilingModuleHeader
Whether this header is part of the module that we are building.
Definition: HeaderSearch.h:71
unsigned isImport
True if this is a #import'd or #pragma once file.
Definition: HeaderSearch.h:52
void ClearFileInfo()
Forget everything we know about headers so far.
Definition: HeaderSearch.h:345
StringRef getModuleHash() const
Retrieve the module hash.
Definition: HeaderSearch.h:334
DiagnosticsEngine & getDiags() const
Definition: HeaderSearch.h:269
One of these records is kept for each identifier that is lexed.
This class represents an Apple concept known as a 'header map'.
Definition: HeaderMap.h:65
FileManager & getFileMgr() const
Definition: HeaderSearch.h:267
const IdentifierInfo * getControllingMacro(ExternalPreprocessorSource *External)
Retrieve the controlling macro for this header file, if any.
Describes a module or submodule.
Definition: Module.h:96
unsigned External
Whether this header file info was supplied by an external source, and has not changed since.
Definition: HeaderSearch.h:65
void setModuleHash(StringRef Hash)
Set the hash to use for module cache paths.
Definition: HeaderSearch.h:326
void AddIncludeAlias(StringRef Source, StringRef Dest)
Map the source include name to the dest include name.
Definition: HeaderSearch.h:305
bool IsUserSpecifiedSystemFramework
Whether this framework has been "user-specified" to be treated as if it were a system framework (even...
Definition: HeaderSearch.h:153
search_dir_iterator search_dir_begin() const
Definition: HeaderSearch.h:720
search_dir_iterator quoted_dir_end() const
Definition: HeaderSearch.h:728
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:191
unsigned short NumIncludes
The number of times the file has been included already.
Definition: HeaderSearch.h:90
search_dir_iterator search_dir_end() const
Definition: HeaderSearch.h:721
unsigned Resolved
Whether this structure is considered to already have been "resolved", meaning that it was loaded from...
Definition: HeaderSearch.h:75
virtual HeaderFileInfo GetHeaderFileInfo(const FileEntry *FE)=0
Retrieve the header file information for the given file entry.
The preprocessor keeps track of this information for each file that is #included.
Definition: HeaderSearch.h:50
unsigned header_file_size() const
Definition: HeaderSearch.h:704
Encapsulates the information needed to find the file referenced by a #include or #include_next,...
Definition: HeaderSearch.h:158
StringRef getModuleCachePath() const
Retrieve the path to the module cache.
Definition: HeaderSearch.h:337
const ModuleMap & getModuleMap() const
Retrieve the module map.
Definition: HeaderSearch.h:702
ModuleHeaderRole
Flags describing the role of a module header.
Definition: ModuleMap.h:128
StringRef Filename
Definition: Format.cpp:2070
unsigned Offset
Definition: Format.cpp:2072
Exposes information about the current target.
Definition: TargetInfo.h:179
Abstract interface for external sources of preprocessor information.
bool hasFileBeenImported(const FileEntry *File)
Determine whether the given file is known to have ever been #imported (or if it has been #included an...
Definition: HeaderSearch.h:490
HeaderSearchOptions & getHeaderSearchOpts() const
Retrieve the header-search options with which this header search was initialized.
Definition: HeaderSearch.h:265
search_dir_iterator quoted_dir_begin() const
Definition: HeaderSearch.h:724
search_dir_iterator system_dir_end() const
Definition: HeaderSearch.h:744
void IncrementIncludeCount(const FileEntry *File)
Increment the count for the number of times the specified FileEntry has been entered.
Definition: HeaderSearch.h:463
DirectoryLookup - This class represents one entry in the search list that specifies the search order ...
const DirectoryEntry * Directory
The directory entry which should be used for the cached framework.
Definition: HeaderSearch.h:148
SrcMgr::CharacteristicKind getFileDirFlavor(const FileEntry *File)
Return whether the specified file is a normal header, a system header, or a C++ friendly system heade...
Definition: HeaderSearch.h:438
unsigned isModuleHeader
Whether this header is part of a module.
Definition: HeaderSearch.h:68
#define false
Definition: stdbool.h:17
Encodes a location in the source.
search_dir_iterator system_dir_begin() const
Definition: HeaderSearch.h:740
Cached information about one file (either on disk or in the virtual file system).
Definition: FileEntry.h:276
const IdentifierInfo * ControllingMacro
If this file has a #ifndef XXX (or equivalent) guard that protects the entire contents of the file,...
Definition: HeaderSearch.h:107
An opaque identifier used by SourceManager which refers to a source file (MemoryBuffer) along with it...
unsigned ControllingMacroID
The ID number of the controlling macro.
Definition: HeaderSearch.h:97
Dataflow Directional Tag Classes.
An external source of header file information, which may supply information about header files alread...
Definition: HeaderSearch.h:133
bool isNonDefault() const
Determine whether this is a non-default header file info, e.g., it corresponds to an actual header we...
Definition: HeaderSearch.h:125
void SetExternalSource(ExternalHeaderFileInfoSource *ES)
Set the external source of header information.
Definition: HeaderSearch.h:358
std::vector< DirectoryLookup >::const_iterator search_dir_iterator
Definition: HeaderSearch.h:718
void AddSearchPath(const DirectoryLookup &dir, bool isAngled)
Add an additional search path.
Definition: HeaderSearch.h:285
search_dir_iterator angled_dir_begin() const
Definition: HeaderSearch.h:732
Cached information about one directory (either on disk or in the virtual file system).
StringRef Framework
If this header came from a framework include, this is the name of the framework.
Definition: HeaderSearch.h:111
HeaderSearch(std::shared_ptr< HeaderSearchOptions > HSOpts, SourceManager &SourceMgr, DiagnosticsEngine &Diags, const LangOptions &LangOpts, const TargetInfo *Target)
Defines the clang::SourceLocation class and associated facilities.
void setDirectoryHasModuleMap(const DirectoryEntry *Dir)
Consider modules when including files from this directory.
Definition: HeaderSearch.h:340
void SetSystemHeaderPrefixes(ArrayRef< std::pair< std::string, bool >> P)
Set the list of system header prefixes.
Definition: HeaderSearch.h:294
HeaderSearchOptions - Helper class for storing options related to the initialization of the HeaderSea...
StringRef MapHeaderToIncludeAlias(StringRef Source)
Maps one header file name to a different header file name, for use with the include_alias pragma.
Definition: HeaderSearch.h:315
HeaderSearch & operator=(const HeaderSearch &)=delete
bool FirstTimeLexingFile(const FileEntry *File)
Return true if this is the first time encountering this header.
Definition: HeaderSearch.h:477
void SetExternalLookup(ExternalPreprocessorSource *EPS)
Definition: HeaderSearch.h:349
unsigned IndexHeaderMapHeader
Whether this is a header inside a framework that is currently being built.
Definition: HeaderSearch.h:84
unsigned IsValid
Whether this file has been looked up as a header.
Definition: HeaderSearch.h:87
void MarkFileSystemHeader(const FileEntry *File)
Mark the specified file as a system header, e.g.
Definition: HeaderSearch.h:452
This structure is used to record entries in our framework cache.
Definition: HeaderSearch.h:146
unsigned search_dir_size() const
Definition: HeaderSearch.h:722
A header that is known to reside within a given module, whether it was included or excluded.
Definition: ModuleMap.h:155
void MarkFileIncludeOnce(const FileEntry *File)
Mark the specified file as a "once only" file, e.g.
Definition: HeaderSearch.h:444
void setModuleCachePath(StringRef CachePath)
Set the path to the module cache.
Definition: HeaderSearch.h:329
ExternalPreprocessorSource * getExternalLookup() const
Definition: HeaderSearch.h:353
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:129
void SetFileControllingMacro(const FileEntry *File, const IdentifierInfo *ControllingMacro)
Mark the specified file as having a controlling macro.
Definition: HeaderSearch.h:471