contrib/llvm/tools/clang/include/clang/Lex/ModuleMap.h

   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