[clang][lex] Remark on search path usage

[jansvoboda11]

Summary

For dependency scanning, it would be useful to collect header search paths (provided on command-line via -I and friends) that were actually used during preprocessing. This patch adds that feature to HeaderSearch along with a new remark that reports such paths as they get used.

Previous version of this patch tried to use the existing LookupFileCache to report used paths via HitIdx. That doesn't work for ComputeUserEntryUsage (which is intended to be called *after* preprocessing), because it indexes used search paths by the file name. This means the values get overwritten when the code contains #include_next.

Note that HeaderSearch doesn't use HeaderSearchOptions::UserEntries directly. Instead, InitHeaderSearch pre-processes them (adds platform-specific paths, removes duplicates, removes paths that don't exist) and creates DirectoryLookup instances. This means we need a mechanism for translating between those two. It's not possible to go from DirectoryLookup back to the original HeaderSearch, so InitHeaderSearch now tracks the relationships explicitly.

Depends on D111557.

[Bigcheese]

I think this is looking good, but would like either @dexonsmith, @akyrtzi, or someone else familiar with this area to take a look. Only other comment I have is that the new functions you add should use the current LLVM naming convention.

I also wonder how we should handle other things that are found via include paths such as module maps.

[jansvoboda11]

Fix naming of new functions/variables

[jansvoboda11]

In D102923#2781386, @Bigcheese wrote:

I also wonder how we should handle other things that are found via include paths such as module maps.

That's a good point. The logic for module map lookup is more complex than header lookup, so I'd be keen to tackle that in a follow-up patch.

[dexonsmith]

Thanks for your patience! I thought I already looked at this last week.

This is looking close. Comments mostly inline, but a high level point: I think this should report system search paths.

In D102923#2787001, @jansvoboda11 wrote:

In D102923#2781386, @Bigcheese wrote:

I also wonder how we should handle other things that are found via include paths such as module maps.

That's a good point. The logic for module map lookup is more complex than header lookup, so I'd be keen to tackle that in a follow-up patch.

Yup, seems like something that could be added as a follow up (although probably using the same remark). Is there a good place to leave behind a FIXME?

clang/include/clang/Basic/DiagnosticLexKinds.td

450

I suggest, more simply, "search path used:" (drop the "user-provided"). If you think it's useful for information purposes to know whether it was a user or system search path, I'd suggest using a select (in that case, maybe you want to add an optional "framework" descriptor, and/or "header map" when applicable, etc.).

451

I think it'd be better to define a DiagGroup in clang/include/clang/Basic/DiagnosticGroups.td and use it here.

It might be nice for it to be more general, and not refer to headers, so we can reuse it for module maps, and/or potentially other remarks. Maybe, -Rsearch-paths?

clang/include/clang/Lex/HeaderSearch.h

175–176

I think this can just be a vector of unsigned, since the key is densely packed and counting from 0. You can use ~0U for a sentinel for the non-entries. Maybe it's not too important though.

clang/lib/Frontend/InitHeaderSearch.cpp

581–583

I don't see why we'd want to filter out system includes.

• Users sometimes manually configure "system" search paths, and this remark is fairly special-purpose, so I'm not sure the distinction is interesting to preserve.
• This remark is already going to be "noisy" and hit a few times on essentially every compilation. Adding the system paths that get hit won't change that much.
• The motivation for the patch is to test the logic for detecting which search paths are used in isolation from the canonicalize-explicit-module-build-commands logic in clang-scan-deps. We need to know that the logic works for system search paths as well.

clang/test/Preprocessor/header-search-user-entries.c

1–4 ↗

