1 //===--- ModuleMap.h - Describe the layout of modules -----------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines the ModuleMap interface, which describes the layout of a
11 // module as it relates to headers.
13 //===----------------------------------------------------------------------===//
16 #ifndef LLVM_CLANG_LEX_MODULEMAP_H
17 #define LLVM_CLANG_LEX_MODULEMAP_H
19 #include "clang/Basic/LangOptions.h"
20 #include "clang/Basic/Module.h"
21 #include "clang/Basic/SourceManager.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"
34 class DiagnosticConsumer;
35 class DiagnosticsEngine;
37 class ModuleMapParser;
40 SourceManager &SourceMgr;
41 IntrusiveRefCntPtr<DiagnosticsEngine> Diags;
42 const LangOptions &LangOpts;
43 const TargetInfo *Target;
44 HeaderSearch &HeaderInfo;
46 /// \brief The directory used for Clang-supplied, builtin include headers,
47 /// such as "stdint.h".
48 const DirectoryEntry *BuiltinIncludeDir;
50 /// \brief Language options used to parse the module map itself.
52 /// These are always simple C language options.
53 LangOptions MMapLangOpts;
55 // The module that we are building; related to \c LangOptions::CurrentModule.
56 Module *CompilingModule;
59 // The module that the .cc source file is associated with.
61 std::string SourceModuleName;
64 /// \brief The top-level modules that are known.
65 llvm::StringMap<Module *> Modules;
68 /// \brief Describes the role of a module header.
69 enum ModuleHeaderRole {
70 /// \brief This header is normally included in the module.
72 /// \brief This header is included but private.
74 /// \brief This header is explicitly excluded from the module.
76 // Caution: Adding an enumerator needs other changes.
77 // Adjust the number of bits for KnownHeader::Storage.
78 // Adjust the bitfield HeaderFileInfo::HeaderRole size.
79 // Adjust the HeaderFileInfoTrait::ReadData streaming.
80 // Adjust the HeaderFileInfoTrait::EmitData streaming.
83 /// \brief A header that is known to reside within a given module,
84 /// whether it was included or excluded.
86 llvm::PointerIntPair<Module *, 2, ModuleHeaderRole> Storage;
89 KnownHeader() : Storage(0, NormalHeader) { }
90 KnownHeader(Module *M, ModuleHeaderRole Role) : Storage(M, Role) { }
92 /// \brief Retrieve the module the header is stored in.
93 Module *getModule() const { return Storage.getPointer(); }
95 /// \brief The role of this header within the module.
96 ModuleHeaderRole getRole() const { return Storage.getInt(); }
98 /// \brief Whether this header is available in the module.
99 bool isAvailable() const {
100 return getRole() != ExcludedHeader && getModule()->isAvailable();
103 // \brief Whether this known header is valid (i.e., it has an
104 // associated module).
105 LLVM_EXPLICIT operator bool() const { return Storage.getPointer() != 0; }
109 typedef llvm::DenseMap<const FileEntry *, SmallVector<KnownHeader, 1> >
112 /// \brief Mapping from each header to the module that owns the contents of
116 /// \brief Mapping from directories with umbrella headers to the module
117 /// that is generated from the umbrella header.
119 /// This mapping is used to map headers that haven't explicitly been named
120 /// in the module map over to the module that includes them via its umbrella
122 llvm::DenseMap<const DirectoryEntry *, Module *> UmbrellaDirs;
124 /// \brief A directory for which framework modules can be inferred.
125 struct InferredDirectory {
126 InferredDirectory() : InferModules(), InferSystemModules() { }
128 /// \brief Whether to infer modules from this directory.
129 unsigned InferModules : 1;
131 /// \brief Whether the modules we infer are [system] modules.
132 unsigned InferSystemModules : 1;
134 /// \brief The names of modules that cannot be inferred within this
136 SmallVector<std::string, 2> ExcludedModules;
139 /// \brief A mapping from directories to information about inferring
140 /// framework modules from within those directories.
141 llvm::DenseMap<const DirectoryEntry *, InferredDirectory> InferredDirectories;
143 /// \brief Describes whether we haved parsed a particular file as a module
145 llvm::DenseMap<const FileEntry *, bool> ParsedModuleMap;
147 friend class ModuleMapParser;
149 /// \brief Resolve the given export declaration into an actual export
152 /// \param Mod The module in which we're resolving the export declaration.
154 /// \param Unresolved The export declaration to resolve.
156 /// \param Complain Whether this routine should complain about unresolvable
159 /// \returns The resolved export declaration, which will have a NULL pointer
160 /// if the export could not be resolved.
162 resolveExport(Module *Mod, const Module::UnresolvedExportDecl &Unresolved,
163 bool Complain) const;
165 /// \brief Resolve the given module id to an actual module.
167 /// \param Id The module-id to resolve.
169 /// \param Mod The module in which we're resolving the module-id.
171 /// \param Complain Whether this routine should complain about unresolvable
174 /// \returns The resolved module, or null if the module-id could not be
176 Module *resolveModuleId(const ModuleId &Id, Module *Mod, bool Complain) const;
179 /// \brief Construct a new module map.
181 /// \param SourceMgr The source manager used to find module files and headers.
182 /// This source manager should be shared with the header-search mechanism,
183 /// since they will refer to the same headers.
185 /// \param DC A diagnostic consumer that will be cloned for use in generating
188 /// \param LangOpts Language options for this translation unit.
190 /// \param Target The target for this translation unit.
191 ModuleMap(SourceManager &SourceMgr, DiagnosticConsumer &DC,
192 const LangOptions &LangOpts, const TargetInfo *Target,
193 HeaderSearch &HeaderInfo);
195 /// \brief Destroy the module map.
199 /// \brief Set the target information.
200 void setTarget(const TargetInfo &Target);
202 /// \brief Set the directory that contains Clang-supplied include
203 /// files, such as our stdarg.h or tgmath.h.
204 void setBuiltinIncludeDir(const DirectoryEntry *Dir) {
205 BuiltinIncludeDir = Dir;
208 /// \brief Retrieve the module that owns the given header file, if any.
210 /// \param File The header file that is likely to be included.
212 /// \param RequestingModule Specifies the module the header is intended to be
213 /// used from. Used to disambiguate if a header is present in multiple
216 /// \returns The module KnownHeader, which provides the module that owns the
217 /// given header file. The KnownHeader is default constructed to indicate
218 /// that no module owns this header file.
219 KnownHeader findModuleForHeader(const FileEntry *File,
220 Module *RequestingModule = NULL);
222 /// \brief Determine whether the given header is part of a module
223 /// marked 'unavailable'.
224 bool isHeaderInUnavailableModule(const FileEntry *Header) const;
226 /// \brief Retrieve a module with the given name.
228 /// \param Name The name of the module to look up.
230 /// \returns The named module, if known; otherwise, returns null.
231 Module *findModule(StringRef Name) const;
233 /// \brief Retrieve a module with the given name using lexical name lookup,
234 /// starting at the given context.
236 /// \param Name The name of the module to look up.
238 /// \param Context The module context, from which we will perform lexical
241 /// \returns The named module, if known; otherwise, returns null.
242 Module *lookupModuleUnqualified(StringRef Name, Module *Context) const;
244 /// \brief Retrieve a module with the given name within the given context,
245 /// using direct (qualified) name lookup.
247 /// \param Name The name of the module to look up.
249 /// \param Context The module for which we will look for a submodule. If
250 /// null, we will look for a top-level module.
252 /// \returns The named submodule, if known; otherwose, returns null.
253 Module *lookupModuleQualified(StringRef Name, Module *Context) const;
255 /// \brief Find a new module or submodule, or create it if it does not already
258 /// \param Name The name of the module to find or create.
260 /// \param Parent The module that will act as the parent of this submodule,
261 /// or NULL to indicate that this is a top-level module.
263 /// \param IsFramework Whether this is a framework module.
265 /// \param IsExplicit Whether this is an explicit submodule.
267 /// \returns The found or newly-created module, along with a boolean value
268 /// that will be true if the module is newly-created.
269 std::pair<Module *, bool> findOrCreateModule(StringRef Name, Module *Parent,
273 /// \brief Determine whether we can infer a framework module a framework
274 /// with the given name in the given
276 /// \param ParentDir The directory that is the parent of the framework
279 /// \param Name The name of the module.
281 /// \param IsSystem Will be set to 'true' if the inferred module must be a
284 /// \returns true if we are allowed to infer a framework module, and false
286 bool canInferFrameworkModule(const DirectoryEntry *ParentDir,
287 StringRef Name, bool &IsSystem) const;
289 /// \brief Infer the contents of a framework module map from the given
290 /// framework directory.
291 Module *inferFrameworkModule(StringRef ModuleName,
292 const DirectoryEntry *FrameworkDir,
293 bool IsSystem, Module *Parent);
295 /// \brief Retrieve the module map file containing the definition of the given
298 /// \param Module The module whose module map file will be returned, if known.
300 /// \returns The file entry for the module map file containing the given
301 /// module, or NULL if the module definition was inferred.
302 const FileEntry *getContainingModuleMapFile(Module *Module) const;
304 /// \brief Resolve all of the unresolved exports in the given module.
306 /// \param Mod The module whose exports should be resolved.
308 /// \param Complain Whether to emit diagnostics for failures.
310 /// \returns true if any errors were encountered while resolving exports,
312 bool resolveExports(Module *Mod, bool Complain);
314 /// \brief Resolve all of the unresolved uses in the given module.
316 /// \param Mod The module whose uses should be resolved.
318 /// \param Complain Whether to emit diagnostics for failures.
320 /// \returns true if any errors were encountered while resolving uses,
322 bool resolveUses(Module *Mod, bool Complain);
324 /// \brief Resolve all of the unresolved conflicts in the given module.
326 /// \param Mod The module whose conflicts should be resolved.
328 /// \param Complain Whether to emit diagnostics for failures.
330 /// \returns true if any errors were encountered while resolving conflicts,
332 bool resolveConflicts(Module *Mod, bool Complain);
334 /// \brief Infers the (sub)module based on the given source location and
337 /// \param Loc The location within the source that we are querying, along
338 /// with its source manager.
340 /// \returns The module that owns this source location, or null if no
341 /// module owns this source location.
342 Module *inferModuleFromLocation(FullSourceLoc Loc);
344 /// \brief Sets the umbrella header of the given module to the given
346 void setUmbrellaHeader(Module *Mod, const FileEntry *UmbrellaHeader);
348 /// \brief Sets the umbrella directory of the given module to the given
350 void setUmbrellaDir(Module *Mod, const DirectoryEntry *UmbrellaDir);
352 /// \brief Adds this header to the given module.
353 /// \param Role The role of the header wrt the module.
354 void addHeader(Module *Mod, const FileEntry *Header,
355 ModuleHeaderRole Role);
357 /// \brief Parse the given module map file, and record any modules we
360 /// \param File The file to be parsed.
362 /// \param IsSystem Whether this module map file is in a system header
363 /// directory, and therefore should be considered a system module.
365 /// \returns true if an error occurred, false otherwise.
366 bool parseModuleMapFile(const FileEntry *File, bool IsSystem);
368 /// \brief Dump the contents of the module map, for debugging purposes.
371 typedef llvm::StringMap<Module *>::const_iterator module_iterator;
372 module_iterator module_begin() const { return Modules.begin(); }
373 module_iterator module_end() const { return Modules.end(); }