• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //===--- Module.h - Describe a module ---------------------------*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 ///
10 /// \file
11 /// \brief Defines the clang::Module class, which describes a module in the
12 /// source code.
13 ///
14 //===----------------------------------------------------------------------===//
15 #ifndef LLVM_CLANG_BASIC_MODULE_H
16 #define LLVM_CLANG_BASIC_MODULE_H
17 
18 #include "clang/Basic/FileManager.h"
19 #include "clang/Basic/SourceLocation.h"
20 #include "llvm/ADT/ArrayRef.h"
21 #include "llvm/ADT/DenseSet.h"
22 #include "llvm/ADT/PointerIntPair.h"
23 #include "llvm/ADT/PointerUnion.h"
24 #include "llvm/ADT/SetVector.h"
25 #include "llvm/ADT/SmallVector.h"
26 #include "llvm/ADT/STLExtras.h"
27 #include "llvm/ADT/StringMap.h"
28 #include "llvm/ADT/StringRef.h"
29 #include <string>
30 #include <utility>
31 #include <vector>
32 
33 namespace llvm {
34   class raw_ostream;
35 }
36 
37 namespace clang {
38 
39 class LangOptions;
40 class TargetInfo;
41 class IdentifierInfo;
42 
43 /// \brief Describes the name of a module.
44 typedef SmallVector<std::pair<std::string, SourceLocation>, 2> ModuleId;
45 
46 /// \brief Describes a module or submodule.
47 class Module {
48 public:
49   /// \brief The name of this module.
50   std::string Name;
51 
52   /// \brief The location of the module definition.
53   SourceLocation DefinitionLoc;
54 
55   /// \brief The parent of this module. This will be NULL for the top-level
56   /// module.
57   Module *Parent;
58 
59   /// \brief The build directory of this module. This is the directory in
60   /// which the module is notionally built, and relative to which its headers
61   /// are found.
62   const DirectoryEntry *Directory;
63 
64   /// \brief The umbrella header or directory.
65   llvm::PointerUnion<const DirectoryEntry *, const FileEntry *> Umbrella;
66 
67   /// \brief The module signature.
68   uint64_t Signature;
69 
70   /// \brief The name of the umbrella entry, as written in the module map.
71   std::string UmbrellaAsWritten;
72 
73 private:
74   /// \brief The submodules of this module, indexed by name.
75   std::vector<Module *> SubModules;
76 
77   /// \brief A mapping from the submodule name to the index into the
78   /// \c SubModules vector at which that submodule resides.
79   llvm::StringMap<unsigned> SubModuleIndex;
80 
81   /// \brief The AST file if this is a top-level module which has a
82   /// corresponding serialized AST file, or null otherwise.
83   const FileEntry *ASTFile;
84 
85   /// \brief The top-level headers associated with this module.
86   llvm::SmallSetVector<const FileEntry *, 2> TopHeaders;
87 
88   /// \brief top-level header filenames that aren't resolved to FileEntries yet.
89   std::vector<std::string> TopHeaderNames;
90 
91   /// \brief Cache of modules visible to lookup in this module.
92   mutable llvm::DenseSet<const Module*> VisibleModulesCache;
93 
94   /// The ID used when referencing this module within a VisibleModuleSet.
95   unsigned VisibilityID;
96 
97 public:
98   enum HeaderKind {
99     HK_Normal,
100     HK_Textual,
101     HK_Private,
102     HK_PrivateTextual,
103     HK_Excluded
104   };
105   static const int NumHeaderKinds = HK_Excluded + 1;
106 
107   /// \brief Information about a header directive as found in the module map
108   /// file.
109   struct Header {
110     std::string NameAsWritten;
111     const FileEntry *Entry;
112 
113     explicit operator bool() { return Entry; }
114   };
115 
116   /// \brief Information about a directory name as found in the module map
117   /// file.
118   struct DirectoryName {
119     std::string NameAsWritten;
120     const DirectoryEntry *Entry;
121 
122     explicit operator bool() { return Entry; }
123   };
124 
125   /// \brief The headers that are part of this module.
126   SmallVector<Header, 2> Headers[5];
127 
128   /// \brief Stored information about a header directive that was found in the
129   /// module map file but has not been resolved to a file.
130   struct UnresolvedHeaderDirective {
131     SourceLocation FileNameLoc;
132     std::string FileName;
133     bool IsUmbrella;
134   };
135 
136   /// \brief Headers that are mentioned in the module map file but could not be
137   /// found on the file system.
138   SmallVector<UnresolvedHeaderDirective, 1> MissingHeaders;
139 
140   /// \brief An individual requirement: a feature name and a flag indicating
141   /// the required state of that feature.
142   typedef std::pair<std::string, bool> Requirement;
143 
144   /// \brief The set of language features required to use this module.
145   ///
146   /// If any of these requirements are not available, the \c IsAvailable bit
147   /// will be false to indicate that this (sub)module is not available.
148   SmallVector<Requirement, 2> Requirements;
149 
150   /// \brief Whether this module is missing a feature from \c Requirements.
151   unsigned IsMissingRequirement : 1;
152 
153   /// \brief Whether we tried and failed to load a module file for this module.
154   unsigned HasIncompatibleModuleFile : 1;
155 
156   /// \brief Whether this module is available in the current translation unit.
157   ///
158   /// If the module is missing headers or does not meet all requirements then
159   /// this bit will be 0.
160   unsigned IsAvailable : 1;
161 
162   /// \brief Whether this module was loaded from a module file.
163   unsigned IsFromModuleFile : 1;
164 
165   /// \brief Whether this is a framework module.
166   unsigned IsFramework : 1;
167 
168   /// \brief Whether this is an explicit submodule.
169   unsigned IsExplicit : 1;
170 
171   /// \brief Whether this is a "system" module (which assumes that all
172   /// headers in it are system headers).
173   unsigned IsSystem : 1;
174 
175   /// \brief Whether this is an 'extern "C"' module (which implicitly puts all
176   /// headers in it within an 'extern "C"' block, and allows the module to be
177   /// imported within such a block).
178   unsigned IsExternC : 1;
179 
180   /// \brief Whether this is an inferred submodule (module * { ... }).
181   unsigned IsInferred : 1;
182 
183   /// \brief Whether we should infer submodules for this module based on
184   /// the headers.
185   ///
186   /// Submodules can only be inferred for modules with an umbrella header.
187   unsigned InferSubmodules : 1;
188 
189   /// \brief Whether, when inferring submodules, the inferred submodules
190   /// should be explicit.
191   unsigned InferExplicitSubmodules : 1;
192 
193   /// \brief Whether, when inferring submodules, the inferr submodules should
194   /// export all modules they import (e.g., the equivalent of "export *").
195   unsigned InferExportWildcard : 1;
196 
197   /// \brief Whether the set of configuration macros is exhaustive.
198   ///
199   /// When the set of configuration macros is exhaustive, meaning
200   /// that no identifier not in this list should affect how the module is
201   /// built.
202   unsigned ConfigMacrosExhaustive : 1;
203 
204   /// \brief Describes the visibility of the various names within a
205   /// particular module.
206   enum NameVisibilityKind {
207     /// \brief All of the names in this module are hidden.
208     Hidden,
209     /// \brief All of the names in this module are visible.
210     AllVisible
211   };
212 
213   /// \brief The visibility of names within this particular module.
214   NameVisibilityKind NameVisibility;
215 
216   /// \brief The location of the inferred submodule.
217   SourceLocation InferredSubmoduleLoc;
218 
219   /// \brief The set of modules imported by this module, and on which this
220   /// module depends.
221   llvm::SmallSetVector<Module *, 2> Imports;
222 
223   /// \brief Describes an exported module.
224   ///
225   /// The pointer is the module being re-exported, while the bit will be true
226   /// to indicate that this is a wildcard export.
227   typedef llvm::PointerIntPair<Module *, 1, bool> ExportDecl;
228 
229   /// \brief The set of export declarations.
230   SmallVector<ExportDecl, 2> Exports;
231 
232   /// \brief Describes an exported module that has not yet been resolved
233   /// (perhaps because the module it refers to has not yet been loaded).
234   struct UnresolvedExportDecl {
235     /// \brief The location of the 'export' keyword in the module map file.
236     SourceLocation ExportLoc;
237 
238     /// \brief The name of the module.
239     ModuleId Id;
240 
241     /// \brief Whether this export declaration ends in a wildcard, indicating
242     /// that all of its submodules should be exported (rather than the named
243     /// module itself).
244     bool Wildcard;
245   };
246 
247   /// \brief The set of export declarations that have yet to be resolved.
248   SmallVector<UnresolvedExportDecl, 2> UnresolvedExports;
249 
250   /// \brief The directly used modules.
251   SmallVector<Module *, 2> DirectUses;
252 
253   /// \brief The set of use declarations that have yet to be resolved.
254   SmallVector<ModuleId, 2> UnresolvedDirectUses;
255 
256   /// \brief A library or framework to link against when an entity from this
257   /// module is used.
258   struct LinkLibrary {
LinkLibraryLinkLibrary259     LinkLibrary() : IsFramework(false) { }
LinkLibraryLinkLibrary260     LinkLibrary(const std::string &Library, bool IsFramework)
261       : Library(Library), IsFramework(IsFramework) { }
262 
263     /// \brief The library to link against.
264     ///
265     /// This will typically be a library or framework name, but can also
266     /// be an absolute path to the library or framework.
267     std::string Library;
268 
269     /// \brief Whether this is a framework rather than a library.
270     bool IsFramework;
271   };
272 
273   /// \brief The set of libraries or frameworks to link against when
274   /// an entity from this module is used.
275   llvm::SmallVector<LinkLibrary, 2> LinkLibraries;
276 
277   /// \brief The set of "configuration macros", which are macros that
278   /// (intentionally) change how this module is built.
279   std::vector<std::string> ConfigMacros;
280 
281   /// \brief An unresolved conflict with another module.
282   struct UnresolvedConflict {
283     /// \brief The (unresolved) module id.
284     ModuleId Id;
285 
286     /// \brief The message provided to the user when there is a conflict.
287     std::string Message;
288   };
289 
290   /// \brief The list of conflicts for which the module-id has not yet been
291   /// resolved.
292   std::vector<UnresolvedConflict> UnresolvedConflicts;
293 
294   /// \brief A conflict between two modules.
295   struct Conflict {
296     /// \brief The module that this module conflicts with.
297     Module *Other;
298 
299     /// \brief The message provided to the user when there is a conflict.
300     std::string Message;
301   };
302 
303   /// \brief The list of conflicts.
304   std::vector<Conflict> Conflicts;
305 
306   /// \brief Construct a new module or submodule.
307   Module(StringRef Name, SourceLocation DefinitionLoc, Module *Parent,
308          bool IsFramework, bool IsExplicit, unsigned VisibilityID);
309 
310   ~Module();
311 
312   /// \brief Determine whether this module is available for use within the
313   /// current translation unit.
isAvailable()314   bool isAvailable() const { return IsAvailable; }
315 
316   /// \brief Determine whether this module is available for use within the
317   /// current translation unit.
318   ///
319   /// \param LangOpts The language options used for the current
320   /// translation unit.
321   ///
322   /// \param Target The target options used for the current translation unit.
323   ///
324   /// \param Req If this module is unavailable, this parameter
325   /// will be set to one of the requirements that is not met for use of
326   /// this module.
327   bool isAvailable(const LangOptions &LangOpts,
328                    const TargetInfo &Target,
329                    Requirement &Req,
330                    UnresolvedHeaderDirective &MissingHeader) const;
331 
332   /// \brief Determine whether this module is a submodule.
isSubModule()333   bool isSubModule() const { return Parent != nullptr; }
334 
335   /// \brief Determine whether this module is a submodule of the given other
336   /// module.
337   bool isSubModuleOf(const Module *Other) const;
338 
339   /// \brief Determine whether this module is a part of a framework,
340   /// either because it is a framework module or because it is a submodule
341   /// of a framework module.
isPartOfFramework()342   bool isPartOfFramework() const {
343     for (const Module *Mod = this; Mod; Mod = Mod->Parent)
344       if (Mod->IsFramework)
345         return true;
346 
347     return false;
348   }
349 
350   /// \brief Determine whether this module is a subframework of another
351   /// framework.
isSubFramework()352   bool isSubFramework() const {
353     return IsFramework && Parent && Parent->isPartOfFramework();
354   }
355 
356   /// \brief Retrieve the full name of this module, including the path from
357   /// its top-level module.
358   std::string getFullModuleName() const;
359 
360   /// \brief Whether the full name of this module is equal to joining
361   /// \p nameParts with "."s.
362   ///
363   /// This is more efficient than getFullModuleName().
364   bool fullModuleNameIs(ArrayRef<StringRef> nameParts) const;
365 
366   /// \brief Retrieve the top-level module for this (sub)module, which may
367   /// be this module.
getTopLevelModule()368   Module *getTopLevelModule() {
369     return const_cast<Module *>(
370              const_cast<const Module *>(this)->getTopLevelModule());
371   }
372 
373   /// \brief Retrieve the top-level module for this (sub)module, which may
374   /// be this module.
375   const Module *getTopLevelModule() const;
376 
377   /// \brief Retrieve the name of the top-level module.
378   ///
getTopLevelModuleName()379   StringRef getTopLevelModuleName() const {
380     return getTopLevelModule()->Name;
381   }
382 
383   /// \brief The serialized AST file for this module, if one was created.
getASTFile()384   const FileEntry *getASTFile() const {
385     return getTopLevelModule()->ASTFile;
386   }
387 
388   /// \brief Set the serialized AST file for the top-level module of this module.
setASTFile(const FileEntry * File)389   void setASTFile(const FileEntry *File) {
390     assert((File == nullptr || getASTFile() == nullptr ||
391             getASTFile() == File) && "file path changed");
392     getTopLevelModule()->ASTFile = File;
393   }
394 
395   /// \brief Retrieve the directory for which this module serves as the
396   /// umbrella.
397   DirectoryName getUmbrellaDir() const;
398 
399   /// \brief Retrieve the header that serves as the umbrella header for this
400   /// module.
getUmbrellaHeader()401   Header getUmbrellaHeader() const {
402     if (auto *E = Umbrella.dyn_cast<const FileEntry *>())
403       return Header{UmbrellaAsWritten, E};
404     return Header{};
405   }
406 
407   /// \brief Determine whether this module has an umbrella directory that is
408   /// not based on an umbrella header.
hasUmbrellaDir()409   bool hasUmbrellaDir() const {
410     return Umbrella && Umbrella.is<const DirectoryEntry *>();
411   }
412 
413   /// \brief Add a top-level header associated with this module.
addTopHeader(const FileEntry * File)414   void addTopHeader(const FileEntry *File) {
415     assert(File);
416     TopHeaders.insert(File);
417   }
418 
419   /// \brief Add a top-level header filename associated with this module.
addTopHeaderFilename(StringRef Filename)420   void addTopHeaderFilename(StringRef Filename) {
421     TopHeaderNames.push_back(Filename);
422   }
423 
424   /// \brief The top-level headers associated with this module.
425   ArrayRef<const FileEntry *> getTopHeaders(FileManager &FileMgr);
426 
427   /// \brief Determine whether this module has declared its intention to
428   /// directly use another module.
429   bool directlyUses(const Module *Requested) const;
430 
431   /// \brief Add the given feature requirement to the list of features
432   /// required by this module.
433   ///
434   /// \param Feature The feature that is required by this module (and
435   /// its submodules).
436   ///
437   /// \param RequiredState The required state of this feature: \c true
438   /// if it must be present, \c false if it must be absent.
439   ///
440   /// \param LangOpts The set of language options that will be used to
441   /// evaluate the availability of this feature.
442   ///
443   /// \param Target The target options that will be used to evaluate the
444   /// availability of this feature.
445   void addRequirement(StringRef Feature, bool RequiredState,
446                       const LangOptions &LangOpts,
447                       const TargetInfo &Target);
448 
449   /// \brief Mark this module and all of its submodules as unavailable.
450   void markUnavailable(bool MissingRequirement = false);
451 
452   /// \brief Find the submodule with the given name.
453   ///
454   /// \returns The submodule if found, or NULL otherwise.
455   Module *findSubmodule(StringRef Name) const;
456 
457   /// \brief Determine whether the specified module would be visible to
458   /// a lookup at the end of this module.
459   ///
460   /// FIXME: This may return incorrect results for (submodules of) the
461   /// module currently being built, if it's queried before we see all
462   /// of its imports.
isModuleVisible(const Module * M)463   bool isModuleVisible(const Module *M) const {
464     if (VisibleModulesCache.empty())
465       buildVisibleModulesCache();
466     return VisibleModulesCache.count(M);
467   }
468 
getVisibilityID()469   unsigned getVisibilityID() const { return VisibilityID; }
470 
471   typedef std::vector<Module *>::iterator submodule_iterator;
472   typedef std::vector<Module *>::const_iterator submodule_const_iterator;
473 
submodule_begin()474   submodule_iterator submodule_begin() { return SubModules.begin(); }
submodule_begin()475   submodule_const_iterator submodule_begin() const {return SubModules.begin();}
submodule_end()476   submodule_iterator submodule_end()   { return SubModules.end(); }
submodule_end()477   submodule_const_iterator submodule_end() const { return SubModules.end(); }
478 
submodules()479   llvm::iterator_range<submodule_iterator> submodules() {
480     return llvm::make_range(submodule_begin(), submodule_end());
481   }
submodules()482   llvm::iterator_range<submodule_const_iterator> submodules() const {
483     return llvm::make_range(submodule_begin(), submodule_end());
484   }
485 
486   /// \brief Appends this module's list of exported modules to \p Exported.
487   ///
488   /// This provides a subset of immediately imported modules (the ones that are
489   /// directly exported), not the complete set of exported modules.
490   void getExportedModules(SmallVectorImpl<Module *> &Exported) const;
491 
getModuleInputBufferName()492   static StringRef getModuleInputBufferName() {
493     return "<module-includes>";
494   }
495 
496   /// \brief Print the module map for this module to the given stream.
497   ///
498   void print(raw_ostream &OS, unsigned Indent = 0) const;
499 
500   /// \brief Dump the contents of this module to the given output stream.
501   void dump() const;
502 
503 private:
504   void buildVisibleModulesCache() const;
505 };
506 
507 /// \brief A set of visible modules.
508 class VisibleModuleSet {
509 public:
VisibleModuleSet()510   VisibleModuleSet() : Generation(0) {}
VisibleModuleSet(VisibleModuleSet && O)511   VisibleModuleSet(VisibleModuleSet &&O)
512       : ImportLocs(std::move(O.ImportLocs)), Generation(O.Generation ? 1 : 0) {
513     O.ImportLocs.clear();
514     ++O.Generation;
515   }
516 
517   /// Move from another visible modules set. Guaranteed to leave the source
518   /// empty and bump the generation on both.
519   VisibleModuleSet &operator=(VisibleModuleSet &&O) {
520     ImportLocs = std::move(O.ImportLocs);
521     O.ImportLocs.clear();
522     ++O.Generation;
523     ++Generation;
524     return *this;
525   }
526 
527   /// \brief Get the current visibility generation. Incremented each time the
528   /// set of visible modules changes in any way.
getGeneration()529   unsigned getGeneration() const { return Generation; }
530 
531   /// \brief Determine whether a module is visible.
isVisible(const Module * M)532   bool isVisible(const Module *M) const {
533     return getImportLoc(M).isValid();
534   }
535 
536   /// \brief Get the location at which the import of a module was triggered.
getImportLoc(const Module * M)537   SourceLocation getImportLoc(const Module *M) const {
538     return M->getVisibilityID() < ImportLocs.size()
539                ? ImportLocs[M->getVisibilityID()]
540                : SourceLocation();
541   }
542 
543   /// \brief A callback to call when a module is made visible (directly or
544   /// indirectly) by a call to \ref setVisible.
545   typedef llvm::function_ref<void(Module *M)> VisibleCallback;
546   /// \brief A callback to call when a module conflict is found. \p Path
547   /// consists of a sequence of modules from the conflicting module to the one
548   /// made visible, where each was exported by the next.
549   typedef llvm::function_ref<void(ArrayRef<Module *> Path,
550                                   Module *Conflict, StringRef Message)>
551       ConflictCallback;
552   /// \brief Make a specific module visible.
553   void setVisible(Module *M, SourceLocation Loc,
554                   VisibleCallback Vis = [](Module *) {},
555                   ConflictCallback Cb = [](ArrayRef<Module *>, Module *,
556                                            StringRef) {});
557 
558 private:
559   /// Import locations for each visible module. Indexed by the module's
560   /// VisibilityID.
561   std::vector<SourceLocation> ImportLocs;
562   /// Visibility generation, bumped every time the visibility state changes.
563   unsigned Generation;
564 };
565 
566 } // end namespace clang
567 
568 
569 #endif // LLVM_CLANG_BASIC_MODULE_H
570