DylibVerifier.h

Go to the documentation of this file.

//===- InstallAPI/DylibVerifier.h -------------------------------*- C++ -*-===//
//
// 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
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_CLANG_INSTALLAPI_DYLIBVERIFIER_H
#define LLVM_CLANG_INSTALLAPI_DYLIBVERIFIER_H
 
#include "clang/Basic/Diagnostic.h"
#include "clang/Basic/SourceManager.h"
#include "clang/InstallAPI/MachO.h"
 
namespace clang {
namespace installapi {
struct FrontendAttrs;
 
/// A list of InstallAPI verification modes.
enum class VerificationMode {
  Invalid,
  ErrorsOnly,
  ErrorsAndWarnings,
  Pedantic,
};
 
using LibAttrs = llvm::StringMap<ArchitectureSet>;
using ReexportedInterfaces = llvm::SmallVector<llvm::MachO::InterfaceFile, 8>;
 
// Pointers to information about a zippered declaration used for
// querying and reporting violations against different
// declarations that all map to the same symbol.
struct ZipperedDeclSource {
  const FrontendAttrs *FA;
  clang::SourceManager *SrcMgr;
  Target T;
};
using ZipperedDeclSources = std::vector<ZipperedDeclSource>;
 
/// Service responsible to tracking state of verification across the
/// lifetime of InstallAPI.
/// As declarations are collected during AST traversal, they are
/// compared as symbols against what is available in the binary dylib.
class DylibVerifier : llvm::MachO::RecordVisitor {
private:
  struct SymbolContext;
  struct DWARFContext;
 
public:
  enum class Result { NoVerify, Ignore, Valid, Invalid };
  struct VerifierContext {
    // Current target being verified against the AST.
    llvm::MachO::Target Target;
 
    // Target specific API from binary.
    RecordsSlice *DylibSlice = nullptr;
 
    // Query state of verification after AST has been traversed.
    Result FrontendState = Result::Ignore;
 
    // First error for AST traversal, which is tied to the target triple.
    bool DiscoveredFirstError = false;
 
    // Determines what kind of banner to print a violation for.
    bool PrintArch = false;
 
    // Engine for reporting violations.
    DiagnosticsEngine *Diag = nullptr;
 
    // Handle diagnostics reporting for target level violations.
    void emitDiag(llvm::function_ref<void()> Report, RecordLoc *Loc = nullptr);
 
    VerifierContext() = default;
    VerifierContext(DiagnosticsEngine *Diag) : Diag(Diag) {}
  };
 
  DylibVerifier() = default;
 
  DylibVerifier(llvm::MachO::Records &&Dylib, ReexportedInterfaces &&Reexports,
                AliasMap Aliases, DiagnosticsEngine *Diag,
                VerificationMode Mode, bool Zippered, bool Demangle,
                StringRef DSYMPath)
      : Dylib(std::move(Dylib)), Reexports(std::move(Reexports)),
        Aliases(std::move(Aliases)), Mode(Mode), Zippered(Zippered),
        Demangle(Demangle), DSYMPath(DSYMPath),
        Exports(std::make_unique<SymbolSet>()), Ctx(VerifierContext{Diag}) {}
 
  Result verify(GlobalRecord *R, const FrontendAttrs *FA);
  Result verify(ObjCInterfaceRecord *R, const FrontendAttrs *FA);
  Result verify(ObjCIVarRecord *R, const FrontendAttrs *FA,
                const StringRef SuperClass);
 
  // Scan through dylib slices and report any remaining missing exports.
  Result verifyRemainingSymbols();
 
  /// Compare and report the attributes represented as
  /// load commands in the dylib to the attributes provided via options.
  bool verifyBinaryAttrs(const ArrayRef<Target> ProvidedTargets,
                         const BinaryAttrs &ProvidedBA,
                         const LibAttrs &ProvidedReexports,
                         const LibAttrs &ProvidedClients,
                         const LibAttrs &ProvidedRPaths, const FileType &FT);
 
  /// Initialize target for verification.
  void setTarget(const Target &T);
 
  /// Release ownership over exports.
  std::unique_ptr<SymbolSet> takeExports();
 
  /// Get result of verification.
  Result getState() const { return Ctx.FrontendState; }
 
  /// Set different source managers to the same diagnostics engine.
  void setSourceManager(IntrusiveRefCntPtr<SourceManager> SourceMgr);
 
private:
  /// Determine whether to compare declaration to symbol in binary.
  bool canVerify();
 
