//===--- APINotesManager.cpp - Manage API Notes Files ---------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
#include "clang/APINotes/APINotesManager.h"
#include "clang/APINotes/APINotesReader.h"
#include "clang/APINotes/APINotesYAMLCompiler.h"
#include "clang/Basic/Diagnostic.h"
#include "clang/Basic/FileManager.h"
#include "clang/Basic/LangOptions.h"
#include "clang/Basic/SourceManager.h"
#include "clang/Basic/SourceMgrAdapter.h"
#include "clang/Basic/Version.h"
#include "llvm/ADT/APInt.h"
#include "llvm/ADT/Hashing.h"
#include "llvm/ADT/SetVector.h"
#include "llvm/ADT/SmallPtrSet.h"
#include "llvm/ADT/SmallVector.h"
#include "llvm/ADT/Statistic.h"
#include "llvm/Support/MemoryBuffer.h"
#include "llvm/Support/Path.h"
#include "llvm/Support/PrettyStackTrace.h"
using namespace clang;
using namespace api_notes;
#define DEBUG_TYPE "API Notes"
STATISTIC(NumHeaderAPINotes, "non-framework API notes files loaded");
STATISTIC(NumPublicFrameworkAPINotes, "framework public API notes loaded");
STATISTIC(NumPrivateFrameworkAPINotes, "framework private API notes loaded");
STATISTIC(NumFrameworksSearched, "frameworks searched");
STATISTIC(NumDirectoriesSearched, "header directories searched");
STATISTIC(NumDirectoryCacheHits, "directory cache hits");
namespace {
/// Prints two successive strings, which much be kept alive as long as the
/// PrettyStackTrace entry.
class PrettyStackTraceDoubleString : public llvm::PrettyStackTraceEntry {
StringRef First, Second;
public:
PrettyStackTraceDoubleString(StringRef First, StringRef Second)
: First(First), Second(Second) {}
void print(raw_ostream &OS) const override { OS << First << Second; }
};
} // namespace
APINotesManager::APINotesManager(SourceManager &SM, const LangOptions &LangOpts)
: SM(SM), ImplicitAPINotes(LangOpts.APINotes) {}
APINotesManager::~APINotesManager() {
// Free the API notes readers.
for (const auto &Entry : Readers) {
if (auto Reader = Entry.second.dyn_cast<APINotesReader *>())
delete Reader;
}
delete CurrentModuleReaders[ReaderKind::Public];
delete CurrentModuleReaders[ReaderKind::Private];
}
std::unique_ptr<APINotesReader>
APINotesManager::loadAPINotes(FileEntryRef APINotesFile) {
PrettyStackTraceDoubleString Trace("Loading API notes from ",
APINotesFile.getName());
// Open the source file.
auto SourceFileID = SM.getOrCreateFileID(APINotesFile, SrcMgr::C_User);
auto SourceBuffer = SM.getBufferOrNone(SourceFileID, SourceLocation());
if (!SourceBuffer)
return nullptr;
// Compile the API notes source into a buffer.
// FIXME: Either propagate OSType through or, better yet, improve the binary
// APINotes format to maintain complete availability information.
// FIXME: We don't even really need to go through the binary format at all;
// we're just going to immediately deserialize it again.
llvm::SmallVector<char, 1024> APINotesBuffer;
std::unique_ptr<llvm::MemoryBuffer> CompiledBuffer;
{
SourceMgrAdapter SMAdapter(
SM, SM.getDiagnostics(), diag::err_apinotes_message,
diag::warn_apinotes_message, diag::note_apinotes_message, APINotesFile);
llvm::raw_svector_ostream OS(APINotesBuffer);
if (api_notes::compileAPINotes(
SourceBuffer->getBuffer(), SM.getFileEntryForID(SourceFileID), OS,
SMAdapter.getDiagHandler(), SMAdapter.getDiagContext()))
return nullptr;
// Make a copy of the compiled form into the buffer.
CompiledBuffer = llvm::MemoryBuffer::getMemBufferCopy(
StringRef(APINotesBuffer.data(), APINotesBuffer.size()));
}
// Load the binary form we just compiled.
auto Reader = APINotesReader::Create(std::move(CompiledBuffer), SwiftVersion);
assert(Reader && "Could not load the API notes we just generated?");
return Reader;
}
std::unique_ptr<APINotesReader>
APINotesManager::loadAPINotes(StringRef Buffer) {
llvm::SmallVector<char, 1024> APINotesBuffer;
std::unique_ptr<llvm::MemoryBuffer> CompiledBuffer;
SourceMgrAdapter SMAdapter(
SM, SM.getDiagnostics(), diag::err_apinotes_message,
diag::warn_apinotes_message, diag::note_apinotes_message, std::nullopt);
llvm::raw_svector_ostream OS(APINotesBuffer);
if (api_notes::compileAPINotes(Buffer, nullptr, OS,
SMAdapter.getDiagHandler(),
SMAdapter.getDiagContext()))
return nullptr;
CompiledBuffer = llvm::MemoryBuffer::getMemBufferCopy(
StringRef(APINotesBuffer.data(), APINotesBuffer.size()));
auto Reader = APINotesReader::Create(std::move(CompiledBuffer), SwiftVersion);
assert(Reader && "Could not load the API notes we just generated?");
return Reader;
}
bool APINotesManager::loadAPINotes(const DirectoryEntry *HeaderDir,
FileEntryRef APINotesFile) {
assert(!Readers.contains(HeaderDir));
if (auto Reader = loadAPINotes(APINotesFile)) {
Readers[HeaderDir] = Reader.release();
return false;
}
Readers[HeaderDir] = nullptr;
return true;
}
OptionalFileEntryRef
APINotesManager::findAPINotesFile(DirectoryEntryRef Directory,
StringRef Basename, bool WantPublic) {
FileManager &FM = SM.getFileManager();
llvm::SmallString<128> Path(Directory.getName());
StringRef Suffix = WantPublic ? "" : "_private";
// Look for the source API notes file.
llvm::sys::path::append(Path, llvm::Twine(Basename) + Suffix + "." +
SOURCE_APINOTES_EXTENSION);
return FM.getOptionalFileRef(Path, /*Open*/ true);
}
OptionalDirectoryEntryRef APINotesManager::loadFrameworkAPINotes(
llvm::StringRef FrameworkPath, llvm::StringRef FrameworkName, bool Public) {
FileManager &FM = SM.getFileManager();
llvm::SmallString<128> Path(FrameworkPath);
unsigned FrameworkNameLength = Path.size();
StringRef Suffix = Public ? "" : "_private";
// Form the path to the APINotes file.
llvm::sys::path::append(Path, "APINotes");
llvm::sys::path::append(Path, (llvm::Twine(FrameworkName) + Suffix + "." +
SOURCE_APINOTES_EXTENSION));
// Try to open the APINotes file.
auto APINotesFile = FM.getOptionalFileRef(Path);
if (!APINotesFile)
return std::nullopt;
// Form the path to the corresponding header directory.
Path.resize(FrameworkNameLength);
llvm::sys::path::append(Path, Public ? "Headers" : "PrivateHeaders");
// Try to access the header directory.
auto HeaderDir = FM.getOptionalDirectoryRef(Path);
if (!HeaderDir)
return std::nullopt;
// Try to load the API notes.
if (loadAPINotes(*HeaderDir, *APINotesFile))
return std::nullopt;
// Success: return the header directory.
if (Public)
++NumPublicFrameworkAPINotes;
else
++NumPrivateFrameworkAPINotes;
return *HeaderDir;
}
static void checkPrivateAPINotesName(DiagnosticsEngine &Diags,
const FileEntry *File, const Module *M) {
if (File->tryGetRealPathName().empty())
return;
StringRef RealFileName =
llvm::sys::path::filename(File->tryGetRealPathName());
StringRef RealStem = llvm::sys::path::stem(RealFileName);
if (RealStem.ends_with("_private"))
return;
unsigned DiagID = diag::warn_apinotes_private_case;
if (M->IsSystem)
DiagID = diag::warn_apinotes_private_case_system;
Diags.Report(SourceLocation(), DiagID) << M->Name << RealFileName;
}
/// \returns true if any of \p module's immediate submodules are defined in a
/// private module map
static bool hasPrivateSubmodules(const Module *M) {
return llvm::any_of(M->submodules(), [](const Module *Submodule) {
return Submodule->ModuleMapIsPrivate;
});
}
llvm::SmallVector<FileEntryRef, 2>
APINotesManager::getCurrentModuleAPINotes(Module *M, bool LookInModule,
ArrayRef<std::string> SearchPaths) {
FileManager &FM = SM.getFileManager();
auto ModuleName = M->getTopLevelModuleName();
llvm::SmallVector<FileEntryRef, 2> APINotes;
// First, look relative to the module itself.
if (LookInModule) {
// Local function to try loading an API notes file in the given directory.
auto tryAPINotes = [&](DirectoryEntryRef Dir, bool WantPublic) {
if (auto File = findAPINotesFile(Dir, ModuleName, WantPublic)) {
if (!WantPublic)
checkPrivateAPINotesName(SM.getDiagnostics(), *File, M);
APINotes.push_back(*File);
}
};
if (M->IsFramework) {
// For frameworks, we search in the "Headers" or "PrivateHeaders"
// subdirectory.
//
// Public modules:
// - Headers/Foo.apinotes
// - PrivateHeaders/Foo_private.apinotes (if there are private submodules)
// Private modules:
// - PrivateHeaders/Bar.apinotes (except that 'Bar' probably already has
// the word "Private" in it in practice)
llvm::SmallString<128> Path(M->Directory->getName());
if (!M->ModuleMapIsPrivate) {
unsigned PathLen = Path.size();
llvm::sys::path::append(Path, "Headers");
if (auto APINotesDir = FM.getOptionalDirectoryRef(Path))
tryAPINotes(*APINotesDir, /*wantPublic=*/true);
Path.resize(PathLen);
}
if (M->ModuleMapIsPrivate || hasPrivateSubmodules(M)) {
llvm::sys::path::append(Path, "PrivateHeaders");
if (auto PrivateAPINotesDir = FM.getOptionalDirectoryRef(Path))
tryAPINotes(*PrivateAPINotesDir,
/*wantPublic=*/M->ModuleMapIsPrivate);
}
} else {
// Public modules:
// - Foo.apinotes
// - Foo_private.apinotes (if there are private submodules)
// Private modules:
// - Bar.apinotes (except that 'Bar' probably already has the word
// "Private" in it in practice)
tryAPINotes(*M->Directory, /*wantPublic=*/true);
if (!M->ModuleMapIsPrivate && hasPrivateSubmodules(M))
tryAPINotes(*M->Directory, /*wantPublic=*/false);
}
if (!APINotes.empty())
return APINotes;
}
// Second, look for API notes for this module in the module API
// notes search paths.
for (const auto &SearchPath : SearchPaths) {
if (auto SearchDir = FM.getOptionalDirectoryRef(SearchPath)) {
if (auto File = findAPINotesFile(*SearchDir, ModuleName)) {
APINotes.push_back(*File);
return APINotes;
}
}
}
// Didn't find any API notes.
return APINotes;
}
bool APINotesManager::loadCurrentModuleAPINotes(
Module *M, bool LookInModule, ArrayRef<std::string> SearchPaths) {
assert(!CurrentModuleReaders[ReaderKind::Public] &&
"Already loaded API notes for the current module?");
auto APINotes = getCurrentModuleAPINotes(M, LookInModule, SearchPaths);
unsigned NumReaders = 0;
for (auto File : APINotes) {
CurrentModuleReaders[NumReaders++] = loadAPINotes(File).release();
if (!getCurrentModuleReaders().empty())
M->APINotesFile = File.getName().str();
}
return NumReaders > 0;
}
bool APINotesManager::loadCurrentModuleAPINotesFromBuffer(
ArrayRef<StringRef> Buffers) {
unsigned NumReader = 0;
for (auto Buf : Buffers) {
auto Reader = loadAPINotes(Buf);
assert(Reader && "Could not load the API notes we just generated?");
CurrentModuleReaders[NumReader++] = Reader.release();
}
return NumReader;
}
llvm::SmallVector<APINotesReader *, 2>
APINotesManager::findAPINotes(SourceLocation Loc) {
llvm::SmallVector<APINotesReader *, 2> Results;
// If there are readers for the current module, return them.
if (!getCurrentModuleReaders().empty()) {
Results.append(getCurrentModuleReaders().begin(),
getCurrentModuleReaders().end());
return Results;
}
// If we're not allowed to implicitly load API notes files, we're done.
if (!ImplicitAPINotes)
return Results;
// If we don't have source location information, we're done.
if (Loc.isInvalid())
return Results;
// API notes are associated with the expansion location. Retrieve the
// file for this location.
SourceLocation ExpansionLoc = SM.getExpansionLoc(Loc);
FileID ID = SM.getFileID(ExpansionLoc);
if (ID.isInvalid())
return Results;
OptionalFileEntryRef File = SM.getFileEntryRefForID(ID);
if (!File)
return Results;
// Look for API notes in the directory corresponding to this file, or one of
// its its parent directories.
OptionalDirectoryEntryRef Dir = File->getDir();
FileManager &FileMgr = SM.getFileManager();
llvm::SetVector<const DirectoryEntry *,
SmallVector<const DirectoryEntry *, 4>,
llvm::SmallPtrSet<const DirectoryEntry *, 4>>
DirsVisited;
do {
// Look for an API notes reader for this header search directory.
auto Known = Readers.find(*Dir);
// If we already know the answer, chase it.
if (Known != Readers.end()) {
++NumDirectoryCacheHits;
// We've been redirected to another directory for answers. Follow it.
if (Known->second && Known->second.is<DirectoryEntryRef>()) {
DirsVisited.insert(*Dir);
Dir = Known->second.get<DirectoryEntryRef>();
continue;
}
// We have the answer.
if (auto Reader = Known->second.dyn_cast<APINotesReader *>())
Results.push_back(Reader);
break;
}
// Look for API notes corresponding to this directory.
StringRef Path = Dir->getName();
if (llvm::sys::path::extension(Path) == ".framework") {
// If this is a framework directory, check whether there are API notes
// in the APINotes subdirectory.
auto FrameworkName = llvm::sys::path::stem(Path);
++NumFrameworksSearched;
// Look for API notes for both the public and private headers.
OptionalDirectoryEntryRef PublicDir =
loadFrameworkAPINotes(Path, FrameworkName, /*Public=*/true);
OptionalDirectoryEntryRef PrivateDir =
loadFrameworkAPINotes(Path, FrameworkName, /*Public=*/false);
if (PublicDir || PrivateDir) {
// We found API notes: don't ever look past the framework directory.
Readers[*Dir] = nullptr;
// Pretend we found the result in the public or private directory,
// as appropriate. All headers should be in one of those two places,
// but be defensive here.
if (!DirsVisited.empty()) {
if (PublicDir && DirsVisited.back() == *PublicDir) {
DirsVisited.pop_back();
Dir = *PublicDir;
} else if (PrivateDir && DirsVisited.back() == *PrivateDir) {
DirsVisited.pop_back();
Dir = *PrivateDir;
}
}
// Grab the result.
if (auto Reader = Readers[*Dir].dyn_cast<APINotesReader *>())
Results.push_back(Reader);
break;
}
} else {
// Look for an APINotes file in this directory.
llvm::SmallString<128> APINotesPath(Dir->getName());
llvm::sys::path::append(
APINotesPath, (llvm::Twine("APINotes.") + SOURCE_APINOTES_EXTENSION));
// If there is an API notes file here, try to load it.
++NumDirectoriesSearched;
if (auto APINotesFile = FileMgr.getOptionalFileRef(APINotesPath)) {
if (!loadAPINotes(*Dir, *APINotesFile)) {
++NumHeaderAPINotes;
if (auto Reader = Readers[*Dir].dyn_cast<APINotesReader *>())
Results.push_back(Reader);
break;
}
}
}
// We didn't find anything. Look at the parent directory.
if (!DirsVisited.insert(*Dir)) {
Dir = std::nullopt;
break;
}
StringRef ParentPath = llvm::sys::path::parent_path(Path);
while (llvm::sys::path::stem(ParentPath) == "..")
ParentPath = llvm::sys::path::parent_path(ParentPath);
Dir = ParentPath.empty() ? std::nullopt
: FileMgr.getOptionalDirectoryRef(ParentPath);
} while (Dir);
// Path compression for all of the directories we visited, redirecting
// them to the directory we ended on. If no API notes were found, the
// resulting directory will be NULL, indicating no API notes.
for (const auto Visited : DirsVisited)
Readers[Visited] = Dir ? ReaderEntry(*Dir) : ReaderEntry();
return Results;
}
