1//===--- APINotesManager.cpp - Manage API Notes Files ---------------------===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#include "clang/APINotes/APINotesManager.h"
10#include "clang/APINotes/APINotesReader.h"
11#include "clang/APINotes/APINotesYAMLCompiler.h"
12#include "clang/Basic/Diagnostic.h"
13#include "clang/Basic/FileManager.h"
14#include "clang/Basic/LangOptions.h"
15#include "clang/Basic/Module.h"
16#include "clang/Basic/SourceManager.h"
17#include "clang/Basic/SourceMgrAdapter.h"
18#include "clang/Basic/Version.h"
19#include "llvm/ADT/APInt.h"
20#include "llvm/ADT/Hashing.h"
21#include "llvm/ADT/SetVector.h"
22#include "llvm/ADT/SmallPtrSet.h"
23#include "llvm/ADT/SmallVector.h"
24#include "llvm/ADT/Statistic.h"
25#include "llvm/Support/MemoryBuffer.h"
26#include "llvm/Support/Path.h"
27#include "llvm/Support/PrettyStackTrace.h"
28
29using namespace clang;
30using namespace api_notes;
31
32#define DEBUG_TYPE "API Notes"
33STATISTIC(NumHeaderAPINotes, "non-framework API notes files loaded");
34STATISTIC(NumPublicFrameworkAPINotes, "framework public API notes loaded");
35STATISTIC(NumPrivateFrameworkAPINotes, "framework private API notes loaded");
36STATISTIC(NumFrameworksSearched, "frameworks searched");
37STATISTIC(NumDirectoriesSearched, "header directories searched");
38STATISTIC(NumDirectoryCacheHits, "directory cache hits");
39
40namespace {
41/// Prints two successive strings, which much be kept alive as long as the
42/// PrettyStackTrace entry.
43class PrettyStackTraceDoubleString : public llvm::PrettyStackTraceEntry {
44 StringRef First, Second;
45
46public:
47 PrettyStackTraceDoubleString(StringRef First, StringRef Second)
48 : First(First), Second(Second) {}
49 void print(raw_ostream &OS) const override { OS << First << Second; }
50};
51} // namespace
52
53APINotesManager::APINotesManager(SourceManager &SM, const LangOptions &LangOpts)
54 : SM(SM), ImplicitAPINotes(LangOpts.APINotes) {}
55
56APINotesManager::~APINotesManager() {
57 // Free the API notes readers.
58 for (const auto &Entry : Readers) {
59 if (auto Reader = Entry.second.dyn_cast<APINotesReader *>())
60 delete Reader;
61 }
62
63 delete CurrentModuleReaders[ReaderKind::Public];
64 delete CurrentModuleReaders[ReaderKind::Private];
65}
66
67std::unique_ptr<APINotesReader>
68APINotesManager::loadAPINotes(FileEntryRef APINotesFile) {
69 PrettyStackTraceDoubleString Trace("Loading API notes from ",
70 APINotesFile.getName());
71
72 // Open the source file.
73 auto SourceFileID = SM.getOrCreateFileID(SourceFile: APINotesFile, FileCharacter: SrcMgr::C_User);
74 auto SourceBuffer = SM.getBufferOrNone(FID: SourceFileID, Loc: SourceLocation());
75 if (!SourceBuffer)
76 return nullptr;
77
78 // Compile the API notes source into a buffer.
79 // FIXME: Either propagate OSType through or, better yet, improve the binary
80 // APINotes format to maintain complete availability information.
81 // FIXME: We don't even really need to go through the binary format at all;
82 // we're just going to immediately deserialize it again.
83 llvm::SmallVector<char, 1024> APINotesBuffer;
84 std::unique_ptr<llvm::MemoryBuffer> CompiledBuffer;
85 {
86 SourceMgrAdapter SMAdapter(
87 SM, SM.getDiagnostics(), diag::err_apinotes_message,
88 diag::warn_apinotes_message, diag::note_apinotes_message, APINotesFile);
89 llvm::raw_svector_ostream OS(APINotesBuffer);
90 if (api_notes::compileAPINotes(
91 YAMLInput: SourceBuffer->getBuffer(), SourceFile: SM.getFileEntryForID(FID: SourceFileID), OS,
92 DiagHandler: SMAdapter.getDiagHandler(), DiagHandlerCtxt: SMAdapter.getDiagContext()))
93 return nullptr;
94
95 // Make a copy of the compiled form into the buffer.
96 CompiledBuffer = llvm::MemoryBuffer::getMemBufferCopy(
97 InputData: StringRef(APINotesBuffer.data(), APINotesBuffer.size()));
98 }
99
100 // Load the binary form we just compiled.
101 auto Reader = APINotesReader::Create(InputBuffer: std::move(CompiledBuffer), SwiftVersion);
102 assert(Reader && "Could not load the API notes we just generated?");
103 return Reader;
104}
105
106std::unique_ptr<APINotesReader>
107APINotesManager::loadAPINotes(StringRef Buffer) {
108 llvm::SmallVector<char, 1024> APINotesBuffer;
109 std::unique_ptr<llvm::MemoryBuffer> CompiledBuffer;
110 SourceMgrAdapter SMAdapter(
111 SM, SM.getDiagnostics(), diag::err_apinotes_message,
112 diag::warn_apinotes_message, diag::note_apinotes_message, std::nullopt);
113 llvm::raw_svector_ostream OS(APINotesBuffer);
114
115 if (api_notes::compileAPINotes(YAMLInput: Buffer, SourceFile: nullptr, OS,
116 DiagHandler: SMAdapter.getDiagHandler(),
117 DiagHandlerCtxt: SMAdapter.getDiagContext()))
118 return nullptr;
119
120 CompiledBuffer = llvm::MemoryBuffer::getMemBufferCopy(
121 InputData: StringRef(APINotesBuffer.data(), APINotesBuffer.size()));
122 auto Reader = APINotesReader::Create(InputBuffer: std::move(CompiledBuffer), SwiftVersion);
123 assert(Reader && "Could not load the API notes we just generated?");
124 return Reader;
125}
126
127bool APINotesManager::loadAPINotes(const DirectoryEntry *HeaderDir,
128 FileEntryRef APINotesFile) {
129 assert(!Readers.contains(HeaderDir));
130 if (auto Reader = loadAPINotes(APINotesFile)) {
131 Readers[HeaderDir] = Reader.release();
132 return false;
133 }
134
135 Readers[HeaderDir] = nullptr;
136 return true;
137}
138
139OptionalFileEntryRef
140APINotesManager::findAPINotesFile(DirectoryEntryRef Directory,
141 StringRef Basename, bool WantPublic) {
142 FileManager &FM = SM.getFileManager();
143
144 llvm::SmallString<128> Path(Directory.getName());
145
146 StringRef Suffix = WantPublic ? "" : "_private";
147
148 // Look for the source API notes file.
149 llvm::sys::path::append(path&: Path, a: llvm::Twine(Basename) + Suffix + "." +
150 SOURCE_APINOTES_EXTENSION);
151 return FM.getOptionalFileRef(Filename: Path, /*Open*/ OpenFile: true);
152}
153
154OptionalDirectoryEntryRef APINotesManager::loadFrameworkAPINotes(
155 llvm::StringRef FrameworkPath, llvm::StringRef FrameworkName, bool Public) {
156 FileManager &FM = SM.getFileManager();
157
158 llvm::SmallString<128> Path(FrameworkPath);
159 unsigned FrameworkNameLength = Path.size();
160
161 StringRef Suffix = Public ? "" : "_private";
162
163 // Form the path to the APINotes file.
164 llvm::sys::path::append(path&: Path, a: "APINotes");
165 llvm::sys::path::append(path&: Path, a: (llvm::Twine(FrameworkName) + Suffix + "." +
166 SOURCE_APINOTES_EXTENSION));
167
168 // Try to open the APINotes file.
169 auto APINotesFile = FM.getOptionalFileRef(Filename: Path);
170 if (!APINotesFile)
171 return std::nullopt;
172
173 // Form the path to the corresponding header directory.
174 Path.resize(N: FrameworkNameLength);
175 llvm::sys::path::append(path&: Path, a: Public ? "Headers" : "PrivateHeaders");
176
177 // Try to access the header directory.
178 auto HeaderDir = FM.getOptionalDirectoryRef(DirName: Path);
179 if (!HeaderDir)
180 return std::nullopt;
181
182 // Try to load the API notes.
183 if (loadAPINotes(HeaderDir: *HeaderDir, APINotesFile: *APINotesFile))
184 return std::nullopt;
185
186 // Success: return the header directory.
187 if (Public)
188 ++NumPublicFrameworkAPINotes;
189 else
190 ++NumPrivateFrameworkAPINotes;
191 return *HeaderDir;
192}
193
194static void checkPrivateAPINotesName(DiagnosticsEngine &Diags,
195 const FileEntry *File, const Module *M) {
196 if (File->tryGetRealPathName().empty())
197 return;
198
199 StringRef RealFileName =
200 llvm::sys::path::filename(path: File->tryGetRealPathName());
201 StringRef RealStem = llvm::sys::path::stem(path: RealFileName);
202 if (RealStem.ends_with(Suffix: "_private"))
203 return;
204
205 unsigned DiagID = diag::warn_apinotes_private_case;
206 if (M->IsSystem)
207 DiagID = diag::warn_apinotes_private_case_system;
208
209 Diags.Report(Loc: SourceLocation(), DiagID) << M->Name << RealFileName;
210}
211
212/// \returns true if any of \p module's immediate submodules are defined in a
213/// private module map
214static bool hasPrivateSubmodules(const Module *M) {
215 return llvm::any_of(Range: M->submodules(), P: [](const Module *Submodule) {
216 return Submodule->ModuleMapIsPrivate;
217 });
218}
219
220llvm::SmallVector<FileEntryRef, 2>
221APINotesManager::getCurrentModuleAPINotes(Module *M, bool LookInModule,
222 ArrayRef<std::string> SearchPaths) {
223 FileManager &FM = SM.getFileManager();
224 auto ModuleName = M->getTopLevelModuleName();
225 auto ExportedModuleName = M->getTopLevelModule()->ExportAsModule;
226 llvm::SmallVector<FileEntryRef, 2> APINotes;
227
228 // First, look relative to the module itself.
229 if (LookInModule && M->Directory) {
230 // Local function to try loading an API notes file in the given directory.
231 auto tryAPINotes = [&](DirectoryEntryRef Dir, bool WantPublic) {
232 if (auto File = findAPINotesFile(Directory: Dir, Basename: ModuleName, WantPublic)) {
233 if (!WantPublic)
234 checkPrivateAPINotesName(Diags&: SM.getDiagnostics(), File: *File, M);
235
236 APINotes.push_back(Elt: *File);
237 }
238 // If module FooCore is re-exported through module Foo, try Foo.apinotes.
239 if (!ExportedModuleName.empty())
240 if (auto File = findAPINotesFile(Directory: Dir, Basename: ExportedModuleName, WantPublic))
241 APINotes.push_back(Elt: *File);
242 };
243
244 if (M->IsFramework) {
245 // For frameworks, we search in the "Headers" or "PrivateHeaders"
246 // subdirectory.
247 //
248 // Public modules:
249 // - Headers/Foo.apinotes
250 // - PrivateHeaders/Foo_private.apinotes (if there are private submodules)
251 // Private modules:
252 // - PrivateHeaders/Bar.apinotes (except that 'Bar' probably already has
253 // the word "Private" in it in practice)
254 llvm::SmallString<128> Path(M->Directory->getName());
255
256 if (!M->ModuleMapIsPrivate) {
257 unsigned PathLen = Path.size();
258
259 llvm::sys::path::append(path&: Path, a: "Headers");
260 if (auto APINotesDir = FM.getOptionalDirectoryRef(DirName: Path))
261 tryAPINotes(*APINotesDir, /*wantPublic=*/true);
262
263 Path.resize(N: PathLen);
264 }
265
266 if (M->ModuleMapIsPrivate || hasPrivateSubmodules(M)) {
267 llvm::sys::path::append(path&: Path, a: "PrivateHeaders");
268 if (auto PrivateAPINotesDir = FM.getOptionalDirectoryRef(DirName: Path))
269 tryAPINotes(*PrivateAPINotesDir,
270 /*wantPublic=*/M->ModuleMapIsPrivate);
271 }
272 } else {
273 // Public modules:
274 // - Foo.apinotes
275 // - Foo_private.apinotes (if there are private submodules)
276 // Private modules:
277 // - Bar.apinotes (except that 'Bar' probably already has the word
278 // "Private" in it in practice)
279 tryAPINotes(*M->Directory, /*wantPublic=*/true);
280 if (!M->ModuleMapIsPrivate && hasPrivateSubmodules(M))
281 tryAPINotes(*M->Directory, /*wantPublic=*/false);
282 }
283
284 if (!APINotes.empty())
285 return APINotes;
286 }
287
288 // Second, look for API notes for this module in the module API
289 // notes search paths.
290 for (const auto &SearchPath : SearchPaths) {
291 if (auto SearchDir = FM.getOptionalDirectoryRef(DirName: SearchPath)) {
292 if (auto File = findAPINotesFile(Directory: *SearchDir, Basename: ModuleName)) {
293 APINotes.push_back(Elt: *File);
294 return APINotes;
295 }
296 }
297 }
298
299 // Didn't find any API notes.
300 return APINotes;
301}
302
303bool APINotesManager::loadCurrentModuleAPINotes(
304 Module *M, bool LookInModule, ArrayRef<std::string> SearchPaths) {
305 assert(!CurrentModuleReaders[ReaderKind::Public] &&
306 "Already loaded API notes for the current module?");
307
308 auto APINotes = getCurrentModuleAPINotes(M, LookInModule, SearchPaths);
309 unsigned NumReaders = 0;
310 for (auto File : APINotes) {
311 CurrentModuleReaders[NumReaders++] = loadAPINotes(APINotesFile: File).release();
312 if (!getCurrentModuleReaders().empty())
313 M->APINotesFile = File.getName().str();
314 }
315
316 return NumReaders > 0;
317}
318
319bool APINotesManager::loadCurrentModuleAPINotesFromBuffer(
320 ArrayRef<StringRef> Buffers) {
321 unsigned NumReader = 0;
322 for (auto Buf : Buffers) {
323 auto Reader = loadAPINotes(Buffer: Buf);
324 assert(Reader && "Could not load the API notes we just generated?");
325
326 CurrentModuleReaders[NumReader++] = Reader.release();
327 }
328 return NumReader;
329}
330
331llvm::SmallVector<APINotesReader *, 2>
332APINotesManager::findAPINotes(SourceLocation Loc) {
333 llvm::SmallVector<APINotesReader *, 2> Results;
334
335 // If there are readers for the current module, return them.
336 if (!getCurrentModuleReaders().empty()) {
337 Results.append(in_start: getCurrentModuleReaders().begin(),
338 in_end: getCurrentModuleReaders().end());
339 return Results;
340 }
341
342 // If we're not allowed to implicitly load API notes files, we're done.
343 if (!ImplicitAPINotes)
344 return Results;
345
346 // If we don't have source location information, we're done.
347 if (Loc.isInvalid())
348 return Results;
349
350 // API notes are associated with the expansion location. Retrieve the
351 // file for this location.
352 SourceLocation ExpansionLoc = SM.getExpansionLoc(Loc);
353 FileID ID = SM.getFileID(SpellingLoc: ExpansionLoc);
354 if (ID.isInvalid())
355 return Results;
356 OptionalFileEntryRef File = SM.getFileEntryRefForID(FID: ID);
357 if (!File)
358 return Results;
359
360 // Look for API notes in the directory corresponding to this file, or one of
361 // its its parent directories.
362 OptionalDirectoryEntryRef Dir = File->getDir();
363 FileManager &FileMgr = SM.getFileManager();
364 llvm::SetVector<const DirectoryEntry *,
365 SmallVector<const DirectoryEntry *, 4>,
366 llvm::SmallPtrSet<const DirectoryEntry *, 4>>
367 DirsVisited;
368 do {
369 // Look for an API notes reader for this header search directory.
370 auto Known = Readers.find(Val: *Dir);
371
372 // If we already know the answer, chase it.
373 if (Known != Readers.end()) {
374 ++NumDirectoryCacheHits;
375
376 // We've been redirected to another directory for answers. Follow it.
377 if (Known->second && Known->second.is<DirectoryEntryRef>()) {
378 DirsVisited.insert(X: *Dir);
379 Dir = Known->second.get<DirectoryEntryRef>();
380 continue;
381 }
382
383 // We have the answer.
384 if (auto Reader = Known->second.dyn_cast<APINotesReader *>())
385 Results.push_back(Elt: Reader);
386 break;
387 }
388
389 // Look for API notes corresponding to this directory.
390 StringRef Path = Dir->getName();
391 if (llvm::sys::path::extension(path: Path) == ".framework") {
392 // If this is a framework directory, check whether there are API notes
393 // in the APINotes subdirectory.
394 auto FrameworkName = llvm::sys::path::stem(path: Path);
395 ++NumFrameworksSearched;
396
397 // Look for API notes for both the public and private headers.
398 OptionalDirectoryEntryRef PublicDir =
399 loadFrameworkAPINotes(FrameworkPath: Path, FrameworkName, /*Public=*/true);
400 OptionalDirectoryEntryRef PrivateDir =
401 loadFrameworkAPINotes(FrameworkPath: Path, FrameworkName, /*Public=*/false);
402
403 if (PublicDir || PrivateDir) {
404 // We found API notes: don't ever look past the framework directory.
405 Readers[*Dir] = nullptr;
406
407 // Pretend we found the result in the public or private directory,
408 // as appropriate. All headers should be in one of those two places,
409 // but be defensive here.
410 if (!DirsVisited.empty()) {
411 if (PublicDir && DirsVisited.back() == *PublicDir) {
412 DirsVisited.pop_back();
413 Dir = *PublicDir;
414 } else if (PrivateDir && DirsVisited.back() == *PrivateDir) {
415 DirsVisited.pop_back();
416 Dir = *PrivateDir;
417 }
418 }
419
420 // Grab the result.
421 if (auto Reader = Readers[*Dir].dyn_cast<APINotesReader *>())
422 Results.push_back(Elt: Reader);
423 break;
424 }
425 } else {
426 // Look for an APINotes file in this directory.
427 llvm::SmallString<128> APINotesPath(Dir->getName());
428 llvm::sys::path::append(
429 path&: APINotesPath, a: (llvm::Twine("APINotes.") + SOURCE_APINOTES_EXTENSION));
430
431 // If there is an API notes file here, try to load it.
432 ++NumDirectoriesSearched;
433 if (auto APINotesFile = FileMgr.getOptionalFileRef(Filename: APINotesPath)) {
434 if (!loadAPINotes(HeaderDir: *Dir, APINotesFile: *APINotesFile)) {
435 ++NumHeaderAPINotes;
436 if (auto Reader = Readers[*Dir].dyn_cast<APINotesReader *>())
437 Results.push_back(Elt: Reader);
438 break;
439 }
440 }
441 }
442
443 // We didn't find anything. Look at the parent directory.
444 if (!DirsVisited.insert(X: *Dir)) {
445 Dir = std::nullopt;
446 break;
447 }
448
449 StringRef ParentPath = llvm::sys::path::parent_path(path: Path);
450 while (llvm::sys::path::stem(path: ParentPath) == "..")
451 ParentPath = llvm::sys::path::parent_path(path: ParentPath);
452
453 Dir = ParentPath.empty() ? std::nullopt
454 : FileMgr.getOptionalDirectoryRef(DirName: ParentPath);
455 } while (Dir);
456
457 // Path compression for all of the directories we visited, redirecting
458 // them to the directory we ended on. If no API notes were found, the
459 // resulting directory will be NULL, indicating no API notes.
460 for (const auto Visited : DirsVisited)
461 Readers[Visited] = Dir ? ReaderEntry(*Dir) : ReaderEntry();
462
463 return Results;
464}
465