contrib/llvm/tools/clang/include/clang/Basic/Module.h

   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/SourceLocation.h"
  19 #include "llvm/ADT/PointerIntPair.h"
  20 #include "llvm/ADT/PointerUnion.h"
  21 #include "llvm/ADT/SetVector.h"
  22 #include "llvm/ADT/SmallVector.h"
  23 #include "llvm/ADT/StringMap.h"
  24 #include "llvm/ADT/StringRef.h"
  25 #include <string>
  26 #include <utility>
  27 #include <vector>
  28
  29 namespace llvm {
  30   class raw_ostream;
  31 }
  32
  33 namespace clang {
  34
  35 class DirectoryEntry;
  36 class FileEntry;
  37 class FileManager;
  38 class LangOptions;
  39 class TargetInfo;
  40
  41 /// \brief Describes the name of a module.
  42 typedef SmallVector<std::pair<std::string, SourceLocation>, 2> ModuleId;
  43
  44 /// \brief Describes a module or submodule.
  45 class Module {
  46 public:
  47   /// \brief The name of this module.
  48   std::string Name;
  49
  50   /// \brief The location of the module definition.
  51   SourceLocation DefinitionLoc;
  52
  53   /// \brief The parent of this module. This will be NULL for the top-level
  54   /// module.
  55   Module *Parent;
  56
  57   /// \brief The umbrella header or directory.
  58   llvm::PointerUnion<const DirectoryEntry *, const FileEntry *> Umbrella;
  59
  60 private:
  61   /// \brief The submodules of this module, indexed by name.
  62   std::vector<Module *> SubModules;
  63
  64   /// \brief A mapping from the submodule name to the index into the
  65   /// \c SubModules vector at which that submodule resides.
  66   llvm::StringMap<unsigned> SubModuleIndex;
  67
  68   /// \brief The AST file if this is a top-level module which has a
  69   /// corresponding serialized AST file, or null otherwise.
  70   const FileEntry *ASTFile;
  71
  72   /// \brief The top-level headers associated with this module.
  73   llvm::SmallSetVector<const FileEntry *, 2> TopHeaders;
  74
  75   /// \brief top-level header filenames that aren't resolved to FileEntries yet.
  76   std::vector<std::string> TopHeaderNames;
  77
  78 public:
  79   /// \brief The headers that are part of this module.
  80   SmallVector<const FileEntry *, 2> Headers;
  81
  82   /// \brief The headers that are explicitly excluded from this module.
  83   SmallVector<const FileEntry *, 2> ExcludedHeaders;
  84
  85   /// \brief The set of language features required to use this module.
  86   ///
  87   /// If any of these features is not present, the \c IsAvailable bit
  88   /// will be false to indicate that this (sub)module is not
  89   /// available.
  90   SmallVector<std::string, 2> Requires;
  91
  92   /// \brief Whether this module is available in the current
  93   /// translation unit.
  94   unsigned IsAvailable : 1;
  95
  96   /// \brief Whether this module was loaded from a module file.
  97   unsigned IsFromModuleFile : 1;
  98
  99   /// \brief Whether this is a framework module.
 100   unsigned IsFramework : 1;
 101
 102   /// \brief Whether this is an explicit submodule.
 103   unsigned IsExplicit : 1;
 104
 105   /// \brief Whether this is a "system" module (which assumes that all
 106   /// headers in it are system headers).
 107   unsigned IsSystem : 1;
 108
 109   /// \brief Whether we should infer submodules for this module based on
 110   /// the headers.
 111   ///
 112   /// Submodules can only be inferred for modules with an umbrella header.
 113   unsigned InferSubmodules : 1;
 114
 115   /// \brief Whether, when inferring submodules, the inferred submodules
 116   /// should be explicit.
 117   unsigned InferExplicitSubmodules : 1;
 118
 119   /// \brief Whether, when inferring submodules, the inferr submodules should
 120   /// export all modules they import (e.g., the equivalent of "export *").
 121   unsigned InferExportWildcard : 1;
 122
 123   /// \brief Whether the set of configuration macros is exhaustive.
 124   ///
 125   /// When the set of configuration macros is exhaustive, meaning
 126   /// that no identifier not in this list should affect how the module is
 127   /// built.
 128   unsigned ConfigMacrosExhaustive : 1;
 129
 130   /// \brief Describes the visibility of the various names within a
 131   /// particular module.
 132   enum NameVisibilityKind {
 133     /// \brief All of the names in this module are hidden.
 134     ///
 135     Hidden,
 136     /// \brief Only the macro names in this module are visible.
 137     MacrosVisible,
 138     /// \brief All of the names in this module are visible.
 139     AllVisible
 140   };
 141
 142   ///\ brief The visibility of names within this particular module.
 143   NameVisibilityKind NameVisibility;
 144
 145   /// \brief The location of the inferred submodule.
 146   SourceLocation InferredSubmoduleLoc;
 147
 148   /// \brief The set of modules imported by this module, and on which this
 149   /// module depends.
 150   SmallVector<Module *, 2> Imports;
 151
 152   /// \brief Describes an exported module.
 153   ///
 154   /// The pointer is the module being re-exported, while the bit will be true
 155   /// to indicate that this is a wildcard export.
 156   typedef llvm::PointerIntPair<Module *, 1, bool> ExportDecl;
 157
 158   /// \brief The set of export declarations.
 159   SmallVector<ExportDecl, 2> Exports;
 160
 161   /// \brief Describes an exported module that has not yet been resolved
 162   /// (perhaps because the module it refers to has not yet been loaded).
 163   struct UnresolvedExportDecl {
 164     /// \brief The location of the 'export' keyword in the module map file.
 165     SourceLocation ExportLoc;
 166
 167     /// \brief The name of the module.
 168     ModuleId Id;
 169
 170     /// \brief Whether this export declaration ends in a wildcard, indicating
 171     /// that all of its submodules should be exported (rather than the named
 172     /// module itself).
 173     bool Wildcard;
 174   };
 175
 176   /// \brief The set of export declarations that have yet to be resolved.
 177   SmallVector<UnresolvedExportDecl, 2> UnresolvedExports;
 178
 179   /// \brief A library or framework to link against when an entity from this
 180   /// module is used.
 181   struct LinkLibrary {
 182     LinkLibrary() : IsFramework(false) { }
 183     LinkLibrary(const std::string &Library, bool IsFramework)
 184       : Library(Library), IsFramework(IsFramework) { }
 185
 186     /// \brief The library to link against.
 187     ///
 188     /// This will typically be a library or framework name, but can also
 189     /// be an absolute path to the library or framework.
 190     std::string Library;
 191
 192     /// \brief Whether this is a framework rather than a library.
 193     bool IsFramework;
 194   };
 195
 196   /// \brief The set of libraries or frameworks to link against when
 197   /// an entity from this module is used.
 198   llvm::SmallVector<LinkLibrary, 2> LinkLibraries;
 199
 200   /// \brief The set of "configuration macros", which are macros that
 201   /// (intentionally) change how this module is built.
 202   std::vector<std::string> ConfigMacros;
 203
 204   /// \brief An unresolved conflict with another module.
 205   struct UnresolvedConflict {
 206     /// \brief The (unresolved) module id.
 207     ModuleId Id;
 208
 209     /// \brief The message provided to the user when there is a conflict.
 210     std::string Message;
 211   };
 212
 213   /// \brief The list of conflicts for which the module-id has not yet been
 214   /// resolved.
 215   std::vector<UnresolvedConflict> UnresolvedConflicts;
 216
 217   /// \brief A conflict between two modules.
 218   struct Conflict {
 219     /// \brief The module that this module conflicts with.
 220     Module *Other;
 221
 222     /// \brief The message provided to the user when there is a conflict.
 223     std::string Message;
 224   };
 225
 226   /// \brief The list of conflicts.
 227   std::vector<Conflict> Conflicts;
 228
 229   /// \brief Construct a top-level module.
 230   explicit Module(StringRef Name, SourceLocation DefinitionLoc,
 231                   bool IsFramework)
 232     : Name(Name), DefinitionLoc(DefinitionLoc), Parent(0),Umbrella(),ASTFile(0),
 233       IsAvailable(true), IsFromModuleFile(false), IsFramework(IsFramework),
 234       IsExplicit(false), IsSystem(false),
 235       InferSubmodules(false), InferExplicitSubmodules(false),
 236       InferExportWildcard(false), ConfigMacrosExhaustive(false),
 237       NameVisibility(Hidden) { }
 238
 239   /// \brief Construct a new module or submodule.
 240   Module(StringRef Name, SourceLocation DefinitionLoc, Module *Parent,
 241          bool IsFramework, bool IsExplicit);
 242
 243   ~Module();
 244
 245   /// \brief Determine whether this module is available for use within the
 246   /// current translation unit.
 247   bool isAvailable() const { return IsAvailable; }
 248
 249   /// \brief Determine whether this module is available for use within the
 250   /// current translation unit.
 251   ///
 252   /// \param LangOpts The language options used for the current
 253   /// translation unit.
 254   ///
 255   /// \param Target The target options used for the current translation unit.
 256   ///
 257   /// \param Feature If this module is unavailable, this parameter
 258   /// will be set to one of the features that is required for use of
 259   /// this module (but is not available).
 260   bool isAvailable(const LangOptions &LangOpts,
 261                    const TargetInfo &Target,
 262                    StringRef &Feature) const;
 263
 264   /// \brief Determine whether this module is a submodule.
 265   bool isSubModule() const { return Parent != 0; }
 266
 267   /// \brief Determine whether this module is a submodule of the given other
 268   /// module.
 269   bool isSubModuleOf(Module *Other) const;
 270
 271   /// \brief Determine whether this module is a part of a framework,
 272   /// either because it is a framework module or because it is a submodule
 273   /// of a framework module.
 274   bool isPartOfFramework() const {
 275     for (const Module *Mod = this; Mod; Mod = Mod->Parent)
 276       if (Mod->IsFramework)
 277         return true;
 278
 279     return false;
 280   }
 281
 282   /// \brief Determine whether this module is a subframework of another
 283   /// framework.
 284   bool isSubFramework() const {
 285     return IsFramework && Parent && Parent->isPartOfFramework();
 286   }
 287
 288   /// \brief Retrieve the full name of this module, including the path from
 289   /// its top-level module.
 290   std::string getFullModuleName() const;
 291
 292   /// \brief Retrieve the top-level module for this (sub)module, which may
 293   /// be this module.
 294   Module *getTopLevelModule() {
 295     return const_cast<Module *>(
 296              const_cast<const Module *>(this)->getTopLevelModule());
 297   }
 298
 299   /// \brief Retrieve the top-level module for this (sub)module, which may
 300   /// be this module.
 301   const Module *getTopLevelModule() const;
 302
 303   /// \brief Retrieve the name of the top-level module.
 304   ///
 305   StringRef getTopLevelModuleName() const {
 306     return getTopLevelModule()->Name;
 307   }
 308
 309   /// \brief The serialized AST file for this module, if one was created.
 310   const FileEntry *getASTFile() const {
 311     return getTopLevelModule()->ASTFile;
 312   }
 313
 314   /// \brief Set the serialized AST file for the top-level module of this module.
 315   void setASTFile(const FileEntry *File) {
 316     assert((getASTFile() == 0 || getASTFile() == File) && "file path changed");
 317     getTopLevelModule()->ASTFile = File;
 318   }
 319
 320   /// \brief Retrieve the directory for which this module serves as the
 321   /// umbrella.
 322   const DirectoryEntry *getUmbrellaDir() const;
 323
 324   /// \brief Retrieve the header that serves as the umbrella header for this
 325   /// module.
 326   const FileEntry *getUmbrellaHeader() const {
 327     return Umbrella.dyn_cast<const FileEntry *>();
 328   }
 329
 330   /// \brief Determine whether this module has an umbrella directory that is
 331   /// not based on an umbrella header.
 332   bool hasUmbrellaDir() const {
 333     return Umbrella && Umbrella.is<const DirectoryEntry *>();
 334   }
 335
 336   /// \brief Add a top-level header associated with this module.
 337   void addTopHeader(const FileEntry *File) {
 338     assert(File);
 339     TopHeaders.insert(File);
 340   }
 341
 342   /// \brief Add a top-level header filename associated with this module.
 343   void addTopHeaderFilename(StringRef Filename) {
 344     TopHeaderNames.push_back(Filename);
 345   }
 346
 347   /// \brief The top-level headers associated with this module.
 348   ArrayRef<const FileEntry *> getTopHeaders(FileManager &FileMgr);
 349
 350   /// \brief Add the given feature requirement to the list of features
 351   /// required by this module.
 352   ///
 353   /// \param Feature The feature that is required by this module (and
 354   /// its submodules).
 355   ///
 356   /// \param LangOpts The set of language options that will be used to
 357   /// evaluate the availability of this feature.
 358   ///
 359   /// \param Target The target options that will be used to evaluate the
 360   /// availability of this feature.
 361   void addRequirement(StringRef Feature, const LangOptions &LangOpts,
 362                       const TargetInfo &Target);
 363
 364   /// \brief Find the submodule with the given name.
 365   ///
 366   /// \returns The submodule if found, or NULL otherwise.
 367   Module *findSubmodule(StringRef Name) const;
 368
 369   typedef std::vector<Module *>::iterator submodule_iterator;
 370   typedef std::vector<Module *>::const_iterator submodule_const_iterator;
 371
 372   submodule_iterator submodule_begin() { return SubModules.begin(); }
 373   submodule_const_iterator submodule_begin() const {return SubModules.begin();}
 374   submodule_iterator submodule_end()   { return SubModules.end(); }
 375   submodule_const_iterator submodule_end() const { return SubModules.end(); }
 376
 377   /// \brief Returns the exported modules based on the wildcard restrictions.
 378   void getExportedModules(SmallVectorImpl<Module *> &Exported) const;
 379
 380   static StringRef getModuleInputBufferName() {
 381     return "<module-includes>";
 382   }
 383
 384   /// \brief Print the module map for this module to the given stream.
 385   ///
 386   void print(raw_ostream &OS, unsigned Indent = 0) const;
 387
 388   /// \brief Dump the contents of this module to the given output stream.
 389   void dump() const;
 390 };
 391
 392 } // end namespace clang
 393
 394
 395 #endif // LLVM_CLANG_BASIC_MODULE_H