  /// Shared implementation for verifying exported symbols.
  Result verifyImpl(Record *R, SymbolContext &SymCtx);
 
  /// Check if declaration is marked as obsolete, they are
  // expected to result in a symbol mismatch.
  bool shouldIgnoreObsolete(const Record *R, SymbolContext &SymCtx,
                            const Record *DR);
 
  /// Check if declaration is exported from a reexported library. These
  /// symbols should be omitted from the text-api file.
  bool shouldIgnoreReexport(const Record *R, SymbolContext &SymCtx) const;
 
  // Ignore and omit unavailable symbols in zippered libraries.
  bool shouldIgnoreZipperedAvailability(const Record *R, SymbolContext &SymCtx);
 
  // Check if an internal declaration in zippered library has an
  // external declaration for a different platform. This results
  // in the symbol being in a "seperate" platform slice.
  bool shouldIgnoreInternalZipperedSymbol(const Record *R,
                                          const SymbolContext &SymCtx) const;
 
  /// Compare the visibility declarations to the linkage of symbol found in
  /// dylib.
  Result compareVisibility(const Record *R, SymbolContext &SymCtx,
                           const Record *DR);
 
  /// An ObjCInterfaceRecord can represent up to three symbols. When verifying,
  // account for this granularity.
  bool compareObjCInterfaceSymbols(const Record *R, SymbolContext &SymCtx,
                                   const ObjCInterfaceRecord *DR);
 
  /// Validate availability annotations against dylib.
  Result compareAvailability(const Record *R, SymbolContext &SymCtx,
                             const Record *DR);
 
  /// Compare and validate matching symbol flags.
  bool compareSymbolFlags(const Record *R, SymbolContext &SymCtx,
                          const Record *DR);
 
  /// Update result state on each call to `verify`.
  void updateState(Result State);
 
  /// Add verified exported symbol.
  void addSymbol(const Record *R, SymbolContext &SymCtx,
                 TargetList &&Targets = {});
 
  /// Find matching dylib slice for target triple that is being parsed.
  void assignSlice(const Target &T);
 
  /// Shared implementation for verifying exported symbols in dylib.
  void visitSymbolInDylib(const Record &R, SymbolContext &SymCtx);
 
  void visitGlobal(const GlobalRecord &R) override;
  void visitObjCInterface(const ObjCInterfaceRecord &R) override;
  void visitObjCCategory(const ObjCCategoryRecord &R) override;
  void visitObjCIVar(const ObjCIVarRecord &R, const StringRef Super);
 
  /// Gather annotations for symbol for error reporting.
  std::string getAnnotatedName(const Record *R, SymbolContext &SymCtx,
                               bool ValidSourceLoc = true);
 
  /// Extract source location for symbol implementations.
  /// As this is a relatively expensive operation, it is only used
  /// when there is a violation to report and there is not a known declaration
  /// in the interface.
  void accumulateSrcLocForDylibSymbols();
 
  // Symbols in dylib.
  llvm::MachO::Records Dylib;
 
  // Reexported interfaces apart of the library.
  ReexportedInterfaces Reexports;
 
  // Symbol aliases.
  AliasMap Aliases;
 
  // Controls what class of violations to report.
  VerificationMode Mode = VerificationMode::Invalid;
 
  // Library is zippered.
  bool Zippered = false;
 
  // Attempt to demangle when reporting violations.
  bool Demangle = false;
 
  // File path to DSYM file.
  StringRef DSYMPath;
 
  // Valid symbols in final text file.
  std::unique_ptr<SymbolSet> Exports = std::make_unique<SymbolSet>();
 
  // Unavailable or obsoleted declarations for a zippered library.
  // These are cross referenced against symbols in the dylib.
  llvm::StringMap<ZipperedDeclSources> DeferredZipperedSymbols;
 
  // Track current state of verification while traversing AST.
  VerifierContext Ctx;
 
  // Track DWARF provided source location for dylibs.
  DWARFContext *DWARFCtx = nullptr;
 
  // Source manager for each unique compiler instance.
  llvm::SmallVector<IntrusiveRefCntPtr<SourceManager>, 12> SourceManagers;
};
 
} // namespace installapi
} // namespace clang
#endif // LLVM_CLANG_INSTALLAPI_DYLIBVERIFIER_H