[APINotes] Upstream APINotesManager

//===--- APINotesManager.h - Manage API Notes Files -------------*- 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_APINOTES_APINOTESMANAGER_H

#define LLVM_CLANG_APINOTES_APINOTESMANAGER_H

#include "clang/Basic/Module.h"

#include "clang/Basic/SourceLocation.h"

#include "llvm/ADT/ArrayRef.h"

#include "llvm/ADT/DenseMap.h"

#include "llvm/ADT/PointerUnion.h"

#include "llvm/ADT/StringRef.h"

#include "llvm/Support/VersionTuple.h"

#include <memory>

#include <string>

namespace clang {

class DirectoryEntry;

class FileEntry;

class LangOptions;

class SourceManager;

namespace api_notes {

class APINotesReader;

/// The API notes manager helps find API notes associated with declarations.

///

/// API notes are externally-provided annotations for declarations that can

/// introduce new attributes (covering availability, nullability of

/// parameters/results, and so on) for specific declarations without directly

/// modifying the headers that contain those declarations.

///

/// The API notes manager is responsible for finding and loading the

/// external API notes files that correspond to a given header. Its primary

/// operation is \c findAPINotes(), which finds the API notes reader that

/// provides information about the declarations at that location.

class APINotesManager {

  using ReaderEntry = llvm::PointerUnion<DirectoryEntryRef, APINotesReader *>;

  SourceManager &SM;

  /// Whether to implicitly search for API notes files based on the

  /// source file from which an entity was declared.

  bool ImplicitAPINotes;

  /// The Swift version to use when interpreting versioned API notes.

  llvm::VersionTuple SwiftVersion;

  enum ReaderKind : unsigned { Public = 0, Private = 1 };

  /// API notes readers for the current module.

  ///

  /// There can be up to two of these, one for public headers and one

  /// for private headers.

  ///

  /// Not using std::unique_ptr to store these, since the reader pointers are

  /// also stored in llvm::PointerUnion below.

  APINotesReader *CurrentModuleReaders[2] = {nullptr, nullptr};

  /// A mapping from header file directories to the API notes reader for

  /// that directory, or a redirection to another directory entry that may

  /// have more information, or NULL to indicate that there is no API notes

  /// reader for this directory.

  llvm::DenseMap<const DirectoryEntry *, ReaderEntry> Readers;

  /// Load the API notes associated with the given file, whether it is

  /// the binary or source form of API notes.

  ///

  /// \returns the API notes reader for this file, or null if there is

  /// a failure.

  std::unique_ptr<APINotesReader> loadAPINotes(FileEntryRef APINotesFile);

  /// Load the API notes associated with the given buffer, whether it is

  /// the binary or source form of API notes.

  ///

  /// \returns the API notes reader for this file, or null if there is

  /// a failure.

  std::unique_ptr<APINotesReader> loadAPINotes(StringRef Buffer);

  /// Load the given API notes file for the given header directory.

  ///

  /// \param HeaderDir The directory at which we

  ///

  /// \returns true if an error occurred.

  bool loadAPINotes(const DirectoryEntry *HeaderDir, FileEntryRef APINotesFile);

  /// Look for API notes in the given directory.

  ///

  /// This might find either a binary or source API notes.

  OptionalFileEntryRef findAPINotesFile(DirectoryEntryRef Directory,

                                        StringRef FileName,

                                        bool WantPublic = true);

  /// Attempt to load API notes for the given framework. A framework will have

  /// the API notes file under either {FrameworkPath}/APINotes,

  /// {FrameworkPath}/Headers or {FrameworkPath}/PrivateHeaders, while a

  /// library will have the API notes simply in its directory.

  ///

  /// \param FrameworkPath The path to the framework.

  /// \param Public Whether to load the public API notes. Otherwise, attempt

  /// to load the private API notes.

  ///

  /// \returns the header directory entry (e.g., for Headers or PrivateHeaders)

  /// for which the API notes were successfully loaded, or NULL if API notes

  /// could not be loaded for any reason.

  OptionalDirectoryEntryRef loadFrameworkAPINotes(llvm::StringRef FrameworkPath,

                                                  llvm::StringRef FrameworkName,

                                                  bool Public);

public:

  APINotesManager(SourceManager &SM, const LangOptions &LangOpts);

