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