clang  3.7.0
ModuleMap.h
Go to the documentation of this file.
1 //===--- ModuleMap.h - Describe the layout of modules -----------*- 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 // This file defines the ModuleMap interface, which describes the layout of a
11 // module as it relates to headers.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 
16 #ifndef LLVM_CLANG_LEX_MODULEMAP_H
17 #define LLVM_CLANG_LEX_MODULEMAP_H
18 
20 #include "clang/Basic/Module.h"
22 #include "llvm/ADT/DenseMap.h"
23 #include "llvm/ADT/IntrusiveRefCntPtr.h"
24 #include "llvm/ADT/SmallVector.h"
25 #include "llvm/ADT/StringMap.h"
26 #include "llvm/ADT/StringRef.h"
27 #include <string>
28 
29 namespace clang {
30 
31 class DirectoryEntry;
32 class FileEntry;
33 class FileManager;
34 class DiagnosticConsumer;
35 class DiagnosticsEngine;
36 class HeaderSearch;
37 class ModuleMapParser;
38 
39 class ModuleMap {
40  SourceManager &SourceMgr;
41  DiagnosticsEngine &Diags;
42  const LangOptions &LangOpts;
43  const TargetInfo *Target;
44  HeaderSearch &HeaderInfo;
45 
46  /// \brief The directory used for Clang-supplied, builtin include headers,
47  /// such as "stdint.h".
48  const DirectoryEntry *BuiltinIncludeDir;
49 
50  /// \brief Language options used to parse the module map itself.
51  ///
52  /// These are always simple C language options.
53  LangOptions MMapLangOpts;
54 
55  // The module that we are building; related to \c LangOptions::CurrentModule.
56  Module *CompilingModule;
57 
58 public:
59  // The module that the .cc source file is associated with.
61  std::string SourceModuleName;
62 
63 private:
64  /// \brief The top-level modules that are known.
65  llvm::StringMap<Module *> Modules;
66 
67  /// \brief The number of modules we have created in total.
68  unsigned NumCreatedModules;
69 
70 public:
71  /// \brief Flags describing the role of a module header.
73  /// \brief This header is normally included in the module.
74  NormalHeader = 0x0,
75  /// \brief This header is included but private.
77  /// \brief This header is part of the module (for layering purposes) but
78  /// should be textually included.
80  // Caution: Adding an enumerator needs other changes.
81  // Adjust the number of bits for KnownHeader::Storage.
82  // Adjust the bitfield HeaderFileInfo::HeaderRole size.
83  // Adjust the HeaderFileInfoTrait::ReadData streaming.
84  // Adjust the HeaderFileInfoTrait::EmitData streaming.
85  // Adjust ModuleMap::addHeader.
86  };
87 
88  /// \brief A header that is known to reside within a given module,
89  /// whether it was included or excluded.
90  class KnownHeader {
91  llvm::PointerIntPair<Module *, 2, ModuleHeaderRole> Storage;
92 
93  public:
94  KnownHeader() : Storage(nullptr, NormalHeader) { }
95  KnownHeader(Module *M, ModuleHeaderRole Role) : Storage(M, Role) { }
96 
97  /// \brief Retrieve the module the header is stored in.
98  Module *getModule() const { return Storage.getPointer(); }
99 
100  /// \brief The role of this header within the module.
101  ModuleHeaderRole getRole() const { return Storage.getInt(); }
102 
103  /// \brief Whether this header is available in the module.
104  bool isAvailable() const {
105  return getModule()->isAvailable();
106  }
107 
108  // \brief Whether this known header is valid (i.e., it has an
109  // associated module).
110  explicit operator bool() const {
111  return Storage.getPointer() != nullptr;
112  }
113  };
114 
115  typedef llvm::SmallPtrSet<const FileEntry *, 1> AdditionalModMapsSet;
116 
117 private:
118  typedef llvm::DenseMap<const FileEntry *, SmallVector<KnownHeader, 1> >
119  HeadersMap;
120 
121  /// \brief Mapping from each header to the module that owns the contents of
122  /// that header.
123  HeadersMap Headers;
124 
125  /// \brief Mapping from directories with umbrella headers to the module
126  /// that is generated from the umbrella header.
127  ///
128  /// This mapping is used to map headers that haven't explicitly been named
129  /// in the module map over to the module that includes them via its umbrella
130  /// header.
131  llvm::DenseMap<const DirectoryEntry *, Module *> UmbrellaDirs;
132 
133  /// \brief The set of attributes that can be attached to a module.
134  struct Attributes {
135  Attributes() : IsSystem(), IsExternC(), IsExhaustive() {}
136 
137  /// \brief Whether this is a system module.
138  unsigned IsSystem : 1;
139 
140  /// \brief Whether this is an extern "C" module.
141  unsigned IsExternC : 1;
142 
143  /// \brief Whether this is an exhaustive set of configuration macros.
144  unsigned IsExhaustive : 1;
145  };
146 
147  /// \brief A directory for which framework modules can be inferred.
148  struct InferredDirectory {
149  InferredDirectory() : InferModules() {}
150 
151  /// \brief Whether to infer modules from this directory.
152  unsigned InferModules : 1;
153 
154  /// \brief The attributes to use for inferred modules.
155  Attributes Attrs;
156 
157  /// \brief If \c InferModules is non-zero, the module map file that allowed
158  /// inferred modules. Otherwise, nullptr.
159  const FileEntry *ModuleMapFile;
160 
161  /// \brief The names of modules that cannot be inferred within this
162  /// directory.
163  SmallVector<std::string, 2> ExcludedModules;
164  };
165 
166  /// \brief A mapping from directories to information about inferring
167  /// framework modules from within those directories.
168  llvm::DenseMap<const DirectoryEntry *, InferredDirectory> InferredDirectories;
169 
170  /// A mapping from an inferred module to the module map that allowed the
171  /// inference.
172  llvm::DenseMap<const Module *, const FileEntry *> InferredModuleAllowedBy;
173 
174  llvm::DenseMap<const Module *, AdditionalModMapsSet> AdditionalModMaps;
175 
176  /// \brief Describes whether we haved parsed a particular file as a module
177  /// map.
178  llvm::DenseMap<const FileEntry *, bool> ParsedModuleMap;
179 
180  friend class ModuleMapParser;
181 
182  /// \brief Resolve the given export declaration into an actual export
183  /// declaration.
184  ///
185  /// \param Mod The module in which we're resolving the export declaration.
186  ///
187  /// \param Unresolved The export declaration to resolve.
188  ///
189  /// \param Complain Whether this routine should complain about unresolvable
190  /// exports.
191  ///
192  /// \returns The resolved export declaration, which will have a NULL pointer
193  /// if the export could not be resolved.
195  resolveExport(Module *Mod, const Module::UnresolvedExportDecl &Unresolved,
196  bool Complain) const;
197 
198  /// \brief Resolve the given module id to an actual module.
199  ///
200  /// \param Id The module-id to resolve.
201  ///
202  /// \param Mod The module in which we're resolving the module-id.
203  ///
204  /// \param Complain Whether this routine should complain about unresolvable
205  /// module-ids.
206  ///
207  /// \returns The resolved module, or null if the module-id could not be
208  /// resolved.
209  Module *resolveModuleId(const ModuleId &Id, Module *Mod, bool Complain) const;
210 
211  /// \brief Looks up the modules that \p File corresponds to.
212  ///
213  /// If \p File represents a builtin header within Clang's builtin include
214  /// directory, this also loads all of the module maps to see if it will get
215  /// associated with a specific module (e.g. in /usr/include).
216  HeadersMap::iterator findKnownHeader(const FileEntry *File);
217 
218  /// \brief Searches for a module whose umbrella directory contains \p File.
219  ///
220  /// \param File The header to search for.
221  ///
222  /// \param IntermediateDirs On success, contains the set of directories
223  /// searched before finding \p File.
224  KnownHeader findHeaderInUmbrellaDirs(const FileEntry *File,
225  SmallVectorImpl<const DirectoryEntry *> &IntermediateDirs);
226 
227  /// \brief A convenience method to determine if \p File is (possibly nested)
228  /// in an umbrella directory.
229  bool isHeaderInUmbrellaDirs(const FileEntry *File) {
231  return static_cast<bool>(findHeaderInUmbrellaDirs(File, IntermediateDirs));
232  }
233 
234  Module *inferFrameworkModule(const DirectoryEntry *FrameworkDir,
235  Attributes Attrs, Module *Parent);
236 
237 public:
238  /// \brief Construct a new module map.
239  ///
240  /// \param SourceMgr The source manager used to find module files and headers.
241  /// This source manager should be shared with the header-search mechanism,
242  /// since they will refer to the same headers.
243  ///
244  /// \param Diags A diagnostic engine used for diagnostics.
245  ///
246  /// \param LangOpts Language options for this translation unit.
247  ///
248  /// \param Target The target for this translation unit.
250  const LangOptions &LangOpts, const TargetInfo *Target,
251  HeaderSearch &HeaderInfo);
252 
253  /// \brief Destroy the module map.
254  ///
255  ~ModuleMap();
256 
257  /// \brief Set the target information.
258  void setTarget(const TargetInfo &Target);
259 
260  /// \brief Set the directory that contains Clang-supplied include
261  /// files, such as our stdarg.h or tgmath.h.
263  BuiltinIncludeDir = Dir;
264  }
265 
266  /// \brief Retrieve the module that owns the given header file, if any.
267  ///
268  /// \param File The header file that is likely to be included.
269  ///
270  /// \returns The module KnownHeader, which provides the module that owns the
271  /// given header file. The KnownHeader is default constructed to indicate
272  /// that no module owns this header file.
273  KnownHeader findModuleForHeader(const FileEntry *File);
274 
275  /// \brief Reports errors if a module must not include a specific file.
276  ///
277  /// \param RequestingModule The module including a file.
278  ///
279  /// \param FilenameLoc The location of the inclusion's filename.
280  ///
281  /// \param Filename The included filename as written.
282  ///
283  /// \param File The included file.
284  void diagnoseHeaderInclusion(Module *RequestingModule,
285  SourceLocation FilenameLoc, StringRef Filename,
286  const FileEntry *File);
287 
288  /// \brief Determine whether the given header is part of a module
289  /// marked 'unavailable'.
290  bool isHeaderInUnavailableModule(const FileEntry *Header) const;
291 
292  /// \brief Determine whether the given header is unavailable as part
293  /// of the specified module.
294  bool isHeaderUnavailableInModule(const FileEntry *Header,
295  const Module *RequestingModule) const;
296 
297  /// \brief Retrieve a module with the given name.
298  ///
299  /// \param Name The name of the module to look up.
300  ///
301  /// \returns The named module, if known; otherwise, returns null.
302  Module *findModule(StringRef Name) const;
303 
304  /// \brief Retrieve a module with the given name using lexical name lookup,
305  /// starting at the given context.
306  ///
307  /// \param Name The name of the module to look up.
308  ///
309  /// \param Context The module context, from which we will perform lexical
310  /// name lookup.
311  ///
312  /// \returns The named module, if known; otherwise, returns null.
313  Module *lookupModuleUnqualified(StringRef Name, Module *Context) const;
314 
315  /// \brief Retrieve a module with the given name within the given context,
316  /// using direct (qualified) name lookup.
317  ///
318  /// \param Name The name of the module to look up.
319  ///
320  /// \param Context The module for which we will look for a submodule. If
321  /// null, we will look for a top-level module.
322  ///
323  /// \returns The named submodule, if known; otherwose, returns null.
324  Module *lookupModuleQualified(StringRef Name, Module *Context) const;
325 
326  /// \brief Find a new module or submodule, or create it if it does not already
327  /// exist.
328  ///
329  /// \param Name The name of the module to find or create.
330  ///
331  /// \param Parent The module that will act as the parent of this submodule,
332  /// or NULL to indicate that this is a top-level module.
333  ///
334  /// \param IsFramework Whether this is a framework module.
335  ///
336  /// \param IsExplicit Whether this is an explicit submodule.
337  ///
338  /// \returns The found or newly-created module, along with a boolean value
339  /// that will be true if the module is newly-created.
340  std::pair<Module *, bool> findOrCreateModule(StringRef Name, Module *Parent,
341  bool IsFramework,
342  bool IsExplicit);
343 
344  /// \brief Infer the contents of a framework module map from the given
345  /// framework directory.
346  Module *inferFrameworkModule(const DirectoryEntry *FrameworkDir,
347  bool IsSystem, Module *Parent);
348 
349  /// \brief Retrieve the module map file containing the definition of the given
350  /// module.
351  ///
352  /// \param Module The module whose module map file will be returned, if known.
353  ///
354  /// \returns The file entry for the module map file containing the given
355  /// module, or NULL if the module definition was inferred.
356  const FileEntry *getContainingModuleMapFile(const Module *Module) const;
357 
358  /// \brief Get the module map file that (along with the module name) uniquely
359  /// identifies this module.
360  ///
361  /// The particular module that \c Name refers to may depend on how the module
362  /// was found in header search. However, the combination of \c Name and
363  /// this module map will be globally unique for top-level modules. In the case
364  /// of inferred modules, returns the module map that allowed the inference
365  /// (e.g. contained 'module *'). Otherwise, returns
366  /// getContainingModuleMapFile().
367  const FileEntry *getModuleMapFileForUniquing(const Module *M) const;
368 
370 
371  /// \brief Get any module map files other than getModuleMapFileForUniquing(M)
372  /// that define submodules of a top-level module \p M. This is cheaper than
373  /// getting the module map file for each submodule individually, since the
374  /// expected number of results is very small.
376  auto I = AdditionalModMaps.find(M);
377  if (I == AdditionalModMaps.end())
378  return nullptr;
379  return &I->second;
380  }
381 
383  AdditionalModMaps[M].insert(ModuleMap);
384  }
385 
386  /// \brief Resolve all of the unresolved exports in the given module.
387  ///
388  /// \param Mod The module whose exports should be resolved.
389  ///
390  /// \param Complain Whether to emit diagnostics for failures.
391  ///
392  /// \returns true if any errors were encountered while resolving exports,
393  /// false otherwise.
394  bool resolveExports(Module *Mod, bool Complain);
395 
396  /// \brief Resolve all of the unresolved uses in the given module.
397  ///
398  /// \param Mod The module whose uses should be resolved.
399  ///
400  /// \param Complain Whether to emit diagnostics for failures.
401  ///
402  /// \returns true if any errors were encountered while resolving uses,
403  /// false otherwise.
404  bool resolveUses(Module *Mod, bool Complain);
405 
406  /// \brief Resolve all of the unresolved conflicts in the given module.
407  ///
408  /// \param Mod The module whose conflicts should be resolved.
409  ///
410  /// \param Complain Whether to emit diagnostics for failures.
411  ///
412  /// \returns true if any errors were encountered while resolving conflicts,
413  /// false otherwise.
414  bool resolveConflicts(Module *Mod, bool Complain);
415 
416  /// \brief Infers the (sub)module based on the given source location and
417  /// source manager.
418  ///
419  /// \param Loc The location within the source that we are querying, along
420  /// with its source manager.
421  ///
422  /// \returns The module that owns this source location, or null if no
423  /// module owns this source location.
425 
426  /// \brief Sets the umbrella header of the given module to the given
427  /// header.
428  void setUmbrellaHeader(Module *Mod, const FileEntry *UmbrellaHeader,
429  Twine NameAsWritten);
430 
431  /// \brief Sets the umbrella directory of the given module to the given
432  /// directory.
433  void setUmbrellaDir(Module *Mod, const DirectoryEntry *UmbrellaDir,
434  Twine NameAsWritten);
435 
436  /// \brief Adds this header to the given module.
437  /// \param Role The role of the header wrt the module.
438  void addHeader(Module *Mod, Module::Header Header,
439  ModuleHeaderRole Role);
440 
441  /// \brief Marks this header as being excluded from the given module.
442  void excludeHeader(Module *Mod, Module::Header Header);
443 
444  /// \brief Parse the given module map file, and record any modules we
445  /// encounter.
446  ///
447  /// \param File The file to be parsed.
448  ///
449  /// \param IsSystem Whether this module map file is in a system header
450  /// directory, and therefore should be considered a system module.
451  ///
452  /// \param HomeDir The directory in which relative paths within this module
453  /// map file will be resolved.
454  ///
455  /// \param ExternModuleLoc The location of the "extern module" declaration
456  /// that caused us to load this module map file, if any.
457  ///
458  /// \returns true if an error occurred, false otherwise.
459  bool parseModuleMapFile(const FileEntry *File, bool IsSystem,
460  const DirectoryEntry *HomeDir,
461  SourceLocation ExternModuleLoc = SourceLocation());
462 
463  /// \brief Dump the contents of the module map, for debugging purposes.
464  void dump();
465 
466  typedef llvm::StringMap<Module *>::const_iterator module_iterator;
467  module_iterator module_begin() const { return Modules.begin(); }
468  module_iterator module_end() const { return Modules.end(); }
469 };
470 
471 }
472 #endif
void addHeader(Module *Mod, Module::Header Header, ModuleHeaderRole Role)
Adds this header to the given module.
Definition: ModuleMap.cpp:787
Module * getModule() const
Retrieve the module the header is stored in.
Definition: ModuleMap.h:98
ModuleMap(SourceManager &SourceMgr, DiagnosticsEngine &Diags, const LangOptions &LangOpts, const TargetInfo *Target, HeaderSearch &HeaderInfo)
Construct a new module map.
Definition: ModuleMap.cpp:87
Module * lookupModuleQualified(StringRef Name, Module *Context) const
Retrieve a module with the given name within the given context, using direct (qualified) name lookup...
Definition: ModuleMap.cpp:538
This header is included but private.
Definition: ModuleMap.h:76
bool parseModuleMapFile(const FileEntry *File, bool IsSystem, const DirectoryEntry *HomeDir, SourceLocation ExternModuleLoc=SourceLocation())
Parse the given module map file, and record any modules we encounter.
Definition: ModuleMap.cpp:2321
module_iterator module_begin() const
Definition: ModuleMap.h:467
Module * findModule(StringRef Name) const
Retrieve a module with the given name.
Definition: ModuleMap.cpp:520
This header is part of the module (for layering purposes) but should be textually included...
Definition: ModuleMap.h:79
bool isHeaderInUnavailableModule(const FileEntry *Header) const
Determine whether the given header is part of a module marked 'unavailable'.
Definition: ModuleMap.cpp:434
Defines the SourceManager interface.
llvm::SmallPtrSet< const FileEntry *, 1 > AdditionalModMapsSet
Definition: ModuleMap.h:115
Defines the clang::Module class, which describes a module in the source code.
void excludeHeader(Module *Mod, Module::Header Header)
Marks this header as being excluded from the given module.
Definition: ModuleMap.cpp:799
bool resolveUses(Module *Mod, bool Complain)
Resolve all of the unresolved uses in the given module.
Definition: ModuleMap.cpp:866
bool isHeaderUnavailableInModule(const FileEntry *Header, const Module *RequestingModule) const
Determine whether the given header is unavailable as part of the specified module.
Definition: ModuleMap.cpp:439
bool resolveConflicts(Module *Mod, bool Complain)
Resolve all of the unresolved conflicts in the given module.
Definition: ModuleMap.cpp:879
void setUmbrellaDir(Module *Mod, const DirectoryEntry *UmbrellaDir, Twine NameAsWritten)
Sets the umbrella directory of the given module to the given directory.
Definition: ModuleMap.cpp:766
std::string SourceModuleName
Definition: ModuleMap.h:61
Keeps track of the various options that can be enabled, which controls the dialect of C or C++ that i...
Definition: LangOptions.h:48
Describes a module or submodule.
Definition: Basic/Module.h:49
bool isAvailable() const
Determine whether this module is available for use within the current translation unit...
Definition: Basic/Module.h:313
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:135
module_iterator module_end() const
Definition: ModuleMap.h:468
const FileEntry * getContainingModuleMapFile(const Module *Module) const
Retrieve the module map file containing the definition of the given module.
Definition: ModuleMap.cpp:810
void setTarget(const TargetInfo &Target)
Set the target information.
Definition: ModuleMap.cpp:104
Encapsulates the information needed to find the file referenced by a #include or #include_next, (sub-)framework lookup, etc.
Definition: HeaderSearch.h:151
llvm::StringMap< Module * >::const_iterator module_iterator
Definition: ModuleMap.h:466
void diagnoseHeaderInclusion(Module *RequestingModule, SourceLocation FilenameLoc, StringRef Filename, const FileEntry *File)
Reports errors if a module must not include a specific file.
Definition: ModuleMap.cpp:245
ModuleHeaderRole
Flags describing the role of a module header.
Definition: ModuleMap.h:72
ASTContext * Context
Exposes information about the current target.
Defines the clang::LangOptions interface.
void dump()
Dump the contents of the module map, for debugging purposes.
Definition: ModuleMap.cpp:831
Module * lookupModuleUnqualified(StringRef Name, Module *Context) const
Retrieve a module with the given name using lexical name lookup, starting at the given context...
Definition: ModuleMap.cpp:528
SourceManager & SourceMgr
Definition: Format.cpp:1205
bool isAvailable() const
Whether this header is available in the module.
Definition: ModuleMap.h:104
#define bool
Definition: stdbool.h:31
bool resolveExports(Module *Mod, bool Complain)
Resolve all of the unresolved exports in the given module.
Definition: ModuleMap.cpp:853
SmallVector< std::pair< std::string, SourceLocation >, 2 > ModuleId
Describes the name of a module.
Definition: Basic/Module.h:43
void setUmbrellaHeader(Module *Mod, const FileEntry *UmbrellaHeader, Twine NameAsWritten)
Sets the umbrella header of the given module to the given header.
Definition: ModuleMap.cpp:758
Information about a header directive as found in the module map file.
Definition: Basic/Module.h:111
void addAdditionalModuleMapFile(const Module *M, const FileEntry *ModuleMap)
Definition: ModuleMap.h:382
std::pair< Module *, bool > findOrCreateModule(StringRef Name, Module *Parent, bool IsFramework, bool IsExplicit)
Find a new module or submodule, or create it if it does not already exist.
Definition: ModuleMap.cpp:546
void setBuiltinIncludeDir(const DirectoryEntry *Dir)
Set the directory that contains Clang-supplied include files, such as our stdarg.h or tgmath...
Definition: ModuleMap.h:262
Encodes a location in the source. The SourceManager can decode this to get at the full include stack...
Cached information about one file (either on disk or in the virtual file system). ...
Definition: FileManager.h:53
This header is normally included in the module.
Definition: ModuleMap.h:74
Module * inferModuleFromLocation(FullSourceLoc Loc)
Infers the (sub)module based on the given source location and source manager.
Definition: ModuleMap.cpp:894
const FileEntry * getModuleMapFileForUniquing(const Module *M) const
Get the module map file that (along with the module name) uniquely identifies this module...
Definition: ModuleMap.cpp:818
AdditionalModMapsSet * getAdditionalModuleMapFiles(const Module *M)
Get any module map files other than getModuleMapFileForUniquing(M) that define submodules of a top-le...
Definition: ModuleMap.h:375
Describes an exported module that has not yet been resolved (perhaps because the module it refers to ...
Definition: Basic/Module.h:233
KnownHeader findModuleForHeader(const FileEntry *File)
Retrieve the module that owns the given header file, if any.
Definition: ModuleMap.cpp:337
Cached information about one directory (either on disk or in the virtual file system).
Definition: FileManager.h:40
KnownHeader(Module *M, ModuleHeaderRole Role)
Definition: ModuleMap.h:95
ModuleHeaderRole getRole() const
The role of this header within the module.
Definition: ModuleMap.h:101
llvm::PointerIntPair< Module *, 1, bool > ExportDecl
Describes an exported module.
Definition: Basic/Module.h:226
A SourceLocation and its associated SourceManager.
~ModuleMap()
Destroy the module map.
Definition: ModuleMap.cpp:96
Module * SourceModule
Definition: ModuleMap.h:60
A header that is known to reside within a given module, whether it was included or excluded...
Definition: ModuleMap.h:90
void setInferredModuleAllowedBy(Module *M, const FileEntry *ModuleMap)
Definition: ModuleMap.cpp:826
This class handles loading and caching of source files into memory.