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

Provided by KDAB

Privacy Policy
Improve your Profiling and Debugging skills
Find out more

source code of clang/lib/APINotes/APINotesManager.cpp