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
16#include "clang/Basic/SourceLocation.h"
17#include "clang/Basic/SourceManager.h"
18#include "clang/Lex/DirectoryLookup.h"
19#include "clang/Lex/ExternalPreprocessorSource.h"
20#include "clang/Lex/HeaderMap.h"
21#include "clang/Lex/ModuleMap.h"
22#include "llvm/ADT/ArrayRef.h"
23#include "llvm/ADT/DenseMap.h"
24#include "llvm/ADT/MapVector.h"
25#include "llvm/ADT/SmallPtrSet.h"
26#include "llvm/ADT/SmallString.h"
27#include "llvm/ADT/StringMap.h"
28#include "llvm/ADT/StringRef.h"
29#include "llvm/ADT/StringSet.h"
30#include "llvm/Support/Allocator.h"
31#include <cassert>
32#include <cstddef>
33#include <memory>
34#include <string>
35#include <utility>
36#include <vector>
37
38namespace llvm {
39
40class Triple;
41
42} // namespace llvm
43
44namespace clang {
45
46class DiagnosticsEngine;
47class DirectoryEntry;
48class ExternalPreprocessorSource;
49class FileEntry;
50class FileManager;
51class HeaderSearch;
52class HeaderSearchOptions;
53class IdentifierInfo;
54class LangOptions;
55class Module;
56class Preprocessor;
57class TargetInfo;
58
59/// The preprocessor keeps track of this information for each
60/// file that is \#included.
61struct HeaderFileInfo {
62 // TODO: Whether the file was included is not a property of the file itself.
63 // It's a preprocessor state, move it there.
64 /// True if this file has been included (or imported) **locally**.
65 LLVM_PREFERRED_TYPE(bool)
66 unsigned IsLocallyIncluded : 1;
67
68 // TODO: Whether the file was imported is not a property of the file itself.
69 // It's a preprocessor state, move it there.
70 /// True if this is a \#import'd file.
71 LLVM_PREFERRED_TYPE(bool)
72 unsigned isImport : 1;
73
74 /// True if this is a \#pragma once file.
75 LLVM_PREFERRED_TYPE(bool)
76 unsigned isPragmaOnce : 1;
77
78 /// Keep track of whether this is a system header, and if so,
79 /// whether it is C++ clean or not. This can be set by the include paths or
80 /// by \#pragma gcc system_header. This is an instance of
81 /// SrcMgr::CharacteristicKind.
82 LLVM_PREFERRED_TYPE(SrcMgr::CharacteristicKind)
83 unsigned DirInfo : 3;
84
85 /// Whether this header file info was supplied by an external source,
86 /// and has not changed since.
87 LLVM_PREFERRED_TYPE(bool)
88 unsigned External : 1;
89
90 /// Whether this header is part of and built with a module. i.e. it is listed
91 /// in a module map, and is not `excluded` or `textual`. (same meaning as
92 /// `ModuleMap::isModular()`).
93 LLVM_PREFERRED_TYPE(bool)
94 unsigned isModuleHeader : 1;
95
96 /// Whether this header is a `textual header` in a module. If a header is
97 /// textual in one module and normal in another module, this bit will not be
98 /// set, only `isModuleHeader`.
99 LLVM_PREFERRED_TYPE(bool)
100 unsigned isTextualModuleHeader : 1;
101
102 /// Whether this header is part of the module that we are building, even if it
103 /// doesn't build with the module. i.e. this will include `excluded` and
104 /// `textual` headers as well as normal headers.
105 LLVM_PREFERRED_TYPE(bool)
106 unsigned isCompilingModuleHeader : 1;
107
108 /// Whether this structure is considered to already have been
109 /// "resolved", meaning that it was loaded from the external source.
110 LLVM_PREFERRED_TYPE(bool)
111 unsigned Resolved : 1;
112
113 /// Whether this file has been looked up as a header.
114 LLVM_PREFERRED_TYPE(bool)
115 unsigned IsValid : 1;
116
117 /// If this file has a \#ifndef XXX (or equivalent) guard that
118 /// protects the entire contents of the file, this is the identifier
119 /// for the macro that controls whether or not it has any effect.
120 ///
121 /// Note: Most clients should use getControllingMacro() to access
122 /// the controlling macro of this header, since
123 /// getControllingMacro() is able to load a controlling macro from
124 /// external storage.
125 LazyIdentifierInfoPtr LazyControllingMacro;
126
127 HeaderFileInfo()
128 : IsLocallyIncluded(false), isImport(false), isPragmaOnce(false),
129 DirInfo(SrcMgr::C_User), External(false), isModuleHeader(false),
130 isTextualModuleHeader(false), isCompilingModuleHeader(false),
131 Resolved(false), IsValid(false) {}
132
133 /// Retrieve the controlling macro for this header file, if
134 /// any.
135 const IdentifierInfo *
136 getControllingMacro(ExternalPreprocessorSource *External);
137
138 /// Update the module membership bits based on the header role.
139 ///
140 /// isModuleHeader will potentially be set, but not cleared.
141 /// isTextualModuleHeader will be set or cleared based on the role update.
142 void mergeModuleMembership(ModuleMap::ModuleHeaderRole Role);
143};
144
145static_assert(sizeof(HeaderFileInfo) <= 16);
146
147/// An external source of header file information, which may supply
148/// information about header files already included.
149class ExternalHeaderFileInfoSource {
150public:
151 virtual ~ExternalHeaderFileInfoSource();
152
153 /// Retrieve the header file information for the given file entry.
154 ///
155 /// \returns Header file information for the given file entry, with the
156 /// \c External bit set. If the file entry is not known, return a
157 /// default-constructed \c HeaderFileInfo.
158 virtual HeaderFileInfo GetHeaderFileInfo(FileEntryRef FE) = 0;
159};
160
161/// This structure is used to record entries in our framework cache.
162struct FrameworkCacheEntry {
163 /// The directory entry which should be used for the cached framework.
164 OptionalDirectoryEntryRef Directory;
165
166 /// Whether this framework has been "user-specified" to be treated as if it
167 /// were a system framework (even if it was found outside a system framework
168 /// directory).
169 bool IsUserSpecifiedSystemFramework;
170};
171
172namespace detail {
173template <bool Const, typename T>
174using Qualified = std::conditional_t<Const, const T, T>;
175
176/// Forward iterator over the search directories of \c HeaderSearch.
177template <bool IsConst>
178struct SearchDirIteratorImpl
179 : llvm::iterator_facade_base<SearchDirIteratorImpl<IsConst>,
180 std::forward_iterator_tag,
181 Qualified<IsConst, DirectoryLookup>> {
182 /// Const -> non-const iterator conversion.
183 template <typename Enable = std::enable_if<IsConst, bool>>
184 SearchDirIteratorImpl(const SearchDirIteratorImpl<false> &Other)
185 : HS(Other.HS), Idx(Other.Idx) {}
186
187 SearchDirIteratorImpl(const SearchDirIteratorImpl &) = default;
188
189 SearchDirIteratorImpl &operator=(const SearchDirIteratorImpl &) = default;
190
191 bool operator==(const SearchDirIteratorImpl &RHS) const {
192 return HS == RHS.HS && Idx == RHS.Idx;
193 }
194
195 SearchDirIteratorImpl &operator++() {
196 assert(*this && "Invalid iterator.");
197 ++Idx;
198 return *this;
199 }
200
201 Qualified<IsConst, DirectoryLookup> &operator*() const {
202 assert(*this && "Invalid iterator.");
203 return HS->SearchDirs[Idx];
204 }
205
206 /// Creates an invalid iterator.
207 SearchDirIteratorImpl(std::nullptr_t) : HS(nullptr), Idx(0) {}
208
209 /// Checks whether the iterator is valid.
210 explicit operator bool() const { return HS != nullptr; }
211
212private:
213 /// The parent \c HeaderSearch. This is \c nullptr for invalid iterator.
214 Qualified<IsConst, HeaderSearch> *HS;
215
216 /// The index of the current element.
217 size_t Idx;
218
219 /// The constructor that creates a valid iterator.
220 SearchDirIteratorImpl(Qualified<IsConst, HeaderSearch> &HS, size_t Idx)
221 : HS(&HS), Idx(Idx) {}
222
223 /// Only HeaderSearch is allowed to instantiate valid iterators.
224 friend HeaderSearch;
225
226 /// Enables const -> non-const conversion.
227 friend SearchDirIteratorImpl<!IsConst>;
228};
229} // namespace detail
230
231using ConstSearchDirIterator = detail::SearchDirIteratorImpl<true>;
232using SearchDirIterator = detail::SearchDirIteratorImpl<false>;
233
234using ConstSearchDirRange = llvm::iterator_range<ConstSearchDirIterator>;
235using SearchDirRange = llvm::iterator_range<SearchDirIterator>;
236
237/// Encapsulates the information needed to find the file referenced
238/// by a \#include or \#include_next, (sub-)framework lookup, etc.
239class HeaderSearch {
240 friend class DirectoryLookup;
241
242 friend ConstSearchDirIterator;
243 friend SearchDirIterator;
244
245 /// Header-search options used to initialize this header search.
246 const HeaderSearchOptions &HSOpts;
247
248 /// Mapping from SearchDir to HeaderSearchOptions::UserEntries indices.
249 llvm::DenseMap<unsigned, unsigned> SearchDirToHSEntry;
250
251 DiagnosticsEngine &Diags;
252 FileManager &FileMgr;
253
254 /// \#include search path information. Requests for \#include "x" search the
255 /// directory of the \#including file first, then each directory in SearchDirs
256 /// consecutively. Requests for <x> search the current dir first, then each
257 /// directory in SearchDirs, starting at AngledDirIdx, consecutively.
258 std::vector<DirectoryLookup> SearchDirs;
259 /// Whether the DirectoryLookup at the corresponding index in SearchDirs has
260 /// been successfully used to lookup a file.
261 std::vector<bool> SearchDirsUsage;
262 unsigned AngledDirIdx = 0;
263 unsigned SystemDirIdx = 0;
264
265 /// Maps HeaderMap keys to SearchDir indices. When HeaderMaps are used
266 /// heavily, SearchDirs can start with thousands of HeaderMaps, so this Index
267 /// lets us avoid scanning them all to find a match.
268 llvm::StringMap<unsigned, llvm::BumpPtrAllocator> SearchDirHeaderMapIndex;
269
270 /// The index of the first SearchDir that isn't a header map.
271 unsigned FirstNonHeaderMapSearchDirIdx = 0;
272
273 /// \#include prefixes for which the 'system header' property is
274 /// overridden.
275 ///
276 /// For a \#include "x" or \#include \<x> directive, the last string in this
277 /// list which is a prefix of 'x' determines whether the file is treated as
278 /// a system header.
279 std::vector<std::pair<std::string, bool>> SystemHeaderPrefixes;
280
281 /// The context hash used in SpecificModuleCachePath (unless suppressed).
282 std::string ContextHash;
283
284 /// The specific module cache path containing ContextHash (unless suppressed).
285 std::string SpecificModuleCachePath;
286
287 /// The length of the normalized module cache path at the start of \c
288 /// SpecificModuleCachePath.
289 size_t NormalizedModuleCachePathLen = 0;
290
291 /// All the preprocessor-specific data about files that are included.
292 mutable llvm::MapVector<FileEntryRef, HeaderFileInfo> FileInfo;
293
294 /// Keeps track of each lookup performed by LookupFile.
295 struct LookupFileCacheInfo {
296 // The requesting module for the lookup we cached.
297 const Module *RequestingModule = nullptr;
298
299 /// Starting search directory iterator that the cached search was performed
300 /// from. If there is a hit and this value doesn't match the current query,
301 /// the cache has to be ignored.
302 ConstSearchDirIterator StartIt = nullptr;
303
304 /// The search directory iterator that satisfied the query.
305 ConstSearchDirIterator HitIt = nullptr;
306
307 /// This is non-null if the original filename was mapped to a framework
308 /// include via a headermap.
309 const char *MappedName = nullptr;
310
311 /// Default constructor -- Initialize all members with zero.
312 LookupFileCacheInfo() = default;
313
314 void reset(const Module *NewRequestingModule,
315 ConstSearchDirIterator NewStartIt) {
316 RequestingModule = NewRequestingModule;
317 StartIt = NewStartIt;
318 MappedName = nullptr;
319 }
320 };
321 llvm::StringMap<LookupFileCacheInfo, llvm::BumpPtrAllocator> LookupFileCache;
322
323 /// The files that were already considered for the \c -Wshadow-header
324 /// diagnostic, keyed by the spelling of the include that resolved to them.
325 /// Since the set of shadowing candidates depends on the spelling, the same
326 /// file has to be considered once per spelling it was found under.
327 llvm::StringMap<llvm::SmallPtrSet<const FileEntry *, 1>> ShadowCheckedHeaders;
328
329 /// Collection mapping a framework or subframework
330 /// name like "Carbon" to the Carbon.framework directory.
331 llvm::StringMap<FrameworkCacheEntry, llvm::BumpPtrAllocator> FrameworkMap;
332
333 /// Maps include file names (including the quotes or
334 /// angle brackets) to other include file names. This is used to support the
335 /// include_alias pragma for Microsoft compatibility.
336 using IncludeAliasMap =
337 llvm::StringMap<std::string, llvm::BumpPtrAllocator>;
338 std::unique_ptr<IncludeAliasMap> IncludeAliases;
339
340 /// This is a mapping from FileEntry -> HeaderMap, uniquing headermaps.
341 std::vector<std::pair<FileEntryRef, std::unique_ptr<HeaderMap>>> HeaderMaps;
342
343 /// The mapping between modules and headers.
344 mutable ModuleMap ModMap;
345
346 struct ModuleMapDirectoryState {
347 OptionalFileEntryRef ModuleMapFile;
348 OptionalFileEntryRef PrivateModuleMapFile;
349 enum {
350 Parsed,
351 Loaded,
352 Invalid,
353 } Status;
354
355 /// Relative header path -> list of module names
356 llvm::StringMap<llvm::SmallVector<StringRef, 1>> HeaderToModules{};
357 /// Relative dir path -> module name
358 llvm::SmallVector<std::pair<std::string, StringRef>, 2>
359 UmbrellaDirModules{};
360 /// List of module names with umbrella header decls
361 llvm::SmallVector<StringRef, 2> UmbrellaHeaderModules{};
362 };
363
364 /// Describes whether a given directory has a module map in it.
365 llvm::DenseMap<const DirectoryEntry *, ModuleMapDirectoryState>
366 DirectoryModuleMap;
367
368 /// Set of module map files we've already loaded, and a flag indicating
369 /// whether they were valid or not.
370 llvm::DenseMap<const FileEntry *, bool> LoadedModuleMaps;
371
372 /// Set of module map files we've already parsed, and a flag indicating
373 /// whether they were valid or not.
374 llvm::DenseMap<const FileEntry *, bool> ParsedModuleMaps;
375
376 // A map of discovered headers with their associated include file name.
377 llvm::DenseMap<const FileEntry *, llvm::SmallString<64>> IncludeNames;
378
379 /// Uniqued set of framework names, which is used to track which
380 /// headers were included as framework headers.
381 llvm::StringSet<llvm::BumpPtrAllocator> FrameworkNames;
382
383 /// Entity used to resolve the identifier IDs of controlling
384 /// macros into IdentifierInfo pointers, and keep the identifire up to date,
385 /// as needed.
386 ExternalPreprocessorSource *ExternalLookup = nullptr;
387
388 /// Entity used to look up stored header file information.
389 ExternalHeaderFileInfoSource *ExternalSource = nullptr;
390
391 /// Scan all of the header maps at the beginning of SearchDirs and
392 /// map their keys to the SearchDir index of their header map.
393 void indexInitialHeaderMaps();
394
395 /// Build the module map index for a directory's module map.
396 ///
397 /// This fills a ModuleMapDirectoryState with index information from its
398 /// directory's module map.
399 void buildModuleMapIndex(DirectoryEntryRef Dir,
400 ModuleMapDirectoryState &MMState);
401
402 void processModuleMapForIndex(const modulemap::ModuleMapFile &MMF,
403 DirectoryEntryRef MMDir, StringRef PathPrefix,
404 ModuleMapDirectoryState &MMState);
405
406 void processExternModuleDeclForIndex(const modulemap::ExternModuleDecl &EMD,
407 DirectoryEntryRef MMDir,
408 StringRef PathPrefix,
409 ModuleMapDirectoryState &MMState);
410
411 void processModuleDeclForIndex(const modulemap::ModuleDecl &MD,
412 StringRef ModuleName, DirectoryEntryRef MMDir,
413 StringRef PathPrefix,
414 ModuleMapDirectoryState &MMState);
415
416 void addToModuleMapIndex(StringRef RelPath, StringRef ModuleName,
417 StringRef PathPrefix,
418 ModuleMapDirectoryState &MMState);
419
420 /// Check if a relative path would be covered by the module map index.
421 /// Returns the module names that would cover this path.
422 SmallVector<StringRef, 1>
423 findMatchingModulesInIndex(StringRef RelativePath,
424 const ModuleMapDirectoryState &MMState) const;
425
426public:
427 HeaderSearch(const HeaderSearchOptions &HSOpts, SourceManager &SourceMgr,
428 DiagnosticsEngine &Diags, const LangOptions &LangOpts,
429 const TargetInfo *Target);
430 HeaderSearch(const HeaderSearch &) = delete;
431 HeaderSearch &operator=(const HeaderSearch &) = delete;
432
433 /// Retrieve the header-search options with which this header search
434 /// was initialized.
435 const HeaderSearchOptions &getHeaderSearchOpts() const { return HSOpts; }
436
437 FileManager &getFileMgr() const { return FileMgr; }
438
439 DiagnosticsEngine &getDiags() const { return Diags; }
440
441 /// Interface for setting the file search paths.
442 void SetSearchPaths(std::vector<DirectoryLookup> dirs, unsigned angledDirIdx,
443 unsigned systemDirIdx,
444 llvm::DenseMap<unsigned, unsigned> searchDirToHSEntry);
445
446 /// Add an additional search path.
447 void AddSearchPath(const DirectoryLookup &dir, bool isAngled);
448
449 /// Add an additional system search path.
450 void AddSystemSearchPath(const DirectoryLookup &dir) {
451 SearchDirs.push_back(x: dir);
452 SearchDirsUsage.push_back(x: false);
453 }
454
455 /// Set the list of system header prefixes.
456 void SetSystemHeaderPrefixes(ArrayRef<std::pair<std::string, bool>> P) {
457 SystemHeaderPrefixes.assign(first: P.begin(), last: P.end());
458 }
459
460 /// Checks whether the map exists or not.
461 bool HasIncludeAliasMap() const { return (bool)IncludeAliases; }
462
463 /// Map the source include name to the dest include name.
464 ///
465 /// The Source should include the angle brackets or quotes, the dest
466 /// should not. This allows for distinction between <> and "" headers.
467 void AddIncludeAlias(StringRef Source, StringRef Dest) {
468 if (!IncludeAliases)
469 IncludeAliases.reset(p: new IncludeAliasMap);
470 (*IncludeAliases)[Source] = std::string(Dest);
471 }
472
473 /// Maps one header file name to a different header
474 /// file name, for use with the include_alias pragma. Note that the source
475 /// file name should include the angle brackets or quotes. Returns StringRef
476 /// as null if the header cannot be mapped.
477 StringRef MapHeaderToIncludeAlias(StringRef Source) {
478 assert(IncludeAliases && "Trying to map headers when there's no map");
479
480 // Do any filename replacements before anything else
481 IncludeAliasMap::const_iterator Iter = IncludeAliases->find(Key: Source);
482 if (Iter != IncludeAliases->end())
483 return Iter->second;
484 return {};
485 }
486
487 /// Initialize the module cache path.
488 void initializeModuleCachePath(std::string ContextHash);
489
490 /// Retrieve the specific module cache path. This is the normalized module
491 /// cache path plus the context hash (unless suppressed).
492 StringRef getSpecificModuleCachePath() const {
493 return SpecificModuleCachePath;
494 }
495
496 /// Retrieve the context hash.
497 StringRef getContextHash() const { return ContextHash; }
498
499 /// Retrieve the normalized module cache path. This is the path as provided on
500 /// the command line, but absolute, without './' components, and with
501 /// preferred path separators. Note that this does not have the context hash.
502 StringRef getNormalizedModuleCachePath() const {
503 return getSpecificModuleCachePath().substr(Start: 0, N: NormalizedModuleCachePathLen);
504 }
505
506 /// Forget everything we know about headers so far.
507 void ClearFileInfo() {
508 FileInfo.clear();
509 }
510
511 void SetExternalLookup(ExternalPreprocessorSource *EPS) {
512 ExternalLookup = EPS;
513 }
514
515 ExternalPreprocessorSource *getExternalLookup() const {
516 return ExternalLookup;
517 }
518
519 /// Set the external source of header information.
520 void SetExternalSource(ExternalHeaderFileInfoSource *ES) {
521 ExternalSource = ES;
522 }
523
524 void diagnoseHeaderShadowing(
525 StringRef Filename, FileEntryRef FE, SourceLocation IncludeLoc,
526 ConstSearchDirIterator FromDir,
527 ArrayRef<std::pair<OptionalFileEntryRef, DirectoryEntryRef>> Includers,
528 bool isAngled, int IncluderLoopIndex, ConstSearchDirIterator MainLoopIt);
529
530 /// Set the target information for the header search, if not
531 /// already known.
532 void setTarget(const TargetInfo &Target);
533
534 /// Given a "foo" or \<foo> reference, look up the indicated file,
535 /// return null on failure.
536 ///
537 /// \returns If successful, this returns 'UsedDir', the DirectoryLookup member
538 /// the file was found in, or null if not applicable.
539 ///
540 /// \param IncludeLoc Used for diagnostics if valid.
541 ///
542 /// \param isAngled indicates whether the file reference is a <> reference.
543 ///
544 /// \param CurDir If non-null, the file was found in the specified directory
545 /// search location. This is used to implement \#include_next.
546 ///
547 /// \param Includers Indicates where the \#including file(s) are, in case
548 /// relative searches are needed. In reverse order of inclusion.
549 ///
550 /// \param SearchPath If non-null, will be set to the search path relative
551 /// to which the file was found. If the include path is absolute, SearchPath
552 /// will be set to an empty string.
553 ///
554 /// \param RelativePath If non-null, will be set to the path relative to
555 /// SearchPath at which the file was found. This only differs from the
556 /// Filename for framework includes.
557 ///
558 /// \param SuggestedModule If non-null, and the file found is semantically
559 /// part of a known module, this will be set to the module that should
560 /// be imported instead of preprocessing/parsing the file found.
561 ///
562 /// \param IsMapped If non-null, and the search involved header maps, set to
563 /// true.
564 ///
565 /// \param IsFrameworkFound If non-null, will be set to true if a framework is
566 /// found in any of searched SearchDirs. Will be set to false if a framework
567 /// is found only through header maps. Doesn't guarantee the requested file is
568 /// found.
569 OptionalFileEntryRef LookupFile(
570 StringRef Filename, SourceLocation IncludeLoc, bool isAngled,
571 ConstSearchDirIterator FromDir, ConstSearchDirIterator *CurDir,
572 ArrayRef<std::pair<OptionalFileEntryRef, DirectoryEntryRef>> Includers,
573 SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath,
574 Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule,
575 bool *IsMapped, bool *IsFrameworkFound, bool SkipCache = false,
576 bool BuildSystemModule = false, bool OpenFile = true,
577 bool CacheFailures = true);
578
579 /// Look up a subframework for the specified \#include file.
580 ///
581 /// For example, if \#include'ing <HIToolbox/HIToolbox.h> from
582 /// within ".../Carbon.framework/Headers/Carbon.h", check to see if
583 /// HIToolbox is a subframework within Carbon.framework. If so, return
584 /// the FileEntry for the designated file, otherwise return null.
585 OptionalFileEntryRef LookupSubframeworkHeader(
586 StringRef Filename, FileEntryRef ContextFileEnt,
587 SmallVectorImpl<char> *SearchPath, SmallVectorImpl<char> *RelativePath,
588 Module *RequestingModule, ModuleMap::KnownHeader *SuggestedModule);
589
590 /// Look up the specified framework name in our framework cache.
591 /// \returns The DirectoryEntry it is in if we know, null otherwise.
592 FrameworkCacheEntry &LookupFrameworkCache(StringRef FWName) {
593 return FrameworkMap[FWName];
594 }
595
596 /// Mark the specified file as a target of a \#include,
597 /// \#include_next, or \#import directive.
598 ///
599 /// \return false if \#including the file will have no effect or true
600 /// if we should include it.
601 ///
602 /// \param M The module to which `File` belongs (this should usually be the
603 /// SuggestedModule returned by LookupFile/LookupSubframeworkHeader)
604 bool ShouldEnterIncludeFile(Preprocessor &PP, FileEntryRef File,
605 bool isImport, bool ModulesEnabled, Module *M,
606 bool &IsFirstIncludeOfFile);
607
608 /// Return whether the specified file is a normal header,
609 /// a system header, or a C++ friendly system header.
610 SrcMgr::CharacteristicKind getFileDirFlavor(FileEntryRef File) {
611 if (const HeaderFileInfo *HFI = getExistingFileInfo(FE: File))
612 return (SrcMgr::CharacteristicKind)HFI->DirInfo;
613 return (SrcMgr::CharacteristicKind)HeaderFileInfo().DirInfo;
614 }
615
616 /// Mark the specified file as a "once only" file due to
617 /// \#pragma once.
618 void MarkFileIncludeOnce(FileEntryRef File) {
619 getFileInfo(FE: File).isPragmaOnce = true;
620 }
621
622 /// Mark the specified file as a system header, e.g. due to
623 /// \#pragma GCC system_header.
624 void MarkFileSystemHeader(FileEntryRef File) {
625 getFileInfo(FE: File).DirInfo = SrcMgr::C_System;
626 }
627
628 /// Mark the specified file as part of a module.
629 void MarkFileModuleHeader(FileEntryRef FE, ModuleMap::ModuleHeaderRole Role,
630 bool isCompilingModuleHeader);
631
632 /// Mark the specified file as having a controlling macro.
633 ///
634 /// This is used by the multiple-include optimization to eliminate
635 /// no-op \#includes.
636 void SetFileControllingMacro(FileEntryRef File,
637 const IdentifierInfo *ControllingMacro) {
638 getFileInfo(FE: File).LazyControllingMacro = ControllingMacro;
639 }
640
641 /// Determine whether this file is intended to be safe from
642 /// multiple inclusions, e.g., it has \#pragma once or a controlling
643 /// macro.
644 ///
645 /// This routine does not consider the effect of \#import
646 bool isFileMultipleIncludeGuarded(FileEntryRef File) const;
647
648 /// Determine whether the given file is known to have ever been \#imported.
649 bool hasFileBeenImported(FileEntryRef File) const {
650 const HeaderFileInfo *FI = getExistingFileInfo(FE: File);
651 return FI && FI->isImport;
652 }
653
654 /// Determine which HeaderSearchOptions::UserEntries have been successfully
655 /// used so far and mark their index with 'true' in the resulting bit vector.
656 /// Note: implicit module maps don't contribute to entry usage.
657 std::vector<bool> computeUserEntryUsage() const;
658
659 /// Collect which HeaderSearchOptions::VFSOverlayFiles have been meaningfully
660 /// used so far and mark their index with 'true' in the resulting bit vector.
661 ///
662 /// Note: this ignores VFSs that redirect non-affecting files such as unused
663 /// modulemaps.
664 std::vector<bool> collectVFSUsageAndClear() const;
665
666 /// This method returns a HeaderMap for the specified
667 /// FileEntry, uniquing them through the 'HeaderMaps' datastructure.
668 const HeaderMap *CreateHeaderMap(FileEntryRef FE);
669
670 /// Get filenames for all registered header maps.
671 void getHeaderMapFileNames(SmallVectorImpl<std::string> &Names) const;
672
673 /// Retrieve the name of the cached module file that should be used
674 /// to load the given module.
675 ///
676 /// \param Module The module whose module file name will be returned.
677 ///
678 /// \returns The name of the module file that corresponds to this module,
679 /// or an empty string if this module does not correspond to any module file.
680 ModuleFileName getCachedModuleFileName(Module *Module);
681
682 /// Retrieve the name of the prebuilt module file that should be used
683 /// to load a module with the given name.
684 ///
685 /// \param ModuleName The module whose module file name will be returned.
686 ///
687 /// \param FileMapOnly If true, then only look in the explicit module name
688 // to file name map and skip the directory search.
689 ///
690 /// \returns The name of the module file that corresponds to this module,
691 /// or an empty string if this module does not correspond to any module file.
692 ModuleFileName getPrebuiltModuleFileName(StringRef ModuleName,
693 bool FileMapOnly = false);
694
695 /// Retrieve the name of the prebuilt module file that should be used
696 /// to load the given module.
697 ///
698 /// \param Module The module whose module file name will be returned.
699 ///
700 /// \returns The name of the module file that corresponds to this module,
701 /// or an empty string if this module does not correspond to any module file.
702 ModuleFileName getPrebuiltImplicitModuleFileName(Module *Module);
703
704 /// Retrieve the name of the (to-be-)cached module file that should
705 /// be used to load a module with the given name.
706 ///
707 /// \param ModuleName The module whose module file name will be returned.
708 ///
709 /// \param ModuleMapPath A path that when combined with \c ModuleName
710 /// uniquely identifies this module. See Module::ModuleMap.
711 ///
712 /// \returns The name of the module file that corresponds to this module,
713 /// or an empty string if this module does not correspond to any module file.
714 ModuleFileName getCachedModuleFileName(StringRef ModuleName,
715 StringRef ModuleMapPath);
716
717 /// Lookup a module Search for a module with the given name.
718 ///
719 /// \param ModuleName The name of the module we're looking for.
720 ///
721 /// \param ImportLoc Location of the module include/import.
722 ///
723 /// \param AllowSearch Whether we are allowed to search in the various
724 /// search directories to produce a module definition. If not, this lookup
725 /// will only return an already-known module.
726 ///
727 /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps
728 /// in subdirectories.
729 ///
730 /// \returns The module with the given name.
731 Module *lookupModule(StringRef ModuleName,
732 SourceLocation ImportLoc = SourceLocation(),
733 bool AllowSearch = true,
734 bool AllowExtraModuleMapSearch = false);
735
736 /// Try to find a module map file in the given directory, returning
737 /// \c nullopt if none is found.
738 OptionalFileEntryRef lookupModuleMapFile(DirectoryEntryRef Dir,
739 bool IsFramework);
740
741 /// Determine whether there is a module map that may map the header
742 /// with the given file name to a (sub)module.
743 /// Always returns false if modules are disabled.
744 ///
745 /// \param Filename The name of the file.
746 ///
747 /// \param Root The "root" directory, at which we should stop looking for
748 /// module maps.
749 ///
750 /// \param IsSystem Whether the directories we're looking at are system
751 /// header directories.
752 bool hasModuleMap(StringRef Filename, const DirectoryEntry *Root,
753 bool IsSystem);
754
755 /// Retrieve the module that corresponds to the given file, if any.
756 ///
757 /// \param File The header that we wish to map to a module.
758 /// \param AllowTextual Whether we want to find textual headers too.
759 ModuleMap::KnownHeader findModuleForHeader(FileEntryRef File,
760 bool AllowTextual = false,
761 bool AllowExcluded = false) const;
762
763 /// Retrieve all the modules corresponding to the given file.
764 ///
765 /// \ref findModuleForHeader should typically be used instead of this.
766 ArrayRef<ModuleMap::KnownHeader>
767 findAllModulesForHeader(FileEntryRef File) const;
768
769 /// Like \ref findAllModulesForHeader, but do not attempt to infer module
770 /// ownership from umbrella headers if we've not already done so.
771 ArrayRef<ModuleMap::KnownHeader>
772 findResolvedModulesForHeader(FileEntryRef File) const;
773
774 /// Read the contents of the given module map file.
775 ///
776 /// \param File The module map file.
777 /// \param IsSystem Whether this file is in a system header directory.
778 /// \param ImplicitlyDiscovered Whether this file was found by module map
779 /// search.
780 /// \param ID If the module map file is already mapped (perhaps as part of
781 /// processing a preprocessed module), the ID of the file.
782 /// \param Offset [inout] An offset within ID to start parsing. On exit,
783 /// filled by the end of the parsed contents (either EOF or the
784 /// location of an end-of-module-map pragma).
785 /// \param OriginalModuleMapFile The original path to the module map file,
786 /// used to resolve paths within the module (this is required when
787 /// building the module from preprocessed source).
788 /// \returns true if an error occurred, false otherwise.
789 bool parseAndLoadModuleMapFile(FileEntryRef File, bool IsSystem,
790 bool ImplicitlyDiscovered,
791 FileID ID = FileID(),
792 unsigned *Offset = nullptr,
793 StringRef OriginalModuleMapFile = StringRef());
794
795 /// Collect the set of all known, top-level modules.
796 ///
797 /// \param Modules Will be filled with the set of known, top-level modules.
798 void collectAllModules(SmallVectorImpl<Module *> &Modules);
799
800 /// Load all known, top-level system modules.
801 void loadTopLevelSystemModules();
802
803private:
804 /// Lookup a module with the given module name and search-name.
805 ///
806 /// \param ModuleName The name of the module we're looking for.
807 ///
808 /// \param SearchName The "search-name" to derive filesystem paths from
809 /// when looking for the module map; this is usually equal to ModuleName,
810 /// but for compatibility with some buggy frameworks, additional attempts
811 /// may be made to find the module under a related-but-different search-name.
812 ///
813 /// \param ImportLoc Location of the module include/import.
814 ///
815 /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps
816 /// in subdirectories.
817 ///
818 /// \returns The module named ModuleName.
819 Module *lookupModule(StringRef ModuleName, StringRef SearchName,
820 SourceLocation ImportLoc,
821 bool AllowExtraModuleMapSearch = false);
822
823 /// Retrieve the name of the (to-be-)cached module file that should
824 /// be used to load a module with the given name.
825 ///
826 /// \param ModuleName The module whose module file name will be returned.
827 ///
828 /// \param ModuleMapPath A path that when combined with \c ModuleName
829 /// uniquely identifies this module. See Module::ModuleMap.
830 ///
831 /// \param NormalizedCachePath The normalized path to the module cache.
832 ///
833 /// \returns The name of the module file that corresponds to this module,
834 /// or an empty string if this module does not correspond to any module file.
835 ModuleFileName getCachedModuleFileNameImpl(StringRef ModuleName,
836 StringRef ModuleMapPath,
837 StringRef NormalizedCachePath);
838
839 /// Retrieve a module with the given name, which may be part of the
840 /// given framework.
841 ///
842 /// \param Name The name of the module to retrieve.
843 ///
844 /// \param Dir The framework directory (e.g., ModuleName.framework).
845 ///
846 /// \param IsSystem Whether the framework directory is part of the system
847 /// frameworks.
848 ///
849 /// \param ImplicitlyDiscovered Whether the framework was discovered by module
850 /// map search.
851 ///
852 /// \returns The module, if found; otherwise, null.
853 Module *loadFrameworkModule(StringRef Name, DirectoryEntryRef Dir,
854 bool IsSystem, bool ImplicitlyDiscovered);
855
856 /// Load all of the module maps within the immediate subdirectories
857 /// of the given search directory.
858 void loadSubdirectoryModuleMaps(DirectoryLookup &SearchDir);
859
860 /// Diagnose headers that are a symlink and not covered by a module map.
861 void diagnoseUncoveredSymlink(FileEntryRef File,
862 ModuleMap::KnownHeader &Module,
863 const DirectoryEntry *Root);
864
865 /// Find and suggest a usable module for the given file.
866 ///
867 /// \return \c true if the file can be used, \c false if we are not permitted to
868 /// find this file due to requirements from \p RequestingModule.
869 bool findUsableModuleForHeader(FileEntryRef File, const DirectoryEntry *Root,
870 Module *RequestingModule,
871 ModuleMap::KnownHeader *SuggestedModule,
872 bool IsSystemHeaderDir);
873
874 /// Find and suggest a usable module for the given file, which is part of
875 /// the specified framework.
876 ///
877 /// \return \c true if the file can be used, \c false if we are not permitted to
878 /// find this file due to requirements from \p RequestingModule.
879 bool findUsableModuleForFrameworkHeader(
880 FileEntryRef File, StringRef FrameworkName, Module *RequestingModule,
881 ModuleMap::KnownHeader *SuggestedModule, bool IsSystemFramework);
882
883 /// Look up the file with the specified name and determine its owning
884 /// module.
885 OptionalFileEntryRef
886 getFileAndSuggestModule(StringRef FileName, SourceLocation IncludeLoc,
887 const DirectoryEntry *Dir, bool IsSystemHeaderDir,
888 Module *RequestingModule,
889 ModuleMap::KnownHeader *SuggestedModule,
890 bool OpenFile = true, bool CacheFailures = true);
891
892 /// Cache the result of a successful lookup at the given include location
893 /// using the search path at \c HitIt.
894 void cacheLookupSuccess(LookupFileCacheInfo &CacheLookup,
895 ConstSearchDirIterator HitIt,
896 SourceLocation IncludeLoc);
897
898 /// Note that a lookup at the given include location was successful using the
899 /// search path at index `HitIdx`.
900 void noteLookupUsage(unsigned HitIdx, SourceLocation IncludeLoc);
901
902public:
903 /// Retrieve the module map.
904 ModuleMap &getModuleMap() { return ModMap; }
905
906 /// Retrieve the module map.
907 const ModuleMap &getModuleMap() const { return ModMap; }
908
909 /// Return the HeaderFileInfo structure for the specified FileEntry, in
910 /// preparation for updating it in some way.
911 HeaderFileInfo &getFileInfo(FileEntryRef FE);
912
913 /// Return the HeaderFileInfo structure for the specified FileEntry, if it has
914 /// ever been filled in (either locally or externally).
915 const HeaderFileInfo *getExistingFileInfo(FileEntryRef FE) const;
916
917 /// Iterate HeaderFileInfo structures and their corresponding FileEntryRef, if
918 /// they have ever been filled in locally.
919 void forEachExistingLocalFileInfo(
920 llvm::function_ref<void(FileEntryRef, const HeaderFileInfo &)> Fn) const;
921
922 SearchDirIterator search_dir_begin() { return {*this, 0}; }
923 SearchDirIterator search_dir_end() { return {*this, SearchDirs.size()}; }
924 SearchDirRange search_dir_range() {
925 return {search_dir_begin(), search_dir_end()};
926 }
927
928 ConstSearchDirIterator search_dir_begin() const { return quoted_dir_begin(); }
929 ConstSearchDirIterator search_dir_nth(size_t n) const {
930 assert(n < SearchDirs.size());
931 return {*this, n};
932 }
933 ConstSearchDirIterator search_dir_end() const { return system_dir_end(); }
934 ConstSearchDirRange search_dir_range() const {
935 return {search_dir_begin(), search_dir_end()};
936 }
937
938 unsigned search_dir_size() const { return SearchDirs.size(); }
939
940 ConstSearchDirIterator quoted_dir_begin() const { return {*this, 0}; }
941 ConstSearchDirIterator quoted_dir_end() const { return angled_dir_begin(); }
942
943 ConstSearchDirIterator angled_dir_begin() const {
944 return {*this, AngledDirIdx};
945 }
946 ConstSearchDirIterator angled_dir_end() const { return system_dir_begin(); }
947
948 ConstSearchDirIterator system_dir_begin() const {
949 return {*this, SystemDirIdx};
950 }
951 ConstSearchDirIterator system_dir_end() const {
952 return {*this, SearchDirs.size()};
953 }
954
955 /// Get the index of the given search directory.
956 unsigned searchDirIdx(const DirectoryLookup &DL) const;
957
958 /// Retrieve a uniqued framework name.
959 StringRef getUniqueFrameworkName(StringRef Framework);
960
961 /// Retrieve the include name for the header.
962 ///
963 /// \param File The entry for a given header.
964 /// \returns The name of how the file was included when the header's location
965 /// was resolved.
966 StringRef getIncludeNameForHeader(const FileEntry *File) const;
967
968 /// Suggest a path by which the specified file could be found, for use in
969 /// diagnostics to suggest a #include. Returned path will only contain forward
970 /// slashes as separators. MainFile is the absolute path of the file that we
971 /// are generating the diagnostics for. It will try to shorten the path using
972 /// MainFile location, if none of the include search directories were prefix
973 /// of File.
974 ///
975 /// \param IsAngled If non-null, filled in to indicate whether the suggested
976 /// path should be referenced as <Header.h> instead of "Header.h".
977 std::string suggestPathToFileForDiagnostics(FileEntryRef File,
978 llvm::StringRef MainFile,
979 bool *IsAngled = nullptr) const;
980
981 /// Suggest a path by which the specified file could be found, for use in
982 /// diagnostics to suggest a #include. Returned path will only contain forward
983 /// slashes as separators. MainFile is the absolute path of the file that we
984 /// are generating the diagnostics for. It will try to shorten the path using
985 /// MainFile location, if none of the include search directories were prefix
986 /// of File.
987 ///
988 /// \param WorkingDir If non-empty, this will be prepended to search directory
989 /// paths that are relative.
990 std::string suggestPathToFileForDiagnostics(llvm::StringRef File,
991 llvm::StringRef WorkingDir,
992 llvm::StringRef MainFile,
993 bool *IsAngled = nullptr) const;
994
995 void PrintStats();
996
997 size_t getTotalMemory() const;
998
999private:
1000 /// Describes what happened when we tried to load or parse a module map file.
1001 enum ModuleMapResult {
1002 /// The module map file had already been processed.
1003 MMR_AlreadyProcessed,
1004
1005 /// The module map file was processed by this invocation.
1006 MMR_NewlyProcessed,
1007
1008 /// There is was directory with the given name.
1009 MMR_NoDirectory,
1010
1011 /// There was either no module map file or the module map file was
1012 /// invalid.
1013 MMR_InvalidModuleMap
1014 };
1015
1016 ModuleMapResult parseAndLoadModuleMapFileImpl(
1017 FileEntryRef File, bool IsSystem, bool ImplicitlyDiscovered,
1018 DirectoryEntryRef Dir, FileID ID = FileID(), unsigned *Offset = nullptr,
1019 bool DiagnosePrivMMap = false);
1020
1021 ModuleMapResult parseModuleMapFileImpl(FileEntryRef File, bool IsSystem,
1022 bool ImplicitlyDiscovered,
1023 DirectoryEntryRef Dir,
1024 FileID ID = FileID());
1025
1026 /// Try to load the module map file in the given directory.
1027 ///
1028 /// \param DirName The name of the directory where we will look for a module
1029 /// map file.
1030 /// \param IsSystem Whether this is a system header directory.
1031 /// \param IsFramework Whether this is a framework directory.
1032 ///
1033 /// \returns The result of attempting to load the module map file from the
1034 /// named directory.
1035 ModuleMapResult parseAndLoadModuleMapFile(StringRef DirName, bool IsSystem,
1036 bool ImplicitlyDiscovered,
1037 bool IsFramework);
1038
1039 /// Try to load the module map file in the given directory.
1040 ///
1041 /// \param Dir The directory where we will look for a module map file.
1042 /// \param IsSystem Whether this is a system header directory.
1043 /// \param IsFramework Whether this is a framework directory.
1044 ///
1045 /// \returns The result of attempting to load the module map file from the
1046 /// named directory.
1047 ModuleMapResult parseAndLoadModuleMapFile(DirectoryEntryRef Dir,
1048 bool IsSystem,
1049 bool ImplicitlyDiscovered,
1050 bool IsFramework);
1051
1052 ModuleMapResult parseModuleMapFile(StringRef DirName, bool IsSystem,
1053 bool ImplicitlyDiscovered,
1054 bool IsFramework);
1055 ModuleMapResult parseModuleMapFile(DirectoryEntryRef Dir, bool IsSystem,
1056 bool ImplicitlyDiscovered,
1057 bool IsFramework);
1058};
1059
1060/// Apply the header search options to get given HeaderSearch object.
1061void ApplyHeaderSearchOptions(HeaderSearch &HS,
1062 const HeaderSearchOptions &HSOpts,
1063 const LangOptions &Lang,
1064 const llvm::Triple &triple);
1065
1066void normalizeModuleCachePath(FileManager &FileMgr, StringRef Path,
1067 SmallVectorImpl<char> &NormalizedPath);
1068
1069std::string createSpecificModuleCachePath(FileManager &FileMgr,
1070 StringRef ModuleCachePath,
1071 bool DisableModuleHash,
1072 std::string ContextHash);
1073
1074} // namespace clang
1075
1076#endif // LLVM_CLANG_LEX_HEADERSEARCH_H
1077