clang-tools-extra/include-cleaner/include/clang-include-cleaner/Record.h

   1 //===--- Record.h - Record compiler events ------------------------- C++-*-===//
   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 // Where Analysis.h analyzes AST nodes and recorded preprocessor events, this
  10 // file defines ways to capture AST and preprocessor information from a parse.
  11 //
  12 // These are the simplest way to connect include-cleaner logic to the parser,
  13 // but other ways are possible (for example clangd records includes separately).
  14 //
  15 //===----------------------------------------------------------------------===//
  16
  17 #ifndef CLANG_INCLUDE_CLEANER_RECORD_H
  18 #define CLANG_INCLUDE_CLEANER_RECORD_H
  19
  20 #include "clang-include-cleaner/Types.h"
  21 #include "clang/Basic/SourceLocation.h"
  22 #include "llvm/ADT/DenseMap.h"
  23 #include "llvm/ADT/DenseSet.h"
  24 #include "llvm/ADT/SmallVector.h"
  25 #include "llvm/ADT/StringRef.h"
  26 #include "llvm/Support/Allocator.h"
  27 #include "llvm/Support/FileSystem/UniqueID.h"
  28 #include <memory>
  29 #include <vector>
  30
  31 namespace clang {
  32 class ASTConsumer;
  33 class ASTContext;
  34 class CompilerInstance;
  35 class Decl;
  36 class FileEntry;
  37 class Preprocessor;
  38 class PPCallbacks;
  39 class FileManager;
  40
  41 namespace include_cleaner {
  42
  43 /// Captures #include mapping information. It analyses IWYU Pragma comments and
  44 /// other use-instead-like mechanisms (#pragma include_instead) on included
  45 /// files.
  46 ///
  47 /// This is a low-level piece being used in the "Location => Header" analysis
  48 /// step to determine the final public header rather than the header directly
  49 /// defines the symbol.
  50 class PragmaIncludes {
  51 public:
  52   /// Installs an analysing PPCallback and CommentHandler and populates results
  53   /// to the structure.
  54   void record(const CompilerInstance &CI);
  55
  56   /// Installs an analysing PPCallback and CommentHandler and populates results
  57   /// to the structure.
  58   void record(Preprocessor &P);
  59
  60   /// Returns true if the given #include of the main-file should never be
  61   /// removed.
  62   bool shouldKeep(unsigned HashLineNumber) const {
  63     return ShouldKeep.contains(HashLineNumber);
  64   }
  65
  66   /// Returns the public mapping include for the given physical header file.
  67   /// Returns "" if there is none.
  68   llvm::StringRef getPublic(const FileEntry *File) const;
  69
  70   /// Returns all direct exporter headers for the given header file.
  71   /// Returns empty if there is none.
  72   llvm::SmallVector<const FileEntry *> getExporters(const FileEntry *File,
  73                                                     FileManager &FM) const;
  74   llvm::SmallVector<const FileEntry *> getExporters(tooling::stdlib::Header,
  75                                                     FileManager &FM) const;
  76
  77   /// Returns true if the given file is a self-contained file.
  78   bool isSelfContained(const FileEntry *File) const;
  79
  80   /// Returns true if the given file is marked with the IWYU private pragma.
  81   bool isPrivate(const FileEntry *File) const;
  82
  83 private:
  84   class RecordPragma;
  85   /// 1-based Line numbers for the #include directives of the main file that
  86   /// should always keep (e.g. has the `IWYU pragma: keep` or `IWYU pragma:
  87   /// export` right after).
  88   llvm::DenseSet</*LineNumber*/ unsigned> ShouldKeep;
  89
  90   /// The public header mapping by the IWYU private pragma. For private pragmas
  91   //  without public mapping an empty StringRef is stored.
  92   //
  93   // !!NOTE: instead of using a FileEntry* to identify the physical file, we
  94   // deliberately use the UniqueID to ensure the result is stable across
  95   // FileManagers (for clangd's preamble and main-file builds).
  96   llvm::DenseMap<llvm::sys::fs::UniqueID, llvm::StringRef /*VerbatimSpelling*/>
  97       IWYUPublic;
  98
  99   /// A reverse map from the underlying header to its exporter headers.
 100   ///
 101   /// There's no way to get a FileEntry from a UniqueID, especially when it
 102   /// hasn't been opened before. So store the path and convert it to a
 103   /// FileEntry by opening the file again through a FileManager.
 104   ///
 105   /// We don't use RealPathName, as opening the file through a different name
 106   /// changes its preferred name. Clearly this is fragile!
 107   llvm::DenseMap<llvm::sys::fs::UniqueID,
 108                  llvm::SmallVector</*FileEntry::getName()*/ llvm::StringRef>>
 109       IWYUExportBy;
 110   llvm::DenseMap<tooling::stdlib::Header,
 111                  llvm::SmallVector</*FileEntry::getName()*/ llvm::StringRef>>
 112       StdIWYUExportBy;
 113
 114   /// Contains all non self-contained files detected during the parsing.
 115   llvm::DenseSet<llvm::sys::fs::UniqueID> NonSelfContainedFiles;
 116
 117   /// Owns the strings.
 118   llvm::BumpPtrAllocator Arena;
 119
 120   // FIXME: add support for clang use_instead pragma
 121 };
 122
 123 /// Recorded main-file parser events relevant to include-cleaner.
 124 struct RecordedAST {
 125   /// The consumer (when installed into clang) tracks declarations in `*this`.
 126   std::unique_ptr<ASTConsumer> record();
 127
 128   ASTContext *Ctx = nullptr;
 129   /// The set of declarations written at file scope inside the main file.
 130   ///
 131   /// These are the roots of the subtrees that should be traversed to find uses.
 132   /// (Traversing the TranslationUnitDecl would find uses inside headers!)
 133   std::vector<Decl *> Roots;
 134 };
 135
 136 /// Recorded main-file preprocessor events relevant to include-cleaner.
 137 ///
 138 /// This doesn't include facts that we record globally for the whole TU, even
 139 /// when they occur in the main file (e.g. IWYU pragmas).
 140 struct RecordedPP {
 141   /// The callback (when installed into clang) tracks macros/includes in this.
 142   std::unique_ptr<PPCallbacks> record(const Preprocessor &PP);
 143
 144   /// Describes where macros were used in the main file.
 145   std::vector<SymbolReference> MacroReferences;
 146
 147   /// The include directives seen in the main file.
 148   include_cleaner::Includes Includes;
 149 };
 150
 151 } // namespace include_cleaner
 152 } // namespace clang
 153
 154 #endif