1//===- Module.h - Describe a module -----------------------------*- 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/// \file
10/// Defines the clang::Module class, which describes a module in the
11/// source code.
12//
13//===----------------------------------------------------------------------===//
14
15#ifndef LLVM_CLANG_BASIC_MODULE_H
16#define LLVM_CLANG_BASIC_MODULE_H
17
18#include "clang/Basic/SourceLocation.h"
19#include "llvm/ADT/ArrayRef.h"
20#include "llvm/ADT/DenseSet.h"
21#include "llvm/ADT/Optional.h"
22#include "llvm/ADT/PointerIntPair.h"
23#include "llvm/ADT/SetVector.h"
24#include "llvm/ADT/SmallVector.h"
25#include "llvm/ADT/STLExtras.h"
26#include "llvm/ADT/StringMap.h"
27#include "llvm/ADT/StringRef.h"
28#include "llvm/ADT/iterator_range.h"
29#include <array>
30#include <cassert>
31#include <cstdint>
32#include <ctime>
33#include <string>
34#include <utility>
35#include <vector>
36
37namespace llvm {
38
39class raw_ostream;
40
41} // namespace llvm
42
43namespace clang {
44
45class DirectoryEntry;
46class FileEntry;
47class FileManager;
48class LangOptions;
49class TargetInfo;
50
51/// Describes the name of a module.
52using ModuleId = SmallVector<std::pair<std::string, SourceLocation>, 2>;
53
54/// The signature of a module, which is a hash of the AST content.
55struct ASTFileSignature : std::array<uint32_t, 5> {
56 ASTFileSignature(std::array<uint32_t, 5> S = {{0}})
57 : std::array<uint32_t, 5>(std::move(S)) {}
58
59 explicit operator bool() const {
60 return *this != std::array<uint32_t, 5>({{0}});
61 }
62};
63
64/// Describes a module or submodule.
65class Module {
66public:
67 /// The name of this module.
68 std::string Name;
69
70 /// The location of the module definition.
71 SourceLocation DefinitionLoc;
72
73 enum ModuleKind {
74 /// This is a module that was defined by a module map and built out
75 /// of header files.
76 ModuleMapModule,
77
78 /// This is a C++ Modules TS module interface unit.
79 ModuleInterfaceUnit,
80
81 /// This is a fragment of the global module within some C++ module.
82 GlobalModuleFragment,
83
84 /// This is the private module fragment within some C++ module.
85 PrivateModuleFragment,
86 };
87
88 /// The kind of this module.
89 ModuleKind Kind = ModuleMapModule;
90
91 /// The parent of this module. This will be NULL for the top-level
92 /// module.
93 Module *Parent;
94
95 /// The build directory of this module. This is the directory in
96 /// which the module is notionally built, and relative to which its headers
97 /// are found.
98 const DirectoryEntry *Directory = nullptr;
99
100 /// The presumed file name for the module map defining this module.
101 /// Only non-empty when building from preprocessed source.
102 std::string PresumedModuleMapFile;
103
104 /// The umbrella header or directory.
105 const void *Umbrella = nullptr;
106
107 /// The module signature.
108 ASTFileSignature Signature;
109
110 /// The name of the umbrella entry, as written in the module map.
111 std::string UmbrellaAsWritten;
112
113 /// The module through which entities defined in this module will
114 /// eventually be exposed, for use in "private" modules.
115 std::string ExportAsModule;
116
117 /// Does this Module scope describe part of the purview of a named C++ module?
118 bool isModulePurview() const {
119 return Kind == ModuleInterfaceUnit || Kind == PrivateModuleFragment;
120 }
121
122private:
123 /// The submodules of this module, indexed by name.
124 std::vector<Module *> SubModules;
125
126 /// A mapping from the submodule name to the index into the
127 /// \c SubModules vector at which that submodule resides.
128 llvm::StringMap<unsigned> SubModuleIndex;
129
130 /// The AST file if this is a top-level module which has a
131 /// corresponding serialized AST file, or null otherwise.
132 const FileEntry *ASTFile = nullptr;
133
134 /// The top-level headers associated with this module.
135 llvm::SmallSetVector<const FileEntry *, 2> TopHeaders;
136
137 /// top-level header filenames that aren't resolved to FileEntries yet.
138 std::vector<std::string> TopHeaderNames;
139
140 /// Cache of modules visible to lookup in this module.
141 mutable llvm::DenseSet<const Module*> VisibleModulesCache;
142
143 /// The ID used when referencing this module within a VisibleModuleSet.
144 unsigned VisibilityID;
145
146public:
147 enum HeaderKind {
148 HK_Normal,
149 HK_Textual,
150 HK_Private,
151 HK_PrivateTextual,
152 HK_Excluded
153 };
154 static const int NumHeaderKinds = HK_Excluded + 1;
155
156 /// Information about a header directive as found in the module map
157 /// file.
158 struct Header {
159 std::string NameAsWritten;
160 const FileEntry *Entry;
161
162 explicit operator bool() { return Entry; }
163 };
164
165 /// Information about a directory name as found in the module map
166 /// file.
167 struct DirectoryName {
168 std::string NameAsWritten;
169 const DirectoryEntry *Entry;
170
171 explicit operator bool() { return Entry; }
172 };
173
174 /// The headers that are part of this module.
175 SmallVector<Header, 2> Headers[5];
176
177 /// Stored information about a header directive that was found in the
178 /// module map file but has not been resolved to a file.
179 struct UnresolvedHeaderDirective {
180 HeaderKind Kind = HK_Normal;
181 SourceLocation FileNameLoc;
182 std::string FileName;
183 bool IsUmbrella = false;
184 bool HasBuiltinHeader = false;
185 Optional<off_t> Size;
186 Optional<time_t> ModTime;
187 };
188
189 /// Headers that are mentioned in the module map file but that we have not
190 /// yet attempted to resolve to a file on the file system.
191 SmallVector<UnresolvedHeaderDirective, 1> UnresolvedHeaders;
192
193 /// Headers that are mentioned in the module map file but could not be
194 /// found on the file system.
195 SmallVector<UnresolvedHeaderDirective, 1> MissingHeaders;
196
197 /// An individual requirement: a feature name and a flag indicating
198 /// the required state of that feature.
199 using Requirement = std::pair<std::string, bool>;
200
201 /// The set of language features required to use this module.
202 ///
203 /// If any of these requirements are not available, the \c IsAvailable bit
204 /// will be false to indicate that this (sub)module is not available.
205 SmallVector<Requirement, 2> Requirements;
206
207 /// A module with the same name that shadows this module.
208 Module *ShadowingModule = nullptr;
209
210 /// Whether this module has declared itself unimportable, either because
211 /// it's missing a requirement from \p Requirements or because it's been
212 /// shadowed by another module.
213 unsigned IsUnimportable : 1;
214
215 /// Whether we tried and failed to load a module file for this module.
216 unsigned HasIncompatibleModuleFile : 1;
217
218 /// Whether this module is available in the current translation unit.
219 ///
220 /// If the module is missing headers or does not meet all requirements then
221 /// this bit will be 0.
222 unsigned IsAvailable : 1;
223
224 /// Whether this module was loaded from a module file.
225 unsigned IsFromModuleFile : 1;
226
227 /// Whether this is a framework module.
228 unsigned IsFramework : 1;
229
230 /// Whether this is an explicit submodule.
231 unsigned IsExplicit : 1;
232
233 /// Whether this is a "system" module (which assumes that all
234 /// headers in it are system headers).
235 unsigned IsSystem : 1;
236
237 /// Whether this is an 'extern "C"' module (which implicitly puts all
238 /// headers in it within an 'extern "C"' block, and allows the module to be
239 /// imported within such a block).
240 unsigned IsExternC : 1;
241
242 /// Whether this is an inferred submodule (module * { ... }).
243 unsigned IsInferred : 1;
244
245 /// Whether we should infer submodules for this module based on
246 /// the headers.
247 ///
248 /// Submodules can only be inferred for modules with an umbrella header.
249 unsigned InferSubmodules : 1;
250
251 /// Whether, when inferring submodules, the inferred submodules
252 /// should be explicit.
253 unsigned InferExplicitSubmodules : 1;
254
255 /// Whether, when inferring submodules, the inferr submodules should
256 /// export all modules they import (e.g., the equivalent of "export *").
257 unsigned InferExportWildcard : 1;
258
259 /// Whether the set of configuration macros is exhaustive.
260 ///
261 /// When the set of configuration macros is exhaustive, meaning
262 /// that no identifier not in this list should affect how the module is
263 /// built.
264 unsigned ConfigMacrosExhaustive : 1;
265
266 /// Whether files in this module can only include non-modular headers
267 /// and headers from used modules.
268 unsigned NoUndeclaredIncludes : 1;
269
270 /// Whether this module came from a "private" module map, found next
271 /// to a regular (public) module map.
272 unsigned ModuleMapIsPrivate : 1;
273
274 /// Whether Umbrella is a directory or header.
275 unsigned HasUmbrellaDir : 1;
276
277 /// Describes the visibility of the various names within a
278 /// particular module.
279 enum NameVisibilityKind {
280 /// All of the names in this module are hidden.
281 Hidden,
282 /// All of the names in this module are visible.
283 AllVisible
284 };
285
286 /// The visibility of names within this particular module.
287 NameVisibilityKind NameVisibility;
288
289 /// The location of the inferred submodule.
290 SourceLocation InferredSubmoduleLoc;
291
292 /// The set of modules imported by this module, and on which this
293 /// module depends.
294 llvm::SmallSetVector<Module *, 2> Imports;
295
296 /// Describes an exported module.
297 ///
298 /// The pointer is the module being re-exported, while the bit will be true
299 /// to indicate that this is a wildcard export.
300 using ExportDecl = llvm::PointerIntPair<Module *, 1, bool>;
301
302 /// The set of export declarations.
303 SmallVector<ExportDecl, 2> Exports;
304
305 /// Describes an exported module that has not yet been resolved
306 /// (perhaps because the module it refers to has not yet been loaded).
307 struct UnresolvedExportDecl {
308 /// The location of the 'export' keyword in the module map file.
309 SourceLocation ExportLoc;
310
311 /// The name of the module.
312 ModuleId Id;
313
314 /// Whether this export declaration ends in a wildcard, indicating
315 /// that all of its submodules should be exported (rather than the named
316 /// module itself).
317 bool Wildcard;
318 };
319
320 /// The set of export declarations that have yet to be resolved.
321 SmallVector<UnresolvedExportDecl, 2> UnresolvedExports;
322
323 /// The directly used modules.
324 SmallVector<Module *, 2> DirectUses;
325
326 /// The set of use declarations that have yet to be resolved.
327 SmallVector<ModuleId, 2> UnresolvedDirectUses;
328
329 /// A library or framework to link against when an entity from this
330 /// module is used.
331 struct LinkLibrary {
332 LinkLibrary() = default;
333 LinkLibrary(const std::string &Library, bool IsFramework)
334 : Library(Library), IsFramework(IsFramework) {}
335
336 /// The library to link against.
337 ///
338 /// This will typically be a library or framework name, but can also
339 /// be an absolute path to the library or framework.
340 std::string Library;
341
342 /// Whether this is a framework rather than a library.
343 bool IsFramework = false;
344 };
345
346 /// The set of libraries or frameworks to link against when
347 /// an entity from this module is used.
348 llvm::SmallVector<LinkLibrary, 2> LinkLibraries;
349
350 /// Autolinking uses the framework name for linking purposes
351 /// when this is false and the export_as name otherwise.
352 bool UseExportAsModuleLinkName = false;
353
354 /// The set of "configuration macros", which are macros that
355 /// (intentionally) change how this module is built.
356 std::vector<std::string> ConfigMacros;
357
358 /// An unresolved conflict with another module.
359 struct UnresolvedConflict {
360 /// The (unresolved) module id.
361 ModuleId Id;
362
363 /// The message provided to the user when there is a conflict.
364 std::string Message;
365 };
366
367 /// The list of conflicts for which the module-id has not yet been
368 /// resolved.
369 std::vector<UnresolvedConflict> UnresolvedConflicts;
370
371 /// A conflict between two modules.
372 struct Conflict {
373 /// The module that this module conflicts with.
374 Module *Other;
375
376 /// The message provided to the user when there is a conflict.
377 std::string Message;
378 };
379
380 /// The list of conflicts.
381 std::vector<Conflict> Conflicts;
382
383 /// Construct a new module or submodule.
384 Module(StringRef Name, SourceLocation DefinitionLoc, Module *Parent,
385 bool IsFramework, bool IsExplicit, unsigned VisibilityID);
386
387 ~Module();
388
389 /// Determine whether this module has been declared unimportable.
390 bool isUnimportable() const { return IsUnimportable; }
391
392 /// Determine whether this module has been declared unimportable.
393 ///
394 /// \param LangOpts The language options used for the current
395 /// translation unit.
396 ///
397 /// \param Target The target options used for the current translation unit.
398 ///
399 /// \param Req If this module is unimportable because of a missing
400 /// requirement, this parameter will be set to one of the requirements that
401 /// is not met for use of this module.
402 ///
403 /// \param ShadowingModule If this module is unimportable because it is
404 /// shadowed, this parameter will be set to the shadowing module.
405 bool isUnimportable(const LangOptions &LangOpts, const TargetInfo &Target,
406 Requirement &Req, Module *&ShadowingModule) const;
407
408 /// Determine whether this module is available for use within the
409 /// current translation unit.
410 bool isAvailable() const { return IsAvailable; }
411
412 /// Determine whether this module is available for use within the
413 /// current translation unit.
414 ///
415 /// \param LangOpts The language options used for the current
416 /// translation unit.
417 ///
418 /// \param Target The target options used for the current translation unit.
419 ///
420 /// \param Req If this module is unavailable because of a missing requirement,
421 /// this parameter will be set to one of the requirements that is not met for
422 /// use of this module.
423 ///
424 /// \param MissingHeader If this module is unavailable because of a missing
425 /// header, this parameter will be set to one of the missing headers.
426 ///
427 /// \param ShadowingModule If this module is unavailable because it is
428 /// shadowed, this parameter will be set to the shadowing module.
429 bool isAvailable(const LangOptions &LangOpts,
430 const TargetInfo &Target,
431 Requirement &Req,
432 UnresolvedHeaderDirective &MissingHeader,
433 Module *&ShadowingModule) const;
434
435 /// Determine whether this module is a submodule.
436 bool isSubModule() const { return Parent != nullptr; }
437
438 /// Determine whether this module is a submodule of the given other
439 /// module.
440 bool isSubModuleOf(const Module *Other) const;
441
442 /// Determine whether this module is a part of a framework,
443 /// either because it is a framework module or because it is a submodule
444 /// of a framework module.
445 bool isPartOfFramework() const {
446 for (const Module *Mod = this; Mod; Mod = Mod->Parent)
447 if (Mod->IsFramework)
448 return true;
449
450 return false;
451 }
452
453 /// Determine whether this module is a subframework of another
454 /// framework.
455 bool isSubFramework() const {
456 return IsFramework && Parent && Parent->isPartOfFramework();
457 }
458
459 /// Set the parent of this module. This should only be used if the parent
460 /// could not be set during module creation.
461 void setParent(Module *M) {
462 assert(!Parent);
463 Parent = M;
464 Parent->SubModuleIndex[Name] = Parent->SubModules.size();
465 Parent->SubModules.push_back(this);
466 }
467
468 /// Retrieve the full name of this module, including the path from
469 /// its top-level module.
470 /// \param AllowStringLiterals If \c true, components that might not be
471 /// lexically valid as identifiers will be emitted as string literals.
472 std::string getFullModuleName(bool AllowStringLiterals = false) const;
473
474 /// Whether the full name of this module is equal to joining
475 /// \p nameParts with "."s.
476 ///
477 /// This is more efficient than getFullModuleName().
478 bool fullModuleNameIs(ArrayRef<StringRef> nameParts) const;
479
480 /// Retrieve the top-level module for this (sub)module, which may
481 /// be this module.
482 Module *getTopLevelModule() {
483 return const_cast<Module *>(
484 const_cast<const Module *>(this)->getTopLevelModule());
485 }
486
487 /// Retrieve the top-level module for this (sub)module, which may
488 /// be this module.
489 const Module *getTopLevelModule() const;
490
491 /// Retrieve the name of the top-level module.
492 StringRef getTopLevelModuleName() const {
493 return getTopLevelModule()->Name;
494 }
495
496 /// The serialized AST file for this module, if one was created.
497 const FileEntry *getASTFile() const {
498 return getTopLevelModule()->ASTFile;
499 }
500
501 /// Set the serialized AST file for the top-level module of this module.
502 void setASTFile(const FileEntry *File) {
503 assert((File == nullptr || getASTFile() == nullptr ||
504 getASTFile() == File) && "file path changed");
505 getTopLevelModule()->ASTFile = File;
506 }
507
508 /// Retrieve the directory for which this module serves as the
509 /// umbrella.
510 DirectoryName getUmbrellaDir() const;
511
512 /// Retrieve the header that serves as the umbrella header for this
513 /// module.
514 Header getUmbrellaHeader() const {
515 if (!HasUmbrellaDir)
516 return Header{UmbrellaAsWritten,
517 static_cast<const FileEntry *>(Umbrella)};
518 return Header{};
519 }
520
521 /// Determine whether this module has an umbrella directory that is
522 /// not based on an umbrella header.
523 bool hasUmbrellaDir() const { return Umbrella && HasUmbrellaDir; }
524
525 /// Add a top-level header associated with this module.
526 void addTopHeader(const FileEntry *File);
527
528 /// Add a top-level header filename associated with this module.
529 void addTopHeaderFilename(StringRef Filename) {
530 TopHeaderNames.push_back(std::string(Filename));
531 }
532
533 /// The top-level headers associated with this module.
534 ArrayRef<const FileEntry *> getTopHeaders(FileManager &FileMgr);
535
536 /// Determine whether this module has declared its intention to
537 /// directly use another module.
538 bool directlyUses(const Module *Requested) const;
539
540 /// Add the given feature requirement to the list of features
541 /// required by this module.
542 ///
543 /// \param Feature The feature that is required by this module (and
544 /// its submodules).
545 ///
546 /// \param RequiredState The required state of this feature: \c true
547 /// if it must be present, \c false if it must be absent.
548 ///
549 /// \param LangOpts The set of language options that will be used to
550 /// evaluate the availability of this feature.
551 ///
552 /// \param Target The target options that will be used to evaluate the
553 /// availability of this feature.
554 void addRequirement(StringRef Feature, bool RequiredState,
555 const LangOptions &LangOpts,
556 const TargetInfo &Target);
557
558 /// Mark this module and all of its submodules as unavailable.
559 void markUnavailable(bool Unimportable);
560
561 /// Find the submodule with the given name.
562 ///
563 /// \returns The submodule if found, or NULL otherwise.
564 Module *findSubmodule(StringRef Name) const;
565 Module *findOrInferSubmodule(StringRef Name);
566
567 /// Determine whether the specified module would be visible to
568 /// a lookup at the end of this module.
569 ///
570 /// FIXME: This may return incorrect results for (submodules of) the
571 /// module currently being built, if it's queried before we see all
572 /// of its imports.
573 bool isModuleVisible(const Module *M) const {
574 if (VisibleModulesCache.empty())
575 buildVisibleModulesCache();
576 return VisibleModulesCache.count(M);
577 }
578
579 unsigned getVisibilityID() const { return VisibilityID; }
580
581 using submodule_iterator = std::vector<Module *>::iterator;
582 using submodule_const_iterator = std::vector<Module *>::const_iterator;
583
584 submodule_iterator submodule_begin() { return SubModules.begin(); }
585 submodule_const_iterator submodule_begin() const {return SubModules.begin();}
586 submodule_iterator submodule_end() { return SubModules.end(); }
587 submodule_const_iterator submodule_end() const { return SubModules.end(); }
588
589 llvm::iterator_range<submodule_iterator> submodules() {
590 return llvm::make_range(submodule_begin(), submodule_end());
591 }
592 llvm::iterator_range<submodule_const_iterator> submodules() const {
593 return llvm::make_range(submodule_begin(), submodule_end());
594 }
595
596 /// Appends this module's list of exported modules to \p Exported.
597 ///
598 /// This provides a subset of immediately imported modules (the ones that are
599 /// directly exported), not the complete set of exported modules.
600 void getExportedModules(SmallVectorImpl<Module *> &Exported) const;
601
602 static StringRef getModuleInputBufferName() {
603 return "<module-includes>";
604 }
605
606 /// Print the module map for this module to the given stream.
607 void print(raw_ostream &OS, unsigned Indent = 0) const;
608
609 /// Dump the contents of this module to the given output stream.
610 void dump() const;
611
612private:
613 void buildVisibleModulesCache() const;
614};
615
616/// A set of visible modules.
617class VisibleModuleSet {
618public:
619 VisibleModuleSet() = default;
620 VisibleModuleSet(VisibleModuleSet &&O)
621 : ImportLocs(std::move(O.ImportLocs)), Generation(O.Generation ? 1 : 0) {
622 O.ImportLocs.clear();
623 ++O.Generation;
624 }
625
626 /// Move from another visible modules set. Guaranteed to leave the source
627 /// empty and bump the generation on both.
628 VisibleModuleSet &operator=(VisibleModuleSet &&O) {
629 ImportLocs = std::move(O.ImportLocs);
630 O.ImportLocs.clear();
631 ++O.Generation;
632 ++Generation;
633 return *this;
634 }
635
636 /// Get the current visibility generation. Incremented each time the
637 /// set of visible modules changes in any way.
638 unsigned getGeneration() const { return Generation; }
639
640 /// Determine whether a module is visible.
641 bool isVisible(const Module *M) const {
642 return getImportLoc(M).isValid();
643 }
644
645 /// Get the location at which the import of a module was triggered.
646 SourceLocation getImportLoc(const Module *M) const {
647 return M->getVisibilityID() < ImportLocs.size()
648 ? ImportLocs[M->getVisibilityID()]
649 : SourceLocation();
650 }
651
652 /// A callback to call when a module is made visible (directly or
653 /// indirectly) by a call to \ref setVisible.
654 using VisibleCallback = llvm::function_ref<void(Module *M)>;
655
656 /// A callback to call when a module conflict is found. \p Path
657 /// consists of a sequence of modules from the conflicting module to the one
658 /// made visible, where each was exported by the next.
659 using ConflictCallback =
660 llvm::function_ref<void(ArrayRef<Module *> Path, Module *Conflict,
661 StringRef Message)>;
662
663 /// Make a specific module visible.
664 void setVisible(Module *M, SourceLocation Loc,
665 VisibleCallback Vis = [](Module *) {},
666 ConflictCallback Cb = [](ArrayRef<Module *>, Module *,
667 StringRef) {});
668
669private:
670 /// Import locations for each visible module. Indexed by the module's
671 /// VisibilityID.
672 std::vector<SourceLocation> ImportLocs;
673
674 /// Visibility generation, bumped every time the visibility state changes.
675 unsigned Generation = 0;
676};
677
678/// Abstracts clang modules and precompiled header files and holds
679/// everything needed to generate debug info for an imported module
680/// or PCH.
681class ASTSourceDescriptor {
682 StringRef PCHModuleName;
683 StringRef Path;
684 StringRef ASTFile;
685 ASTFileSignature Signature;
686 Module *ClangModule = nullptr;
687
688public:
689 ASTSourceDescriptor() = default;
690 ASTSourceDescriptor(StringRef Name, StringRef Path, StringRef ASTFile,
691 ASTFileSignature Signature)
692 : PCHModuleName(std::move(Name)), Path(std::move(Path)),
693 ASTFile(std::move(ASTFile)), Signature(Signature) {}
694 ASTSourceDescriptor(Module &M);
695
696 std::string getModuleName() const;
697 StringRef getPath() const { return Path; }
698 StringRef getASTFile() const { return ASTFile; }
699 ASTFileSignature getSignature() const { return Signature; }
700 Module *getModuleOrNull() const { return ClangModule; }
701};
702
703
704} // namespace clang
705
706#endif // LLVM_CLANG_BASIC_MODULE_H
707