(On Diff #348518)

Can we use -verify here? Or does that not work for remarks?

9–11 ↗

(On Diff #348518)

If -verify doesn't work (hopefully it does), I think you'll need to add some CHECK-NOT / CHECK-NEXT / etc. or else you're not testing for the absence of other diagnostics.

Please also test:

• Framework search path (used vs. not used)
• System search path (used vs. not used)
• One search path described relative to -isysroot (used vs. not used)
• Header map (matched and used vs. matched but not used vs. not matched -- for the middle case, I'm not sure what result we actually want)
• A path only used via #if __has_include() (when it's not followed by an #include or #import)
• A path only used via ObjC's #import

If one of them doesn't work and it's complex enough to separate into a follow up, I think that'd be fine, but please find somewhere to leave a FIXME.

[jansvoboda11]

In D102923#2787702, @dexonsmith wrote:

Yup, seems like something that could be added as a follow up (although probably using the same remark). Is there a good place to leave behind a FIXME?

I'll put a FIXME at an appropriate place in the next revision.

clang/include/clang/Basic/DiagnosticLexKinds.td

450

I chose this spelling to distinguish user-provided vs default include paths. The default ones are not important for header search pruning in dependency scanner, as they always get generated in InitHeaderSearch::AddDefaultIncludePaths.

clang/include/clang/Lex/HeaderSearch.h

175–176

I'm not sure what's our approach on early micro-optimizations like this. I don't think it will have measurable impact on memory or runtime.

clang/lib/Frontend/InitHeaderSearch.cpp

581–583

I'm not sure what you mean by system includes. HeaderSearchOptions::UserEntries should contain all search paths provided through the command-line including -isystem and -isysroot: https://github.com/llvm/llvm-project/blob/97d234935f1514af128277943f30efc469525371/clang/lib/Frontend/CompilerInvocation.cpp#L2985-L3056.

"System header prefixes" only control whether a header found through DirectoryLookup should be marked as system.

clang/test/Preprocessor/header-search-user-entries.c

9–11 ↗

(On Diff #348518)

Good point, I'll work on improving the coverage.

[dexonsmith]

clang/include/clang/Basic/DiagnosticLexKinds.td

450

Ah, I thought that logic was all moved to the driver. Looking at AddDefaultIncludePaths, you're right that only some things have moved, and some haven't (yet)...

For example, it looks like the only logic remaining in -cc1 on Darwin is:

// All header search logic is handled in the Driver for Darwin.
if (triple.isOSDarwin()) {
  if (HSOpts.UseStandardSystemIncludes) {
    // Add the default framework include paths on Darwin.
    AddPath("/System/Library/Frameworks", System, true);
    AddPath("/Library/Frameworks", System, true);
  }
  return;
}

(We should probably clean that up and move it to the driver as well...)

I think -cc1 can be agnostic about the source of the search path (user, IDE, driver, etc.).

clang/include/clang/Lex/HeaderSearch.h

175–176

Heh, maybe with the principle that the small things add up (or maybe just out of habit), I probably tend too much toward making small things efficient when it's easy. I also personally find Vector<Optional> just as natural a map data structure as DenseMap, but with more obvious allocation / etc. But yeah, probably not important.

clang/lib/Frontend/InitHeaderSearch.cpp

581–583

Thanks for explaining; you're right, I was confused. (Maybe this should be renamed from UserEntries to CommandLineEntries if it has everything on the command-line?)

As I mentioned above, the distinction between driver-generated and -cc1-generated options is a bit murky (and moving in the direction of removing the latter), so I'm not sure it's meaningful to filter out -cc1-generated options.

[jansvoboda11]

Rebase, handle module maps, add more tests

[jansvoboda11]

I believe I've addressed all suggestions provided so far. @dexonsmith & @Bigcheese, can you check again?

clang/test/Preprocessor/header-search-user-entries.c

9–11 ↗

(On Diff #348518)

I tried using -verify together with expected-remark-re (to match relative paths) and @* (to match any/no line number), but those don't seem to work together.

This expectation:

// expected-remark-re @* {{search path used: '{{.*}}/search-path-usage/FwA'}}

produces:

error: 'error' diagnostics seen but not expected: 
  File /Users/Jan/Code/upstream-llvm/clang/test/Preprocessor/search-path-usage-headers.m Line 30: cannot find start ('{{') of expected regex
error: 'remark' diagnostics seen but not expected: 
  (frontend): search path used: '/Users/Jan/Code/upstream-llvm/clang/test/Preprocessor/Inputs/search-path-usage/FwA'
2 errors generated.

If I drop @*, stuff doesn't work (presumably because of line numbers):

error: 'remark' diagnostics expected but not seen: 
  File /Users/Jan/Code/upstream-llvm/clang/test/Preprocessor/search-path-usage-headers.m Line 30: search path used: '{{.*}}/search-path-usage/FwA'
error: 'remark' diagnostics seen but not expected: 
  (frontend): search path used: '/Users/Jan/Code/upstream-llvm/clang/test/Preprocessor/Inputs/search-path-usage/FwA'
2 errors generated.

Let me know if I'm doing something wrong. In the meantime, I made the FileCheck checks more thorough as you suggested.

[jansvoboda11]

clang/test/Preprocessor/header-search-user-entries.c

9–11 ↗

(On Diff #348518)

• Header map (matched and used vs. matched but not used vs. not matched -- for the middle case, I'm not sure what result we actually want)

Can you clarify what you mean by "matched" and "used" exactly?

[dexonsmith]

clang/test/Preprocessor/header-search-user-entries.c

9–11 ↗

(On Diff #348518)

Oh, I hadn't realized the diagnostic doesn't have a source location. Is there a reason it has no location right now?

Seems like pointing at the first #include that triggers it would be ideal, showing the include stack if there is one.

9–11 ↗

(On Diff #348518)

• Header map (matched and used vs. matched but not used vs. not matched

Can you clarify what you mean by "matched" and "used" exactly?

Assume "hmap" is a header map with the edge a.h -> b.h.

• "Matched" means the header map is queried with "a.h" (or "A.H", or whatever).
• "Used" means "b.h" is subsequently found on disk.

I think the way header maps work, a "matched but not used" would typically result in a compile error... since once the path is converted to "b.h" there's no going back. But here's a scenario would it wouldn't be an error:

#if __has_include("a.h")
#include "a.h"
#endif

The __has_include("a.h") would match in the header map, converting to "b.h", but there's no error when "b.h" isn't found on disk.

for the middle case, I'm not sure what result we actually want

Thinking about it more, I think we need it to count as a use of the header map whenever there's a match (regardless of what happens downstream after the path replacement), because it can affect the result.

With this setup:

% find . -type f
include/a.h
include/c.h
t.c
hmap
% clang -Ihmap -Iinclude -E t.c

(same header map, a.h -> b.h)

Here's an example of the "middle" case, matched but not used, where by my logic above the header map needs a remark:

% cat t.c
#include "a.h"

... because removing the -Ihmap changes the result of the compilation.

Here's the third case, not matched, where the remark shouldn't trigger since -Ihmap does not affect the compilation:

% cat t.c
#include "c.h"

[dexonsmith]

clang/test/Preprocessor/header-search-user-entries.c

9–11 ↗

(On Diff #348518)

... my point being that it should be easy to specify the location, and then you're not having to combine @* with -re:

#include "some-header" // \
  // expected-remark-re {{source path used '{{.*}}/search-path-used/FwA'}} \
  // expected-remark {{some other diagnostic on the same line}}
#include "some-other-header"
  // expected-remark-re @-1 {{source path used '{{.*}}/search-path-used/FwA'}}

For the diagnostics in the headers, which might be included in other tests, probably simplest to add a marker:

// In the x.h
#include "y.h" // #x-include-y

// In the test
// expected-remark-re @#x-include-y {{...}
#include "x.h" // expected-note {{...}}

but you could also use -verify=name-of-test and use name-of-test-remark in x.h to avoid affecting other tests.

[jansvoboda11]

Add SourceLocation to remarks and test with -verify

[dexonsmith]

Thanks; I think this was worth it. I like how clean it looks with -verify in place.

LGTM if you add a couple more header map tests, explained inline.

clang/test/Preprocessor/search-path-usage-headers.m

78–91 ↗

(On Diff #378702)

This is a good positive test, but I don't see a negative test or the "matched but not ultimately found" case I mentioned before.

You can add a RUN like this for the negative test:

// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
//      -I%t/b.hmap                              \
//      -I%S/Inputs/search-path-usage/d          \
//      -DHMAP_NO_MATCH -verify
#ifdef HMAP_NO_MATCH
#include "d.h" // expected-remark {{search path used: ../d'}}
#endif

(same hmap, but not found in the headermap)

and like this for the "matched in header map but not ultimately found" case (different hmap, pointing at a file that won't be found):

// RUN: sed "s|DIR|%/S/Inputs/search-path-usage/missing-subdir|g" \
// RUN:             %S/Inputs/search-path-usage/b.hmap.json.template > %t/b-missing.hmap.json
// RUN: %hmaptool write %t/b-missing.hmap.json %t/b-missing.hmap
// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
// RUN:   -I %t/b-missing.hmap                   \
// RUN:   -I b                                   \
// RUN:   -DHMAP_MATCHED_BUT_MISSING -verify
#ifdef HMAP_MATCHED_BUT_MISSING
#include "b.h" // \
  // expected-remark {{search path used: ../b-missing.hmap}} \
  // expected-error {{file not found: "b.h" [or whatever it is in the end]}}
#endif

(Maybe would be good to have a __has_include-matched-but-missing test as well? I'll leave it up to you.)

[jansvoboda11]

Report matched header maps even when target file does not exist, add tests.

[jansvoboda11]

Thanks for the review, I handled the header map case and added tests. I'll commit once the CI passes.

clang/lib/Lex/HeaderSearch.cpp

473

Note: Here's the header map special case for when a file matched but does not exist.

[teemperor]

This seems to have broken compiling some versions of Foundation/Dispatch with -fmodules enabled (which breaks the LLDB test suite when it tries to compile any Objective-C tests). Can you take a look and/or revert? I mailed you the version/compiler errors.

[dexonsmith]

In D102923#3059592, @teemperor wrote:

This seems to have broken compiling some versions of Foundation/Dispatch with -fmodules enabled (which breaks the LLDB test suite when it tries to compile any Objective-C tests). Can you take a look and/or revert? I mailed you the version/compiler errors.

FYI, Jan is in Europe; if this is blocking LLDB I suggest reverting and he can evaluate tomorrow. (I'm a bit surprised this commit triggers a failure anywhere since it should be NFC aside from remarks, but I guess there must be a logic issue.)

[jansvoboda11]

Fixed in 28fa77feeb7db46abea1a6699d7a88a02d8dab46.

clang/include/clang/Basic/DiagnosticGroups.td

 def UnusedConstVariable : DiagGroup<"unused-const-variable">;
 def UnusedVariable : DiagGroup<"unused-variable",
                                [UnusedConstVariable]>;
 def UnusedButSetVariable : DiagGroup<"unused-but-set-variable">;
 def UnusedLocalTypedef : DiagGroup<"unused-local-typedef">;
 def UnusedPropertyIvar :  DiagGroup<"unused-property-ivar">;
 def UnusedGetterReturnValue : DiagGroup<"unused-getter-return-value">;
 def UsedButMarkedUnused : DiagGroup<"used-but-marked-unused">;
+def UsedSearchPath : DiagGroup<"search-path-usage">;
 def UserDefinedLiterals : DiagGroup<"user-defined-literals">;
 def UserDefinedWarnings : DiagGroup<"user-defined-warnings">;
 def ReorderCtor : DiagGroup<"reorder-ctor">;
 def ReorderInitList : DiagGroup<"reorder-init-list">;
 def Reorder : DiagGroup<"reorder", [ReorderCtor, ReorderInitList]>;
 def UndeclaredSelector : DiagGroup<"undeclared-selector">;
 def ImplicitAtomic : DiagGroup<"implicit-atomic-properties">;
 def AtomicAlignment : DiagGroup<"atomic-alignment">;

clang/include/clang/Basic/DiagnosticLexKinds.td

def err_pp_pragma_hdrstop_not_seen : Error<
   DefaultFatal;
 def warn_pp_macro_def_mismatch_with_pch : Warning<
   "definition of macro %0 does not match definition in precompiled header">,
   InGroup<ClangClPch>;
 def warn_pp_hdrstop_filename_ignored : Warning<
   "#pragma hdrstop filename not supported, "
   "/Fp can be used to specify precompiled header filename">,
   InGroup<ClangClPch>;
+def remark_pp_search_path_usage : Remark<
+  "search path used: '%0'">,
+  InGroup<UsedSearchPath>;
 def err_pp_file_not_found_angled_include_not_fatal : Error<
   "'%0' file not found with <angled> %select{include|import}1; "
   "use \"quotes\" instead">;
 def err_pp_file_not_found_typo_not_fatal
     : Error<"'%0' file not found, did you mean '%1'?">;
 def note_pp_framework_without_header : Note<
   "did not find header '%0' in framework '%1' (loaded from '%2')">;
 def err_pp_error_opening_file : Error<

clang/include/clang/Lex/HeaderMap.h

HeaderMap(std::unique_ptr<const llvm::MemoryBuffer> File, bool BSwap)
       : HeaderMapImpl(std::move(File), BSwap) {}
 
 public:
   /// This attempts to load the specified file as a header map.  If it doesn't
   /// look like a HeaderMap, it gives up and returns null.
   static std::unique_ptr<HeaderMap> Create(const FileEntry *FE,
                                            FileManager &FM);
 
-  /// Check to see if the specified relative filename is located in this
-  /// HeaderMap.  If so, open it and return its FileEntry.  If RawPath is not
-  /// NULL and the file is found, RawPath will be set to the raw path at which
-  /// the file was found in the file system. For example, for a search path
-  /// ".." and a filename "../file.h" this would be "../../file.h".
-  Optional<FileEntryRef> LookupFile(StringRef Filename, FileManager &FM) const;
-
   using HeaderMapImpl::dump;
   using HeaderMapImpl::getFileName;
   using HeaderMapImpl::lookupFilename;
   using HeaderMapImpl::reverseLookupFilename;
 };
 
 } // end namespace clang.
 
 #endif

clang/include/clang/Lex/HeaderSearch.h

 /// Encapsulates the information needed to find the file referenced
 /// by a \#include or \#include_next, (sub-)framework lookup, etc.
 class HeaderSearch {
   friend class DirectoryLookup;
 
   /// Header-search options used to initialize this header search.
   std::shared_ptr<HeaderSearchOptions> HSOpts;
 
+  /// Mapping from SearchDir to HeaderSearchOptions::UserEntries indices.
+  llvm::DenseMap<unsigned, unsigned> SearchDirToHSEntry;
+
   DiagnosticsEngine &Diags;
   FileManager &FileMgr;
 
   /// \#include search path information.  Requests for \#include "x" search the
   /// directory of the \#including file first, then each directory in SearchDirs
   /// consecutively. Requests for <x> search the current dir first, then each
   /// directory in SearchDirs, starting at AngledDirIdx, consecutively.  If
   /// NoCurDirSearch is true, then the check for the file in the current
   /// directory is suppressed.
   std::vector<DirectoryLookup> SearchDirs;
+  /// Whether the DirectoryLookup at the corresponding index in SearchDirs has
+  /// been successfully used to lookup a file.
+  std::vector<bool> SearchDirsUsage;
   unsigned AngledDirIdx = 0;
   unsigned SystemDirIdx = 0;
   bool NoCurDirSearch = false;
 
   /// \#include prefixes for which the 'system header' property is
   /// overridden.
   ///
   /// For a \#include "x" or \#include \<x> directive, the last string in this
public:
   /// was initialized.
   HeaderSearchOptions &getHeaderSearchOpts() const { return *HSOpts; }
 
   FileManager &getFileMgr() const { return FileMgr; }
 
   DiagnosticsEngine &getDiags() const { return Diags; }
 
   /// Interface for setting the file search paths.
-  void SetSearchPaths(const std::vector<DirectoryLookup> &dirs,
-                      unsigned angledDirIdx, unsigned systemDirIdx,
-                      bool noCurDirSearch) {
+  void SetSearchPaths(std::vector<DirectoryLookup> dirs, unsigned angledDirIdx,
+                      unsigned systemDirIdx, bool noCurDirSearch,
+                      llvm::DenseMap<unsigned, unsigned> searchDirToHSEntry) {
     assert(angledDirIdx <= systemDirIdx && systemDirIdx <= dirs.size() &&
         "Directory indices are unordered");
-    SearchDirs = dirs;
+    SearchDirs = std::move(dirs);
+    SearchDirsUsage.assign(SearchDirs.size(), false);
     AngledDirIdx = angledDirIdx;
     SystemDirIdx = systemDirIdx;
     NoCurDirSearch = noCurDirSearch;
+    SearchDirToHSEntry = std::move(searchDirToHSEntry);
     //LookupFileCache.clear();
   }
 
   /// Add an additional search path.
   void AddSearchPath(const DirectoryLookup &dir, bool isAngled) {
     unsigned idx = isAngled ? SystemDirIdx : AngledDirIdx;
     SearchDirs.insert(SearchDirs.begin() + idx, dir);
+    SearchDirsUsage.insert(SearchDirsUsage.begin() + idx, false);
     if (!isAngled)
       AngledDirIdx++;
     SystemDirIdx++;
   }
 
   /// Set the list of system header prefixes.
   void SetSystemHeaderPrefixes(ArrayRef<std::pair<std::string, bool>> P) {
     SystemHeaderPrefixes.assign(P.begin(), P.end());
public:
   bool isFileMultipleIncludeGuarded(const FileEntry *File);
 
   /// Determine whether the given file is known to have ever been \#imported.
   bool hasFileBeenImported(const FileEntry *File) {
     const HeaderFileInfo *FI = getExistingFileInfo(File);
     return FI && FI->isImport;
   }
 
+  /// Determine which HeaderSearchOptions::UserEntries have been successfully
+  /// used so far and mark their index with 'true' in the resulting bit vector.
+  std::vector<bool> computeUserEntryUsage() const;
+
   /// This method returns a HeaderMap for the specified
   /// FileEntry, uniquing them through the 'HeaderMaps' datastructure.
   const HeaderMap *CreateHeaderMap(const FileEntry *FE);
 
   /// Get filenames for all registered header maps.
   void getHeaderMapFileNames(SmallVectorImpl<std::string> &Names) const;
 
   /// Retrieve the name of the cached module file that should be used
private:
   /// Look up the file with the specified name and determine its owning
   /// module.
   Optional<FileEntryRef>
   getFileAndSuggestModule(StringRef FileName, SourceLocation IncludeLoc,
                           const DirectoryEntry *Dir, bool IsSystemHeaderDir,
                           Module *RequestingModule,
                           ModuleMap::KnownHeader *SuggestedModule);
 
+  /// Cache the result of a successful lookup at the given include location
+  /// using the search path at index `HitIdx`.
+  void cacheLookupSuccess(LookupFileCacheInfo &CacheLookup, unsigned HitIdx,
+                          SourceLocation IncludeLoc);
+  /// Note that a lookup at the given include location was successful using the
+  /// search path at index `HitIdx`.
+  void noteLookupUsage(unsigned HitIdx, SourceLocation IncludeLoc);
+
 public:
   /// Retrieve the module map.
   ModuleMap &getModuleMap() { return ModMap; }
 
   /// Retrieve the module map.
   const ModuleMap &getModuleMap() const { return ModMap; }
 
   unsigned header_file_size() const { return FileInfo.size(); }
public:
   }
 
   search_dir_iterator system_dir_begin() const {
     return SearchDirs.begin() + SystemDirIdx;
   }
 
   search_dir_iterator system_dir_end() const { return SearchDirs.end(); }
 
+  /// Get the index of the given search directory.
+  Optional<unsigned> searchDirIdx(const DirectoryLookup &DL) const;
+
   /// Retrieve a uniqued framework name.
   StringRef getUniqueFrameworkName(StringRef Framework);
 
   /// Suggest a path by which the specified file could be found, for use in
   /// diagnostics to suggest a #include. Returned path will only contain forward
   /// slashes as separators. MainFile is the absolute path of the file that we
   /// are generating the diagnostics for. It will try to shorten the path using
   /// MainFile location, if none of the include search directories were prefix

clang/lib/Frontend/InitHeaderSearch.cpp

 using namespace clang;
 using namespace clang::frontend;
 
 namespace {
 /// Holds information about a single DirectoryLookup object.
 struct DirectoryLookupInfo {
   IncludeDirGroup Group;
   DirectoryLookup Lookup;
+  Optional<unsigned> UserEntryIdx;
 
-  DirectoryLookupInfo(IncludeDirGroup Group, DirectoryLookup Lookup)
-      : Group(Group), Lookup(Lookup) {}
+  DirectoryLookupInfo(IncludeDirGroup Group, DirectoryLookup Lookup,
+                      Optional<unsigned> UserEntryIdx)
+      : Group(Group), Lookup(Lookup), UserEntryIdx(UserEntryIdx) {}
 };
 
 /// InitHeaderSearch - This class makes it easier to set the search paths of
 ///  a HeaderSearch object. InitHeaderSearch stores several search path lists
 ///  internally, which can be sent to a HeaderSearch object in one swoop.
 class InitHeaderSearch {
   std::vector<DirectoryLookupInfo> IncludePath;
   std::vector<std::pair<std::string, bool> > SystemHeaderPrefixes;
   HeaderSearch &Headers;
   bool Verbose;
   std::string IncludeSysroot;
   bool HasSysroot;
 
 public:
   InitHeaderSearch(HeaderSearch &HS, bool verbose, StringRef sysroot)
       : Headers(HS), Verbose(verbose), IncludeSysroot(std::string(sysroot)),
         HasSysroot(!(sysroot.empty() || sysroot == "/")) {}
 
   /// AddPath - Add the specified path to the specified group list, prefixing
   /// the sysroot if used.
   /// Returns true if the path exists, false if it was ignored.
-  bool AddPath(const Twine &Path, IncludeDirGroup Group, bool isFramework);
+  bool AddPath(const Twine &Path, IncludeDirGroup Group, bool isFramework,
+               Optional<unsigned> UserEntryIdx = None);
 
   /// AddUnmappedPath - Add the specified path to the specified group list,
   /// without performing any sysroot remapping.
   /// Returns true if the path exists, false if it was ignored.
   bool AddUnmappedPath(const Twine &Path, IncludeDirGroup Group,
-                       bool isFramework);
+                       bool isFramework,
+                       Optional<unsigned> UserEntryIdx = None);
 
   /// AddSystemHeaderPrefix - Add the specified prefix to the system header
   /// prefix list.
   void AddSystemHeaderPrefix(StringRef Prefix, bool IsSystemHeader) {
     SystemHeaderPrefixes.emplace_back(std::string(Prefix), IsSystemHeader);
   }
 
   /// AddGnuCPlusPlusIncludePaths - Add the necessary paths to support a gnu

 #if defined(_WIN32)
   return !Path.empty() && llvm::sys::path::is_separator(Path[0]);
 #else
   return llvm::sys::path::is_absolute(Path);
 #endif
 }
 
 bool InitHeaderSearch::AddPath(const Twine &Path, IncludeDirGroup Group,
-                               bool isFramework) {
+                               bool isFramework,
+                               Optional<unsigned> UserEntryIdx) {
   // Add the path with sysroot prepended, if desired and this is a system header
   // group.
   if (HasSysroot) {
     SmallString<256> MappedPathStorage;
     StringRef MappedPathStr = Path.toStringRef(MappedPathStorage);
     if (CanPrefixSysroot(MappedPathStr)) {
-      return AddUnmappedPath(IncludeSysroot + Path, Group, isFramework);
+      return AddUnmappedPath(IncludeSysroot + Path, Group, isFramework,
+                             UserEntryIdx);
     }
   }
 
-  return AddUnmappedPath(Path, Group, isFramework);
+  return AddUnmappedPath(Path, Group, isFramework, UserEntryIdx);
 }
 
 bool InitHeaderSearch::AddUnmappedPath(const Twine &Path, IncludeDirGroup Group,
-                                       bool isFramework) {
+                                       bool isFramework,
+                                       Optional<unsigned> UserEntryIdx) {
   assert(!Path.isTriviallyEmpty() && "can't handle empty path here");
 
   FileManager &FM = Headers.getFileMgr();
   SmallString<256> MappedPathStorage;
   StringRef MappedPathStr = Path.toStringRef(MappedPathStorage);
 
   // If use system headers while cross-compiling, emit the warning.
   if (HasSysroot && (MappedPathStr.startswith("/usr/include") ||
bool InitHeaderSearch::AddUnmappedPath(const Twine &Path, IncludeDirGroup Group,
   } else if (Group == ExternCSystem) {
     Type = SrcMgr::C_ExternCSystem;
   } else {
     Type = SrcMgr::C_System;
   }
 
   // If the directory exists, add it.
   if (auto DE = FM.getOptionalDirectoryRef(MappedPathStr)) {
-    IncludePath.emplace_back(Group, DirectoryLookup(*DE, Type, isFramework));
+    IncludePath.emplace_back(Group, DirectoryLookup(*DE, Type, isFramework),
+                             UserEntryIdx);
     return true;
   }
 
   // Check to see if this is an apple-style headermap (which are not allowed to
   // be frameworks).
   if (!isFramework) {
     if (auto FE = FM.getFile(MappedPathStr)) {
       if (const HeaderMap *HM = Headers.CreateHeaderMap(*FE)) {
         // It is a headermap, add it to the search path.
         IncludePath.emplace_back(
-            Group, DirectoryLookup(HM, Type, Group == IndexHeaderMap));
+            Group, DirectoryLookup(HM, Type, Group == IndexHeaderMap),
+            UserEntryIdx);
         return true;
       }
     }
   }
 
   if (Verbose)
     llvm::errs() << "ignoring nonexistent directory \""
                  << MappedPathStr << "\"\n";
void InitHeaderSearch::AddDefaultIncludePaths(const LangOptions &Lang,
   }
 
   AddDefaultCIncludePaths(triple, HSOpts);
 }
 
 /// RemoveDuplicates - If there are duplicate directory entries in the specified
 /// search list, remove the later (dead) ones.  Returns the number of non-system
 /// headers removed, which is used to update NumAngled.
-static unsigned RemoveDuplicates(std::vector<DirectoryLookup> &SearchList,
+static unsigned RemoveDuplicates(std::vector<DirectoryLookupInfo> &SearchList,
                                  unsigned First, bool Verbose) {
   llvm::SmallPtrSet<const DirectoryEntry *, 8> SeenDirs;
   llvm::SmallPtrSet<const DirectoryEntry *, 8> SeenFrameworkDirs;
   llvm::SmallPtrSet<const HeaderMap *, 8> SeenHeaderMaps;
   unsigned NonSystemRemoved = 0;
   for (unsigned i = First; i != SearchList.size(); ++i) {
     unsigned DirToRemove = i;
 
-    const DirectoryLookup &CurEntry = SearchList[i];
+    const DirectoryLookup &CurEntry = SearchList[i].Lookup;
 
     if (CurEntry.isNormalDir()) {
       // If this isn't the first time we've seen this dir, remove it.
       if (SeenDirs.insert(CurEntry.getDir()).second)
         continue;
     } else if (CurEntry.isFramework()) {
       // If this isn't the first time we've seen this framework dir, remove it.
       if (SeenFrameworkDirs.insert(CurEntry.getFrameworkDir()).second)
for (unsigned i = First; i != SearchList.size(); ++i) {
     // Since dupes of system dirs are rare, just rescan to find the original
     // that we're nuking instead of using a DenseMap.
     if (CurEntry.getDirCharacteristic() != SrcMgr::C_User) {
       // Find the dir that this is the same of.
       unsigned FirstDir;
       for (FirstDir = First;; ++FirstDir) {
         assert(FirstDir != i && "Didn't find dupe?");
 
-        const DirectoryLookup &SearchEntry = SearchList[FirstDir];
+        const DirectoryLookup &SearchEntry = SearchList[FirstDir].Lookup;
 
         // If these are different lookup types, then they can't be the dupe.
         if (SearchEntry.getLookupType() != CurEntry.getLookupType())
           continue;
 
         bool isSame;
         if (CurEntry.isNormalDir())
           isSame = SearchEntry.getDir() == CurEntry.getDir();
         else if (CurEntry.isFramework())
           isSame = SearchEntry.getFrameworkDir() == CurEntry.getFrameworkDir();
         else {
           assert(CurEntry.isHeaderMap() && "Not a headermap or normal dir?");
           isSame = SearchEntry.getHeaderMap() == CurEntry.getHeaderMap();
         }
 
         if (isSame)
           break;
       }
 
       // If the first dir in the search path is a non-system dir, zap it
       // instead of the system one.
-      if (SearchList[FirstDir].getDirCharacteristic() == SrcMgr::C_User)
+      if (SearchList[FirstDir].Lookup.getDirCharacteristic() == SrcMgr::C_User)
         DirToRemove = FirstDir;
     }
 
     if (Verbose) {
       llvm::errs() << "ignoring duplicate directory \""
                    << CurEntry.getName() << "\"\n";
       if (DirToRemove != i)
         llvm::errs() << "  as it is a non-system directory that duplicates "
                      << "a system directory\n";
     }
     if (DirToRemove != i)
       ++NonSystemRemoved;
 
     // This is reached if the current entry is a duplicate.  Remove the
     // DirToRemove (usually the current dir).
     SearchList.erase(SearchList.begin()+DirToRemove);
     --i;
   }
   return NonSystemRemoved;
 }
 
+/// Extract DirectoryLookups from DirectoryLookupInfos.
+static std::vector<DirectoryLookup>
+extractLookups(const std::vector<DirectoryLookupInfo> &Infos) {
+  std::vector<DirectoryLookup> Lookups;
+  Lookups.reserve(Infos.size());
+  llvm::transform(Infos, std::back_inserter(Lookups),
+                  [](const DirectoryLookupInfo &Info) { return Info.Lookup; });
+  return Lookups;
+}
+
+/// Collect the mapping between indices of DirectoryLookups and UserEntries.
+static llvm::DenseMap<unsigned, unsigned>
+mapToUserEntries(const std::vector<DirectoryLookupInfo> &Infos) {
+  llvm::DenseMap<unsigned, unsigned> LookupsToUserEntries;
+  for (unsigned I = 0, E = Infos.size(); I < E; ++I) {
+    // Check whether this DirectoryLookup maps to a HeaderSearch::UserEntry.
+    if (Infos[I].UserEntryIdx)
+      LookupsToUserEntries.insert({I, *Infos[I].UserEntryIdx});
+  }
+  return LookupsToUserEntries;
+}
 
 void InitHeaderSearch::Realize(const LangOptions &Lang) {
   // Concatenate ANGLE+SYSTEM+AFTER chains together into SearchList.
-  std::vector<DirectoryLookup> SearchList;
+  std::vector<DirectoryLookupInfo> SearchList;
   SearchList.reserve(IncludePath.size());
 
   // Quoted arguments go first.
   for (auto &Include : IncludePath)
     if (Include.Group == Quoted)
-      SearchList.push_back(Include.Lookup);
+      SearchList.push_back(Include);
 
   // Deduplicate and remember index.
   RemoveDuplicates(SearchList, 0, Verbose);
   unsigned NumQuoted = SearchList.size();
 
   for (auto &Include : IncludePath)
     if (Include.Group == Angled || Include.Group == IndexHeaderMap)
-      SearchList.push_back(Include.Lookup);
+      SearchList.push_back(Include);
 
   RemoveDuplicates(SearchList, NumQuoted, Verbose);
   unsigned NumAngled = SearchList.size();
 
   for (auto &Include : IncludePath)
     if (Include.Group == System || Include.Group == ExternCSystem ||
         (!Lang.ObjC && !Lang.CPlusPlus && Include.Group == CSystem) ||
         (/*FIXME !Lang.ObjC && */ Lang.CPlusPlus &&
          Include.Group == CXXSystem) ||
         (Lang.ObjC && !Lang.CPlusPlus && Include.Group == ObjCSystem) ||
         (Lang.ObjC && Lang.CPlusPlus && Include.Group == ObjCXXSystem))
-      SearchList.push_back(Include.Lookup);
+      SearchList.push_back(Include);
 
   for (auto &Include : IncludePath)
     if (Include.Group == After)
-      SearchList.push_back(Include.Lookup);
+      SearchList.push_back(Include);
 
   // Remove duplicates across both the Angled and System directories.  GCC does
   // this and failing to remove duplicates across these two groups breaks
   // #include_next.
   unsigned NonSystemRemoved = RemoveDuplicates(SearchList, NumQuoted, Verbose);
   NumAngled -= NonSystemRemoved;
 
   bool DontSearchCurDir = false;  // TODO: set to true if -I- is set?
-  Headers.SetSearchPaths(SearchList, NumQuoted, NumAngled, DontSearchCurDir);
+  Headers.SetSearchPaths(extractLookups(SearchList), NumQuoted, NumAngled,
+                         DontSearchCurDir, mapToUserEntries(SearchList));
 
   Headers.SetSystemHeaderPrefixes(SystemHeaderPrefixes);
 
   // If verbose, print the list of directories that will be searched.
   if (Verbose) {
     llvm::errs() << "#include \"...\" search starts here:\n";
     for (unsigned i = 0, e = SearchList.size(); i != e; ++i) {
       if (i == NumQuoted)
         llvm::errs() << "#include <...> search starts here:\n";
-      StringRef Name = SearchList[i].getName();
+      StringRef Name = SearchList[i].Lookup.getName();
       const char *Suffix;
-      if (SearchList[i].isNormalDir())
+      if (SearchList[i].Lookup.isNormalDir())
         Suffix = "";
-      else if (SearchList[i].isFramework())
+      else if (SearchList[i].Lookup.isFramework())
         Suffix = " (framework directory)";
       else {
-        assert(SearchList[i].isHeaderMap() && "Unknown DirectoryLookup");
+        assert(SearchList[i].Lookup.isHeaderMap() && "Unknown DirectoryLookup");
         Suffix = " (headermap)";
       }
       llvm::errs() << " " << Name << Suffix << "\n";
     }
     llvm::errs() << "End of search list.\n";
   }
 }
 
 void clang::ApplyHeaderSearchOptions(HeaderSearch &HS,
                                      const HeaderSearchOptions &HSOpts,
                                      const LangOptions &Lang,
                                      const llvm::Triple &Triple) {
   InitHeaderSearch Init(HS, HSOpts.Verbose, HSOpts.Sysroot);
 
   // Add the user defined entries.
   for (unsigned i = 0, e = HSOpts.UserEntries.size(); i != e; ++i) {
     const HeaderSearchOptions::Entry &E = HSOpts.UserEntries[i];
     if (E.IgnoreSysRoot) {
-      Init.AddUnmappedPath(E.Path, E.Group, E.IsFramework);
+      Init.AddUnmappedPath(E.Path, E.Group, E.IsFramework, i);
     } else {
-      Init.AddPath(E.Path, E.Group, E.IsFramework);
+      Init.AddPath(E.Path, E.Group, E.IsFramework, i);
     }
   }
 
   Init.AddDefaultIncludePaths(Lang, Triple, HSOpts);
 
   for (unsigned i = 0, e = HSOpts.SystemHeaderPrefixes.size(); i != e; ++i)
     Init.AddSystemHeaderPrefix(HSOpts.SystemHeaderPrefixes[i].Prefix,
                                HSOpts.SystemHeaderPrefixes[i].IsSystemHeader);

clang/lib/Lex/HeaderMap.cpp

for (unsigned i = 0; i != NumBuckets; ++i) {
     StringRef Key = getStringOrInvalid(B.Key);
     StringRef Prefix = getStringOrInvalid(B.Prefix);
     StringRef Suffix = getStringOrInvalid(B.Suffix);
     llvm::dbgs() << "  " << i << ". " << Key << " -> '" << Prefix << "' '"
                  << Suffix << "'\n";
   }
 }
 
-/// LookupFile - Check to see if the specified relative filename is located in
-/// this HeaderMap.  If so, open it and return its FileEntry.
-Optional<FileEntryRef> HeaderMap::LookupFile(StringRef Filename,
-                                             FileManager &FM) const {
-
-  SmallString<1024> Path;
-  StringRef Dest = HeaderMapImpl::lookupFilename(Filename, Path);
-  if (Dest.empty())
-    return None;
-
-  return FM.getOptionalFileRef(Dest);
-}
-
 StringRef HeaderMapImpl::lookupFilename(StringRef Filename,
                                         SmallVectorImpl<char> &DestPath) const {
   const HMapHeader &Hdr = getHeader();
   unsigned NumBuckets = getEndianAdjustedWord(Hdr.NumBuckets);
 
   // Don't probe infinitely.  This should be checked before constructing.
   assert(llvm::isPowerOf2_32(NumBuckets) && "Expected power of 2");
 

clang/lib/Lex/HeaderSearch.cpp

void HeaderSearch::PrintStats() {
   llvm::errs() << "  " << NumIncluded << " #include/#include_next/#import.\n"
                << "    " << NumMultiIncludeFileOptzn
                << " #includes skipped due to the multi-include optimization.\n";
 
   llvm::errs() << NumFrameworkLookups << " framework lookups.\n"
                << NumSubFrameworkLookups << " subframework lookups.\n";
 }
 
+std::vector<bool> HeaderSearch::computeUserEntryUsage() const {
+  std::vector<bool> UserEntryUsage(HSOpts->UserEntries.size());
+  for (unsigned I = 0, E = SearchDirsUsage.size(); I < E; ++I) {
+    // Check whether this DirectoryLookup has been successfully used.
+    if (SearchDirsUsage[I]) {
+      auto UserEntryIdxIt = SearchDirToHSEntry.find(I);
+      // Check whether this DirectoryLookup maps to a HeaderSearch::UserEntry.
+      if (UserEntryIdxIt != SearchDirToHSEntry.end())
+        UserEntryUsage[UserEntryIdxIt->second] = true;
+    }
+  }
+  return UserEntryUsage;
+}
+
 /// CreateHeaderMap - This method returns a HeaderMap for the specified
 /// FileEntry, uniquing them through the 'HeaderMaps' datastructure.
 const HeaderMap *HeaderSearch::CreateHeaderMap(const FileEntry *FE) {
   // We expect the number of headermaps to be small, and almost always empty.
   // If it ever grows, use of a linear search should be re-evaluated.
   if (!HeaderMaps.empty()) {
     for (unsigned i = 0, e = HeaderMaps.size(); i != e; ++i)
       // Pointer equality comparison of FileEntries works because they are
Module = lookupModule(ModuleName, SearchName, ImportLoc,
                           AllowExtraModuleMapSearch);
   return Module;
 }
 
 Module *HeaderSearch::lookupModule(StringRef ModuleName, StringRef SearchName,
                                    SourceLocation ImportLoc,
                                    bool AllowExtraModuleMapSearch) {
   Module *Module = nullptr;
+  unsigned Idx;
 
   // Look through the various header search paths to load any available module
   // maps, searching for a module map that describes this module.
-  for (unsigned Idx = 0, N = SearchDirs.size(); Idx != N; ++Idx) {
+  for (Idx = 0; Idx != SearchDirs.size(); ++Idx) {
     if (SearchDirs[Idx].isFramework()) {
       // Search for or infer a module map for a framework. Here we use
       // SearchName rather than ModuleName, to permit finding private modules
       // named FooPrivate in buggy frameworks named Foo.
       SmallString<128> FrameworkDirName;
       FrameworkDirName += SearchDirs[Idx].getFrameworkDir()->getName();
       llvm::sys::path::append(FrameworkDirName, SearchName + ".framework");
       if (auto FrameworkDir = FileMgr.getDirectory(FrameworkDirName)) {
if (AllowExtraModuleMapSearch)
       loadSubdirectoryModuleMaps(SearchDirs[Idx]);
 
     // Look again for the module.
     Module = ModMap.findModule(ModuleName);
     if (Module)
       break;
   }
 
+  if (Module)
+    noteLookupUsage(Idx, ImportLoc);
+
   return Module;
 }
 
 //===----------------------------------------------------------------------===//
 // File lookup within a DirectoryLookup scope
 //===----------------------------------------------------------------------===//
 
 /// getName - Return the directory or filename corresponding to this lookup
Optional<FileEntryRef> DirectoryLookup::LookupFile(
   };
 
   // Check if the headermap maps the filename to a framework include
   // ("Foo.h" -> "Foo/Foo.h"), in which case continue header lookup using the
   // framework include.
   if (llvm::sys::path::is_relative(Dest)) {
     MappedName.append(Dest.begin(), Dest.end());
     Filename = StringRef(MappedName.begin(), MappedName.size());
-    Optional<FileEntryRef> Result = HM->LookupFile(Filename, HS.getFileMgr());
-    if (Result) {
-      FixupSearchPath();
-      return *Result;
-    }
-  } else if (auto Res = HS.getFileMgr().getOptionalFileRef(Dest)) {
+    Dest = HM->lookupFilename(Filename, Path);
+
+  if (auto Res = HS.getFileMgr().getOptionalFileRef(Dest)) {
     FixupSearchPath();
     return *Res;
   }
 
+  // Header maps need to be marked as used whenever the filename matches.
+  // The case where the target file **exists** is handled by callee of this
+  // function as part of the regular logic that applies to include search paths.
+  // The case where the target file **does not exist** is handled here:
+  HS.noteLookupUsage(*HS.searchDirIdx(*this), IncludeLoc);
   return None;
 }
 
 /// Given a framework directory, find the top-most framework directory.
 ///
 /// \param FileMgr The file manager to use for directory lookups.
 /// \param DirName The name of the framework directory.
 /// \param SubmodulePath Will be populated with the submodule path from the
if (FoundFramework) {
         return None;
     }
   }
   if (File)
     return *File;
   return None;
 }
 
+void HeaderSearch::cacheLookupSuccess(LookupFileCacheInfo &CacheLookup,
+                                      unsigned HitIdx, SourceLocation Loc) {
+  CacheLookup.HitIdx = HitIdx;
+  noteLookupUsage(HitIdx, Loc);
+}
+
+void HeaderSearch::noteLookupUsage(unsigned HitIdx, SourceLocation Loc) {
+  SearchDirsUsage[HitIdx] = true;
+
+  auto UserEntryIdxIt = SearchDirToHSEntry.find(HitIdx);
+  if (UserEntryIdxIt != SearchDirToHSEntry.end())
+    Diags.Report(Loc, diag::remark_pp_search_path_usage)
+        << HSOpts->UserEntries[UserEntryIdxIt->second].Path;
+}
+
 void HeaderSearch::setTarget(const TargetInfo &Target) {
   ModMap.setTarget(Target);
 }
 
 //===----------------------------------------------------------------------===//
 // Header File Location.
 //===----------------------------------------------------------------------===//
 
for (; i != SearchDirs.size(); ++i) {
 
     bool FoundByHeaderMap = !IsMapped ? false : *IsMapped;
     if (!Includers.empty())
       diagnoseFrameworkInclude(
           Diags, IncludeLoc, Includers.front().second->getName(), Filename,
           &File->getFileEntry(), isAngled, FoundByHeaderMap);
 
     // Remember this location for the next lookup we do.
-    CacheLookup.HitIdx = i;
+    cacheLookupSuccess(CacheLookup, i, IncludeLoc);
     return File;
   }
 
   // If we are including a file with a quoted include "foo.h" from inside
   // a header in a framework that is currently being built, and we couldn't
   // resolve "foo.h" any other way, change the include to <Foo/foo.h>, where
   // "Foo" is the name of the framework in which the including header was found.
   if (!Includers.empty() && Includers.front().first && !isAngled &&
if (IncludingHFI.IndexHeaderMapHeader) {
       if (checkMSVCHeaderSearch(Diags, MSFE ? &MSFE->getFileEntry() : nullptr,
                                 File ? &File->getFileEntry() : nullptr,
                                 IncludeLoc)) {
         if (SuggestedModule)
           *SuggestedModule = MSSuggestedModule;
         return MSFE;
       }
 
-      LookupFileCacheInfo &CacheLookup = LookupFileCache[Filename];
-      CacheLookup.HitIdx = LookupFileCache[ScratchFilename].HitIdx;
+      cacheLookupSuccess(LookupFileCache[Filename],
+                         LookupFileCache[ScratchFilename].HitIdx, IncludeLoc);
       // FIXME: SuggestedModule.
       return File;
     }
   }
 
   if (checkMSVCHeaderSearch(Diags, MSFE ? &MSFE->getFileEntry() : nullptr,
                             nullptr, IncludeLoc)) {
     if (SuggestedModule)

 size_t HeaderSearch::getTotalMemory() const {
   return SearchDirs.capacity()
     + llvm::capacity_in_bytes(FileInfo)
     + llvm::capacity_in_bytes(HeaderMaps)
     + LookupFileCache.getAllocator().getTotalMemory()
     + FrameworkMap.getAllocator().getTotalMemory();
 }
 
+Optional<unsigned> HeaderSearch::searchDirIdx(const DirectoryLookup &DL) const {
+  for (unsigned I = 0; I < SearchDirs.size(); ++I)
+    if (&SearchDirs[I] == &DL)
+      return I;
+  return None;
+}
+
 StringRef HeaderSearch::getUniqueFrameworkName(StringRef Framework) {
   return FrameworkNames.insert(Framework).first->first();
 }
 
 bool HeaderSearch::hasModuleMap(StringRef FileName,
                                 const DirectoryEntry *Root,
                                 bool IsSystem) {
   if (!HSOpts->ImplicitModuleMaps)

clang/test/Preprocessor/Inputs/search-path-usage/FwA/FrameworkA.framework/Modules/module.modulemap

+framework module FrameworkA {
+  header "FrameworkA.h"
+}

clang/test/Preprocessor/Inputs/search-path-usage/FwB/FrameworkB.framework/Modules/module.modulemap

+framework module FrameworkB {
+  header "FrameworkB.h"
+}

clang/test/Preprocessor/Inputs/search-path-usage/a/a.h

+#include_next "a.h" // #a-include-next

clang/test/Preprocessor/Inputs/search-path-usage/b.hmap.json.template

+{
+  "mappings": {
+    "b.h": "DIR/b/b.h"
+  }
+}

clang/test/Preprocessor/Inputs/search-path-usage/modulemap_abs/module.modulemap.template

+module b {
+  header "DIR/b/b.h"
+}

clang/test/Preprocessor/search-path-usage.m

+// RUN: rm -rf %t && mkdir %t
+
+// Check that search paths used by `#include` and `#include_next` are reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage   \
+// RUN:   -I%S/Inputs/search-path-usage/a          \
+// RUN:   -I%S/Inputs/search-path-usage/a_next     \
+// RUN:   -I%S/Inputs/search-path-usage/b          \
+// RUN:   -I%S/Inputs/search-path-usage/c          \
+// RUN:   -I%S/Inputs/search-path-usage/d          \
+// RUN:   -DINCLUDE -verify
+#ifdef INCLUDE
+#include "a.h" // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/a'}} \
+// expected-remark-re@#a-include-next {{search path used: '{{.*}}/search-path-usage/a_next'}}
+#include "d.h" // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/d'}}
+#endif
+
+// Check that framework search paths are reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -F%S/Inputs/search-path-usage/FwA      \
+// RUN:   -F%S/Inputs/search-path-usage/FwB      \
+// RUN:   -DFRAMEWORK -verify
+#ifdef FRAMEWORK
+#include "FrameworkA/FrameworkA.h" // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/FwA'}}
+#endif
+
+// Check that system search paths are reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -isystem %S/Inputs/search-path-usage/b \
+// RUN:   -isystem %S/Inputs/search-path-usage/d \
+// RUN:   -DSYSTEM -verify
+#ifdef SYSTEM
+#include "b.h" // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/b'}}
+#endif
+
+// Check that sysroot-based search paths are reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -isysroot %S/Inputs/search-path-usage  \
+// RUN:   -iwithsysroot /b                       \
+// RUN:   -iwithsysroot /d                       \
+// RUN:   -DSYSROOT -verify
+#ifdef SYSROOT
+#include "d.h" // \
+// expected-remark {{search path used: '/d'}}
+#endif
+
+// Check that search paths used by `__has_include()` are reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -I%S/Inputs/search-path-usage/b        \
+// RUN:   -I%S/Inputs/search-path-usage/d        \
+// RUN:   -DHAS_INCLUDE -verify
+#ifdef HAS_INCLUDE
+#if __has_include("b.h") // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/b'}}
+#endif
+#if __has_include("x.h")
+#endif
+#endif
+
+// Check that search paths used by `#import` are reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -I%S/Inputs/search-path-usage/b        \
+// RUN:   -I%S/Inputs/search-path-usage/d        \
+// RUN:   -DIMPORT -verify
+#ifdef IMPORT
+#import "d.h" // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/d'}}
+#endif
+
+// Check that used header maps are reported when the target file exists.
+//
+// RUN: sed "s|DIR|%/S/Inputs/search-path-usage|g" \
+// RUN:             %S/Inputs/search-path-usage/b.hmap.json.template > %t/b.hmap.json
+// RUN: %hmaptool write %t/b.hmap.json %t/b.hmap
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -I %t/b.hmap                           \
+// RUN:   -I b                                   \
+// RUN:   -DHMAP -verify
+#ifdef HMAP
+#include "b.h" // \
+// expected-remark-re {{search path used: '{{.*}}/b.hmap'}}
+#endif
+
+// Check that unused header map are not reported.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -I%t/b.hmap                            \
+// RUN:   -I%S/Inputs/search-path-usage/d        \
+// RUN:   -DHMAP_NO_MATCH -verify
+#ifdef HMAP_NO_MATCH
+#include "d.h" // \
+// expected-remark-re {{search path used: '{{.*}}/search-path-usage/d'}}
+#endif
+
+// Check that used header map is reported even when the target file is missing.
+//
+// RUN: sed "s|DIR|%/S/Inputs/search-path-usage/missing-subdir|g" \
+// RUN:             %S/Inputs/search-path-usage/b.hmap.json.template > %t/b-missing.hmap.json
+// RUN: %hmaptool write %t/b-missing.hmap.json %t/b-missing.hmap
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -I %t/b-missing.hmap                   \
+// RUN:   -I b                                   \
+// RUN:   -DHMAP_MATCHED_BUT_MISSING -verify
+#ifdef HMAP_MATCHED_BUT_MISSING
+#include "b.h" // \
+// expected-remark-re {{search path used: '{{.*}}/b-missing.hmap'}} \
+// expected-error {{'b.h' file not found}}
+#endif
+
+// Check that used header map is reported even when the target file is missing
+// and the lookup is initiated by __has_include.
+//
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage \
+// RUN:   -I %t/b-missing.hmap                   \
+// RUN:   -I b                                   \
+// RUN:   -DHMAP_MATCHED_BUT_MISSING_IN_HAS_INCLUDE -verify
+#ifdef HMAP_MATCHED_BUT_MISSING_IN_HAS_INCLUDE
+#if __has_include("b.h") // \
+// expected-remark-re {{search path used: '{{.*}}/b-missing.hmap'}}
+#endif
+#endif
+
+// Check that search paths with module maps are reported.
+//
+// RUN: mkdir %t/modulemap_abs
+// RUN: sed "s|DIR|%/S/Inputs/search-path-usage|g"                            \
+// RUN:   %S/Inputs/search-path-usage/modulemap_abs/module.modulemap.template \
+// RUN:     > %t/modulemap_abs/module.modulemap
+// RUN: %clang_cc1 -Eonly %s -Rsearch-path-usage                           \
+// RUN:   -fmodules -fimplicit-module-maps -fmodules-cache-path=%t/modules \
+// RUN:   -I %t/modulemap_abs                                              \
+// RUN:   -I %S/Inputs/search-path-usage/a                                 \
+// RUN:   -DMODMAP_ABS -verify
+#ifdef MODMAP_ABS
+@import b; // \
+// expected-remark-re {{search path used: '{{.*}}/modulemap_abs'}}
+#endif