  ~APINotesManager();

  /// Set the Swift version to use when filtering API notes.

  void setSwiftVersion(llvm::VersionTuple Version) {

    this->SwiftVersion = Version;

  }

  /// Load the API notes for the current module.

  ///

  /// \param M The current module.

  /// \param LookInModule Whether to look inside the module itself.

  /// \param SearchPaths The paths in which we should search for API notes

  /// for the current module.

  ///

  /// \returns true if API notes were successfully loaded, \c false otherwise.

  bool loadCurrentModuleAPINotes(Module *M, bool LookInModule,

                                 ArrayRef<std::string> SearchPaths);

  /// Get FileEntry for the APINotes of the module that is currently being

  /// compiled.

  ///

  /// \param M The current module.

  /// \param LookInModule Whether to look inside the directory of the current

  /// module.

  /// \param SearchPaths The paths in which we should search for API

  /// notes for the current module.

  ///

  /// \returns a vector of FileEntry where APINotes files are.

  llvm::SmallVector<FileEntryRef, 2>

  getCurrentModuleAPINotes(Module *M, bool LookInModule,

                           ArrayRef<std::string> SearchPaths);

  /// Load Compiled API notes for current module.

  ///

  /// \param Buffers Array of compiled API notes.

  ///

  /// \returns true if API notes were successfully loaded, \c false otherwise.

  bool loadCurrentModuleAPINotesFromBuffer(ArrayRef<StringRef> Buffers);

  /// Retrieve the set of API notes readers for the current module.

  ArrayRef<APINotesReader *> getCurrentModuleReaders() const {

    bool HasPublic = CurrentModuleReaders[ReaderKind::Public];

    bool HasPrivate = CurrentModuleReaders[ReaderKind::Private];

    assert(!HasPrivate || HasPublic && "private module requires public module");

    if (!HasPrivate && !HasPublic)

      return {};

    return ArrayRef(CurrentModuleReaders).slice(0, HasPrivate ? 2 : 1);

  }

  /// Find the API notes readers that correspond to the given source location.

  llvm::SmallVector<APINotesReader *, 2> findAPINotes(SourceLocation Loc);

};

} // end namespace api_notes

} // end namespace clang

#endif

  return !(LHS == RHS);

}

/// The file extension used for the source representation of API notes.

static const constexpr char SOURCE_APINOTES_EXTENSION[] = "apinotes";

/// Opaque context ID used to refer to an Objective-C class or protocol or a C++

/// namespace.

class ContextID {

def warn_arcmt_nsalloc_realloc : Warning<"[rewriter] call returns pointer to GC managed memory; it will become unmanaged in ARC">;

def err_arcmt_nsinvocation_ownership : Error<"NSInvocation's %0 is not safe to be used with an object with ownership other than __unsafe_unretained">;

// API notes

def err_apinotes_message : Error<"%0">;

def warn_apinotes_message : Warning<"%0">, InGroup<DiagGroup<"apinotes">>;

def note_apinotes_message : Note<"%0">;

class NonportablePrivateAPINotesPath  : Warning<

  "private API notes file for module '%0' should be named "

  "'%0_private.apinotes', not '%1'">;

def warn_apinotes_private_case : NonportablePrivateAPINotesPath,

  InGroup<DiagGroup<"nonportable-private-apinotes-path">>;

def warn_apinotes_private_case_system : NonportablePrivateAPINotesPath,

  DefaultIgnore, InGroup<DiagGroup<"nonportable-private-system-apinotes-path">>;

// C++ for OpenCL.

def err_openclcxx_not_supported : Error<

  "'%0' is not supported in C++ for OpenCL">;

LANGOPT(RetainCommentsFromSystemHeaders, 1, 0, "retain documentation comments from system headers in the AST")

LANGOPT(APINotes, 1, 0, "use external API notes")

LANGOPT(SanitizeAddressFieldPadding, 2, 0, "controls how aggressive is ASan "

                                           "field padding (0: none, 1:least "

                                           "aggressive, 2: more aggressive)")

  /// eventually be exposed, for use in "private" modules.

  std::string ExportAsModule;

  /// For the debug info, the path to this module's .apinotes file, if any.

  std::string APINotesFile;

  /// Does this Module is a named module of a standard named module?

  bool isNamedModule() const {

    switch (Kind) {