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 | |
28 | using namespace clang; |
29 | using namespace api_notes; |
30 | |
31 | #define DEBUG_TYPE "API Notes" |
32 | STATISTIC(NumHeaderAPINotes, "non-framework API notes files loaded"); |
33 | STATISTIC(NumPublicFrameworkAPINotes, "framework public API notes loaded"); |
34 | STATISTIC(NumPrivateFrameworkAPINotes, "framework private API notes loaded"); |
35 | STATISTIC(NumFrameworksSearched, "frameworks searched"); |
36 | STATISTIC(NumDirectoriesSearched, "header directories searched"); |
37 | STATISTIC(NumDirectoryCacheHits, "directory cache hits"); |
38 | |
39 | namespace { |
40 | /// Prints two successive strings, which much be kept alive as long as the |
41 | /// PrettyStackTrace entry. |
42 | class PrettyStackTraceDoubleString : public llvm::PrettyStackTraceEntry { |
43 | StringRef First, Second; |
44 | |
45 | public: |
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 | |
52 | APINotesManager::APINotesManager(SourceManager &SM, const LangOptions &LangOpts) |
53 | : SM(SM), ImplicitAPINotes(LangOpts.APINotes) {} |
54 | |
55 | APINotesManager::~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 | |
66 | std::unique_ptr<APINotesReader> |
67 | APINotesManager::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 | |
105 | std::unique_ptr<APINotesReader> |
106 | APINotesManager::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 | |
126 | bool 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 | |
138 | OptionalFileEntryRef |
139 | APINotesManager::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 | |
153 | OptionalDirectoryEntryRef 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 | |
193 | static 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 |
213 | static bool hasPrivateSubmodules(const Module *M) { |
214 | return llvm::any_of(Range: M->submodules(), P: [](const Module *Submodule) { |
215 | return Submodule->ModuleMapIsPrivate; |
216 | }); |
217 | } |
218 | |
219 | llvm::SmallVector<FileEntryRef, 2> |
220 | APINotesManager::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 | |
302 | bool 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 | |
318 | bool 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 | |
330 | llvm::SmallVector<APINotesReader *, 2> |
331 | APINotesManager::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 |
Definitions
- NumHeaderAPINotes
- NumPublicFrameworkAPINotes
- NumPrivateFrameworkAPINotes
- NumFrameworksSearched
- NumDirectoriesSearched
- NumDirectoryCacheHits
- PrettyStackTraceDoubleString
- PrettyStackTraceDoubleString
- APINotesManager
- ~APINotesManager
- loadAPINotes
- loadAPINotes
- loadAPINotes
- findAPINotesFile
- loadFrameworkAPINotes
- checkPrivateAPINotesName
- hasPrivateSubmodules
- getCurrentModuleAPINotes
- loadCurrentModuleAPINotes
- loadCurrentModuleAPINotesFromBuffer
Improve your Profiling and Debugging skills
Find out more