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