clang-tools-extra/clangd/index/Serialization.h

   1 //===--- Serialization.h - Binary serialization of index data ----*- 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 // This file provides serialization of indexed symbols and other data.
  10 //
  11 // It writes sections:
  12 //  - metadata such as version info
  13 //  - a string table (which is compressed)
  14 //  - lists of encoded symbols
  15 //
  16 // The format has a simple versioning scheme: the format version number is
  17 // written in the file and non-current versions are rejected when reading.
  18 //
  19 // Human-readable YAML serialization is also supported, and recommended for
  20 // debugging and experiments only.
  21 //
  22 //===----------------------------------------------------------------------===//
  23
  24 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SERIALIZATION_H
  25 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_SERIALIZATION_H
  26
  27 #include "Headers.h"
  28 #include "index/Index.h"
  29 #include "index/Symbol.h"
  30 #include "clang/Tooling/CompilationDatabase.h"
  31 #include "llvm/Support/Error.h"
  32 #include <optional>
  33
  34 namespace clang {
  35 namespace clangd {
  36
  37 enum class IndexFileFormat {
  38   RIFF, // Versioned binary format, suitable for production use.
  39   YAML, // Human-readable format, suitable for experiments and debugging.
  40 };
  41
  42 // Holds the contents of an index file that was read.
  43 struct IndexFileIn {
  44   std::optional<SymbolSlab> Symbols;
  45   std::optional<RefSlab> Refs;
  46   std::optional<RelationSlab> Relations;
  47   // Keys are URIs of the source files.
  48   std::optional<IncludeGraph> Sources;
  49   // This contains only the Directory and CommandLine.
  50   std::optional<tooling::CompileCommand> Cmd;
  51 };
  52 // Parse an index file. The input must be a RIFF or YAML file.
  53 llvm::Expected<IndexFileIn> readIndexFile(llvm::StringRef, SymbolOrigin);
  54
  55 // Specifies the contents of an index file to be written.
  56 struct IndexFileOut {
  57   const SymbolSlab *Symbols = nullptr;
  58   const RefSlab *Refs = nullptr;
  59   const RelationSlab *Relations = nullptr;
  60   // Keys are URIs of the source files.
  61   const IncludeGraph *Sources = nullptr;
  62   // TODO: Support serializing Dex posting lists.
  63   IndexFileFormat Format = IndexFileFormat::RIFF;
  64   const tooling::CompileCommand *Cmd = nullptr;
  65
  66   IndexFileOut() = default;
  67   IndexFileOut(const IndexFileIn &I)
  68       : Symbols(I.Symbols ? &*I.Symbols : nullptr),
  69         Refs(I.Refs ? &*I.Refs : nullptr),
  70         Relations(I.Relations ? &*I.Relations : nullptr),
  71         Sources(I.Sources ? &*I.Sources : nullptr),
  72         Cmd(I.Cmd ? &*I.Cmd : nullptr) {}
  73 };
  74 // Serializes an index file.
  75 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const IndexFileOut &O);
  76
  77 // Convert a single symbol to YAML, a nice debug representation.
  78 std::string toYAML(const Symbol &);
  79 std::string toYAML(const std::pair<SymbolID, ArrayRef<Ref>> &);
  80 std::string toYAML(const Relation &);
  81 std::string toYAML(const Ref &);
  82
  83 // Build an in-memory static index from an index file.
  84 // The size should be relatively small, so data can be managed in memory.
  85 std::unique_ptr<SymbolIndex> loadIndex(llvm::StringRef Filename,
  86                                        SymbolOrigin Origin, bool UseDex = true);
  87
  88 } // namespace clangd
  89 } // namespace clang
  90
  91 #endif