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 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" 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. 60 Module *SourceModule; 61 std::string SourceModuleName; 62 63 private: 64 /// \brief The top-level modules that are known. 65 llvm::StringMap<Module *> Modules; 66 67 public: 68 /// \brief Describes the role of a module header. 69 enum ModuleHeaderRole { 70 /// \brief This header is normally included in the module. 71 NormalHeader, 72 /// \brief This header is included but private. 73 PrivateHeader, 74 /// \brief This header is explicitly excluded from the module. 75 ExcludedHeader 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. 81 }; 82 83 /// \brief A header that is known to reside within a given module, 84 /// whether it was included or excluded. 85 class KnownHeader { 86 llvm::PointerIntPair<Module *, 2, ModuleHeaderRole> Storage; 87 88 public: 89 KnownHeader() : Storage(nullptr, NormalHeader) { } 90 KnownHeader(Module *M, ModuleHeaderRole Role) : Storage(M, Role) { } 91 92 /// \brief Retrieve the module the header is stored in. 93 Module *getModule() const { return Storage.getPointer(); } 94 95 /// \brief The role of this header within the module. 96 ModuleHeaderRole getRole() const { return Storage.getInt(); } 97 98 /// \brief Whether this header is available in the module. 99 bool isAvailable() const { 100 return getRole() != ExcludedHeader && getModule()->isAvailable(); 101 } 102 103 // \brief Whether this known header is valid (i.e., it has an 104 // associated module). 105 LLVM_EXPLICIT operator bool() const { 106 return Storage.getPointer() != nullptr; 107 } 108 }; 109 110 private: 111 typedef llvm::DenseMap<const FileEntry *, SmallVector<KnownHeader, 1> > 112 HeadersMap; 113 114 /// \brief Mapping from each header to the module that owns the contents of 115 /// that header. 116 HeadersMap Headers; 117 118 /// \brief Mapping from directories with umbrella headers to the module 119 /// that is generated from the umbrella header. 120 /// 121 /// This mapping is used to map headers that haven't explicitly been named 122 /// in the module map over to the module that includes them via its umbrella 123 /// header. 124 llvm::DenseMap<const DirectoryEntry *, Module *> UmbrellaDirs; 125 126 /// \brief A directory for which framework modules can be inferred. 127 struct InferredDirectory { 128 InferredDirectory() : InferModules(), InferSystemModules() { } 129 130 /// \brief Whether to infer modules from this directory. 131 unsigned InferModules : 1; 132 133 /// \brief Whether the modules we infer are [system] modules. 134 unsigned InferSystemModules : 1; 135 136 /// \brief If \c InferModules is non-zero, the module map file that allowed 137 /// inferred modules. Otherwise, nullptr. 138 const FileEntry *ModuleMapFile; 139 140 /// \brief The names of modules that cannot be inferred within this 141 /// directory. 142 SmallVector<std::string, 2> ExcludedModules; 143 }; 144 145 /// \brief A mapping from directories to information about inferring 146 /// framework modules from within those directories. 147 llvm::DenseMap<const DirectoryEntry *, InferredDirectory> InferredDirectories; 148 149 /// \brief Describes whether we haved parsed a particular file as a module 150 /// map. 151 llvm::DenseMap<const FileEntry *, bool> ParsedModuleMap; 152 153 friend class ModuleMapParser; 154 155 /// \brief Resolve the given export declaration into an actual export 156 /// declaration. 157 /// 158 /// \param Mod The module in which we're resolving the export declaration. 159 /// 160 /// \param Unresolved The export declaration to resolve. 161 /// 162 /// \param Complain Whether this routine should complain about unresolvable 163 /// exports. 164 /// 165 /// \returns The resolved export declaration, which will have a NULL pointer 166 /// if the export could not be resolved. 167 Module::ExportDecl 168 resolveExport(Module *Mod, const Module::UnresolvedExportDecl &Unresolved, 169 bool Complain) const; 170 171 /// \brief Resolve the given module id to an actual module. 172 /// 173 /// \param Id The module-id to resolve. 174 /// 175 /// \param Mod The module in which we're resolving the module-id. 176 /// 177 /// \param Complain Whether this routine should complain about unresolvable 178 /// module-ids. 179 /// 180 /// \returns The resolved module, or null if the module-id could not be 181 /// resolved. 182 Module *resolveModuleId(const ModuleId &Id, Module *Mod, bool Complain) const; 183 184 /// \brief Looks up the modules that \p File corresponds to. 185 /// 186 /// If \p File represents a builtin header within Clang's builtin include 187 /// directory, this also loads all of the module maps to see if it will get 188 /// associated with a specific module (e.g. in /usr/include). 189 HeadersMap::iterator findKnownHeader(const FileEntry *File); 190 191 /// \brief Searches for a module whose umbrella directory contains \p File. 192 /// 193 /// \param File The header to search for. 194 /// 195 /// \param IntermediateDirs On success, contains the set of directories 196 /// searched before finding \p File. 197 KnownHeader findHeaderInUmbrellaDirs(const FileEntry *File, 198 SmallVectorImpl<const DirectoryEntry *> &IntermediateDirs); 199 200 /// \brief A convenience method to determine if \p File is (possibly nested) 201 /// in an umbrella directory. 202 bool isHeaderInUmbrellaDirs(const FileEntry *File) { 203 SmallVector<const DirectoryEntry *, 2> IntermediateDirs; 204 return static_cast<bool>(findHeaderInUmbrellaDirs(File, IntermediateDirs)); 205 } 206 207 public: 208 /// \brief Construct a new module map. 209 /// 210 /// \param SourceMgr The source manager used to find module files and headers. 211 /// This source manager should be shared with the header-search mechanism, 212 /// since they will refer to the same headers. 213 /// 214 /// \param Diags A diagnostic engine used for diagnostics. 215 /// 216 /// \param LangOpts Language options for this translation unit. 217 /// 218 /// \param Target The target for this translation unit. 219 ModuleMap(SourceManager &SourceMgr, DiagnosticsEngine &Diags, 220 const LangOptions &LangOpts, const TargetInfo *Target, 221 HeaderSearch &HeaderInfo); 222 223 /// \brief Destroy the module map. 224 /// 225 ~ModuleMap(); 226 227 /// \brief Set the target information. 228 void setTarget(const TargetInfo &Target); 229 230 /// \brief Set the directory that contains Clang-supplied include 231 /// files, such as our stdarg.h or tgmath.h. 232 void setBuiltinIncludeDir(const DirectoryEntry *Dir) { 233 BuiltinIncludeDir = Dir; 234 } 235 236 /// \brief Retrieve the module that owns the given header file, if any. 237 /// 238 /// \param File The header file that is likely to be included. 239 /// 240 /// \param RequestingModule Specifies the module the header is intended to be 241 /// used from. Used to disambiguate if a header is present in multiple 242 /// modules. 243 /// 244 /// \returns The module KnownHeader, which provides the module that owns the 245 /// given header file. The KnownHeader is default constructed to indicate 246 /// that no module owns this header file. 247 KnownHeader findModuleForHeader(const FileEntry *File, 248 Module *RequestingModule = nullptr); 249 250 /// \brief Reports errors if a module must not include a specific file. 251 /// 252 /// \param RequestingModule The module including a file. 253 /// 254 /// \param FilenameLoc The location of the inclusion's filename. 255 /// 256 /// \param Filename The included filename as written. 257 /// 258 /// \param File The included file. 259 void diagnoseHeaderInclusion(Module *RequestingModule, 260 SourceLocation FilenameLoc, StringRef Filename, 261 const FileEntry *File); 262 263 /// \brief Determine whether the given header is part of a module 264 /// marked 'unavailable'. 265 bool isHeaderInUnavailableModule(const FileEntry *Header) const; 266 267 /// \brief Determine whether the given header is unavailable as part 268 /// of the specified module. 269 bool isHeaderUnavailableInModule(const FileEntry *Header, 270 const Module *RequestingModule) const; 271 272 /// \brief Retrieve a module with the given name. 273 /// 274 /// \param Name The name of the module to look up. 275 /// 276 /// \returns The named module, if known; otherwise, returns null. 277 Module *findModule(StringRef Name) const; 278 279 /// \brief Retrieve a module with the given name using lexical name lookup, 280 /// starting at the given context. 281 /// 282 /// \param Name The name of the module to look up. 283 /// 284 /// \param Context The module context, from which we will perform lexical 285 /// name lookup. 286 /// 287 /// \returns The named module, if known; otherwise, returns null. 288 Module *lookupModuleUnqualified(StringRef Name, Module *Context) const; 289 290 /// \brief Retrieve a module with the given name within the given context, 291 /// using direct (qualified) name lookup. 292 /// 293 /// \param Name The name of the module to look up. 294 /// 295 /// \param Context The module for which we will look for a submodule. If 296 /// null, we will look for a top-level module. 297 /// 298 /// \returns The named submodule, if known; otherwose, returns null. 299 Module *lookupModuleQualified(StringRef Name, Module *Context) const; 300 301 /// \brief Find a new module or submodule, or create it if it does not already 302 /// exist. 303 /// 304 /// \param Name The name of the module to find or create. 305 /// 306 /// \param Parent The module that will act as the parent of this submodule, 307 /// or NULL to indicate that this is a top-level module. 308 /// 309 /// \param ModuleMap The module map that defines or allows the inference of 310 /// this module. 311 /// 312 /// \param IsFramework Whether this is a framework module. 313 /// 314 /// \param IsExplicit Whether this is an explicit submodule. 315 /// 316 /// \returns The found or newly-created module, along with a boolean value 317 /// that will be true if the module is newly-created. 318 std::pair<Module *, bool> findOrCreateModule(StringRef Name, Module *Parent, 319 const FileEntry *ModuleMap, 320 bool IsFramework, 321 bool IsExplicit); 322 323 /// \brief Determine whether we can infer a framework module a framework 324 /// with the given name in the given 325 /// 326 /// \param ParentDir The directory that is the parent of the framework 327 /// directory. 328 /// 329 /// \param Name The name of the module. 330 /// 331 /// \param IsSystem Will be set to 'true' if the inferred module must be a 332 /// system module. 333 /// 334 /// \returns true if we are allowed to infer a framework module, and false 335 /// otherwise. 336 bool canInferFrameworkModule(const DirectoryEntry *ParentDir, 337 StringRef Name, bool &IsSystem) const; 338 339 /// \brief Infer the contents of a framework module map from the given 340 /// framework directory. 341 Module *inferFrameworkModule(StringRef ModuleName, 342 const DirectoryEntry *FrameworkDir, 343 bool IsSystem, Module *Parent); 344 345 /// \brief Retrieve the module map file containing the definition of the given 346 /// module. 347 /// 348 /// \param Module The module whose module map file will be returned, if known. 349 /// 350 /// \returns The file entry for the module map file containing the given 351 /// module, or NULL if the module definition was inferred. 352 const FileEntry *getContainingModuleMapFile(Module *Module) const; 353 354 /// \brief Resolve all of the unresolved exports in the given module. 355 /// 356 /// \param Mod The module whose exports should be resolved. 357 /// 358 /// \param Complain Whether to emit diagnostics for failures. 359 /// 360 /// \returns true if any errors were encountered while resolving exports, 361 /// false otherwise. 362 bool resolveExports(Module *Mod, bool Complain); 363 364 /// \brief Resolve all of the unresolved uses in the given module. 365 /// 366 /// \param Mod The module whose uses should be resolved. 367 /// 368 /// \param Complain Whether to emit diagnostics for failures. 369 /// 370 /// \returns true if any errors were encountered while resolving uses, 371 /// false otherwise. 372 bool resolveUses(Module *Mod, bool Complain); 373 374 /// \brief Resolve all of the unresolved conflicts in the given module. 375 /// 376 /// \param Mod The module whose conflicts should be resolved. 377 /// 378 /// \param Complain Whether to emit diagnostics for failures. 379 /// 380 /// \returns true if any errors were encountered while resolving conflicts, 381 /// false otherwise. 382 bool resolveConflicts(Module *Mod, bool Complain); 383 384 /// \brief Infers the (sub)module based on the given source location and 385 /// source manager. 386 /// 387 /// \param Loc The location within the source that we are querying, along 388 /// with its source manager. 389 /// 390 /// \returns The module that owns this source location, or null if no 391 /// module owns this source location. 392 Module *inferModuleFromLocation(FullSourceLoc Loc); 393 394 /// \brief Sets the umbrella header of the given module to the given 395 /// header. 396 void setUmbrellaHeader(Module *Mod, const FileEntry *UmbrellaHeader); 397 398 /// \brief Sets the umbrella directory of the given module to the given 399 /// directory. 400 void setUmbrellaDir(Module *Mod, const DirectoryEntry *UmbrellaDir); 401 402 /// \brief Adds this header to the given module. 403 /// \param Role The role of the header wrt the module. 404 void addHeader(Module *Mod, const FileEntry *Header, 405 ModuleHeaderRole Role); 406 407 /// \brief Parse the given module map file, and record any modules we 408 /// encounter. 409 /// 410 /// \param File The file to be parsed. 411 /// 412 /// \param IsSystem Whether this module map file is in a system header 413 /// directory, and therefore should be considered a system module. 414 /// 415 /// \returns true if an error occurred, false otherwise. 416 bool parseModuleMapFile(const FileEntry *File, bool IsSystem); 417 418 /// \brief Dump the contents of the module map, for debugging purposes. 419 void dump(); 420 421 typedef llvm::StringMap<Module *>::const_iterator module_iterator; 422 module_iterator module_begin() const { return Modules.begin(); } 423 module_iterator module_end() const { return Modules.end(); } 424 }; 425 426 } 427 #endif 428
