[clang] [clang][Modules] Refactor modulemap lookup & parse functions, NFCI (PR #235824)

Cyndy Ishida via cfe-commits cfe-commits at lists.llvm.org
Fri Oct 30 11:59:32 PDT 2026


https://github.com/cyndyishida updated https://github.com/llvm/llvm-project/pull/235824

>From 4e5aa6cdd50702bc002df94e6c5c90cb5dd05374 Mon Sep 17 00:00:00 2001
From: Cyndy Ishida <cyndy_ishida at apple.com>
Date: Tue, 20 Oct 2026 10:01:27 -0700
Subject: [PATCH] [clang][Modules] Refactor modulemap lookup & parse functions,
 NFCI

* Split `lookupModule` into seperable functions to isolate parsing from
  loading of a module.
* Do the same for `parseAndLoadModuleMapFile` functionality.
* Clarify related docstrings.

This is in effort to lookup modules without ever loading the full module
definition, which will be introduced in a follow up patch leveraging
lazy module map searching.
---
 clang/include/clang/Lex/HeaderSearch.h | 32 +++++++--
 clang/include/clang/Lex/ModuleMap.h    |  4 +-
 clang/lib/Lex/HeaderSearch.cpp         | 94 +++++++++++++++-----------
 3 files changed, 85 insertions(+), 45 deletions(-)

diff --git a/clang/include/clang/Lex/HeaderSearch.h b/clang/include/clang/Lex/HeaderSearch.h
index adaa126024c3ca..2e5659b3cce3d1 100644
--- a/clang/include/clang/Lex/HeaderSearch.h
+++ b/clang/include/clang/Lex/HeaderSearch.h
@@ -771,7 +771,7 @@ class HeaderSearch {
   ArrayRef<ModuleMap::KnownHeader>
   findResolvedModulesForHeader(FileEntryRef File) const;
 
-  /// Read the contents of the given module map file.
+  /// Read and load the contents of the given module map file.
   ///
   /// \param File The module map file.
   /// \param IsSystem Whether this file is in a system header directory.
@@ -801,6 +801,14 @@ class HeaderSearch {
   void loadTopLevelSystemModules();
 
 private:
+  /// Lookup a module by name, with retry support for private counterparts of
+  /// framework modules.
+  ///
+  /// \returns Whether the module was found.
+  bool lookupModuleWithPrivateFallbacks(StringRef ModuleName,
+                                        SourceLocation ImportLoc,
+                                        bool AllowExtraModuleMapSearch);
+
   /// Lookup a module with the given module name and search-name.
   ///
   /// \param ModuleName The name of the module we're looking for.
@@ -815,10 +823,10 @@ class HeaderSearch {
   /// \param AllowExtraModuleMapSearch Whether we allow to search modulemaps
   /// in subdirectories.
   ///
-  /// \returns The module named ModuleName.
-  Module *lookupModule(StringRef ModuleName, StringRef SearchName,
-                       SourceLocation ImportLoc,
-                       bool AllowExtraModuleMapSearch = false);
+  /// \returns Whether the module was found.
+  bool lookupModuleImpl(StringRef ModuleName, StringRef SearchName,
+                        SourceLocation ImportLoc,
+                        bool AllowExtraModuleMapSearch = false);
 
   /// Retrieve the name of the (to-be-)cached module file that should
   /// be used to load a module with the given name.
@@ -1013,16 +1021,26 @@ class HeaderSearch {
     MMR_InvalidModuleMap
   };
 
+  /// Determine if the \p Result of reading a modulemap failed.
+  static bool hasModuleMapError(ModuleMapResult Result);
+
+  /// Parse and load the module map \p File and its private module map.
   ModuleMapResult parseAndLoadModuleMapFileImpl(
       FileEntryRef File, bool IsSystem, bool ImplicitlyDiscovered,
       DirectoryEntryRef Dir, FileID ID = FileID(), unsigned *Offset = nullptr,
       bool DiagnosePrivMMap = false);
 
+  /// Parse the module map \p File and its private module map, without loading
+  /// the modules they define.
   ModuleMapResult parseModuleMapFileImpl(FileEntryRef File, bool IsSystem,
                                          bool ImplicitlyDiscovered,
                                          DirectoryEntryRef Dir,
                                          FileID ID = FileID());
 
+  /// Find the directory that resolves the modulemap represented in \p File.
+  OptionalDirectoryEntryRef
+  getModuleMapHomeDir(FileEntryRef File, StringRef OriginalModuleMapFile);
+
   /// Try to load the module map file in the given directory.
   ///
   /// \param DirName The name of the directory where we will look for a module
@@ -1049,9 +1067,13 @@ class HeaderSearch {
                                             bool ImplicitlyDiscovered,
                                             bool IsFramework);
 
+  /// Parse the module map file in the directory \p DirName.
+  /// Also loads the module unless module maps are loaded lazily.
   ModuleMapResult parseModuleMapFile(StringRef DirName, bool IsSystem,
                                      bool ImplicitlyDiscovered,
                                      bool IsFramework);
+
+  /// Same as above, but takes the directory as a DirectoryEntryRef.
   ModuleMapResult parseModuleMapFile(DirectoryEntryRef Dir, bool IsSystem,
                                      bool ImplicitlyDiscovered,
                                      bool IsFramework);
diff --git a/clang/include/clang/Lex/ModuleMap.h b/clang/include/clang/Lex/ModuleMap.h
index 18e77cc28ce4b5..ea37fc4702d54d 100644
--- a/clang/include/clang/Lex/ModuleMap.h
+++ b/clang/include/clang/Lex/ModuleMap.h
@@ -517,11 +517,11 @@ class ModuleMap {
   bool isHeaderUnavailableInModule(FileEntryRef Header,
                                    const Module *RequestingModule) const;
 
-  /// Retrieve a module with the given name.
+  /// Retrieve an already loaded module with the given name.
   ///
   /// \param Name The name of the module to look up.
   ///
-  /// \returns The named module, if known; otherwise, returns null.
+  /// \returns The named module, if loaded; otherwise, returns null.
   Module *findModule(StringRef Name) const;
 
   Module *findOrLoadModule(StringRef Name);
diff --git a/clang/lib/Lex/HeaderSearch.cpp b/clang/lib/Lex/HeaderSearch.cpp
index 6c47765cbad0df..08a05b7f3b0f38 100644
--- a/clang/lib/Lex/HeaderSearch.cpp
+++ b/clang/lib/Lex/HeaderSearch.cpp
@@ -305,32 +305,43 @@ Module *HeaderSearch::lookupModule(StringRef ModuleName,
   if (Module || !AllowSearch || !HSOpts.ImplicitModuleMaps)
     return Module;
 
+  if (!lookupModuleWithPrivateFallbacks(ModuleName, ImportLoc,
+                                        AllowExtraModuleMapSearch))
+    return nullptr;
+  return ModMap.findOrLoadModule(ModuleName);
+}
+
+bool HeaderSearch::lookupModuleWithPrivateFallbacks(
+    StringRef ModuleName, SourceLocation ImportLoc,
+    bool AllowExtraModuleMapSearch) {
   StringRef SearchName = ModuleName;
-  Module = lookupModule(ModuleName, SearchName, ImportLoc,
-                        AllowExtraModuleMapSearch);
+  if (lookupModuleImpl(ModuleName, SearchName, ImportLoc,
+                       AllowExtraModuleMapSearch))
+    return true;
 
   // The facility for "private modules" -- adjacent, optional module maps named
-  // module.private.modulemap that are supposed to define private submodules --
-  // may have different flavors of names: FooPrivate, Foo_Private and Foo.Private.
+  // module.private.modulemap that are supposed to define modules for private
+  // headers -- may have different flavors of names: FooPrivate, Foo_Private and
+  // Foo.Private.
   //
   // Foo.Private is now deprecated in favor of Foo_Private. Users of FooPrivate
   // should also rename to Foo_Private. Representing private as submodules
   // could force building unwanted dependencies into the parent module and cause
   // dependency cycles.
-  if (!Module && SearchName.consume_back("_Private"))
-    Module = lookupModule(ModuleName, SearchName, ImportLoc,
-                          AllowExtraModuleMapSearch);
-  if (!Module && SearchName.consume_back("Private"))
-    Module = lookupModule(ModuleName, SearchName, ImportLoc,
-                          AllowExtraModuleMapSearch);
-  return Module;
+  if (SearchName.consume_back("_Private") &&
+      lookupModuleImpl(ModuleName, SearchName, ImportLoc,
+                       AllowExtraModuleMapSearch))
+    return true;
+  if (SearchName.consume_back("Private") &&
+      lookupModuleImpl(ModuleName, SearchName, ImportLoc,
+                       AllowExtraModuleMapSearch))
+    return true;
+  return false;
 }
 
-Module *HeaderSearch::lookupModule(StringRef ModuleName, StringRef SearchName,
-                                   SourceLocation ImportLoc,
-                                   bool AllowExtraModuleMapSearch) {
-  Module *Module = nullptr;
-
+bool HeaderSearch::lookupModuleImpl(StringRef ModuleName, StringRef SearchName,
+                                    SourceLocation ImportLoc,
+                                    bool AllowExtraModuleMapSearch) {
   // Look through the various header search paths to load any available module
   // maps, searching for a module map that describes this module.
   for (DirectoryLookup &Dir : search_dir_range()) {
@@ -344,10 +355,9 @@ Module *HeaderSearch::lookupModule(StringRef ModuleName, StringRef SearchName,
       if (auto FrameworkDir =
               FileMgr.getOptionalDirectoryRef(FrameworkDirName)) {
         bool IsSystem = Dir.getDirCharacteristic() != SrcMgr::C_User;
-        Module = loadFrameworkModule(ModuleName, *FrameworkDir, IsSystem,
-                                     /*ImplicitlyDiscovered=*/true);
-        if (Module)
-          break;
+        if (loadFrameworkModule(ModuleName, *FrameworkDir, IsSystem,
+                                /*ImplicitlyDiscovered=*/true))
+          return true;
       }
     }
 
@@ -366,9 +376,8 @@ Module *HeaderSearch::lookupModule(StringRef ModuleName, StringRef SearchName,
                            /*IsFramework*/ false) == MMR_NewlyProcessed) {
       // We just parsed a module map file; check whether the module can be
       // loaded now.
-      Module = ModMap.findOrLoadModule(ModuleName);
-      if (Module)
-        break;
+      if (ModMap.findOrLoadModule(ModuleName))
+        return true;
     }
 
     // Search for a module map in a subdirectory with the same name as the
@@ -380,9 +389,8 @@ Module *HeaderSearch::lookupModule(StringRef ModuleName, StringRef SearchName,
                            /*ImplicitlyDiscovered=*/true,
                            /*IsFramework*/ false) == MMR_NewlyProcessed) {
       // If we just parsed a module map file, look for the module again.
-      Module = ModMap.findOrLoadModule(ModuleName);
-      if (Module)
-        break;
+      if (ModMap.findOrLoadModule(ModuleName))
+        return true;
     }
 
     if (HSOpts.AllowModuleMapSubdirectorySearch) {
@@ -397,13 +405,12 @@ Module *HeaderSearch::lookupModule(StringRef ModuleName, StringRef SearchName,
         loadSubdirectoryModuleMaps(Dir);
 
       // Look again for the module.
-      Module = ModMap.findOrLoadModule(ModuleName);
-      if (Module)
-        break;
+      if (ModMap.findOrLoadModule(ModuleName))
+        return true;
     }
   }
 
-  return Module;
+  return false;
 }
 
 void HeaderSearch::indexInitialHeaderMaps() {
@@ -2066,10 +2073,9 @@ static OptionalFileEntryRef getPrivateModuleMap(FileEntryRef File,
   return PMMFile;
 }
 
-bool HeaderSearch::parseAndLoadModuleMapFile(FileEntryRef File, bool IsSystem,
-                                             bool ImplicitlyDiscovered,
-                                             FileID ID, unsigned *Offset,
-                                             StringRef OriginalModuleMapFile) {
+OptionalDirectoryEntryRef
+HeaderSearch::getModuleMapHomeDir(FileEntryRef File,
+                                  StringRef OriginalModuleMapFile) {
   // Find the directory for the module. For frameworks, that may require going
   // up from the 'Modules' directory.
   OptionalDirectoryEntryRef Dir;
@@ -2101,11 +2107,23 @@ bool HeaderSearch::parseAndLoadModuleMapFile(FileEntryRef File, bool IsSystem,
       assert(Dir && "parent must exist");
     }
   }
+  return Dir;
+}
 
+bool HeaderSearch::parseAndLoadModuleMapFile(FileEntryRef File, bool IsSystem,
+                                             bool ImplicitlyDiscovered,
+                                             FileID ID, unsigned *Offset,
+                                             StringRef OriginalModuleMapFile) {
+  OptionalDirectoryEntryRef Dir =
+      getModuleMapHomeDir(File, OriginalModuleMapFile);
   assert(Dir && "module map home directory must exist");
-  switch (parseAndLoadModuleMapFileImpl(File, IsSystem, ImplicitlyDiscovered,
-                                        *Dir, ID, Offset,
-                                        /*DiagnosePrivMMap=*/true)) {
+  return hasModuleMapError(parseAndLoadModuleMapFileImpl(
+      File, IsSystem, ImplicitlyDiscovered, *Dir, ID, Offset,
+      /*DiagnosePrivMMap=*/true));
+}
+
+bool HeaderSearch::hasModuleMapError(ModuleMapResult Result) {
+  switch (Result) {
   case MMR_AlreadyProcessed:
   case MMR_NewlyProcessed:
     return false;
@@ -2113,7 +2131,7 @@ bool HeaderSearch::parseAndLoadModuleMapFile(FileEntryRef File, bool IsSystem,
   case MMR_InvalidModuleMap:
     return true;
   }
-  llvm_unreachable("Unknown load module map result");
+  llvm_unreachable("Unknown module map result");
 }
 
 HeaderSearch::ModuleMapResult HeaderSearch::parseAndLoadModuleMapFileImpl(



More information about the cfe-commits mailing list