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
34namespace clang {
35namespace clangd {
36
37enum 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.
43struct 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.
53llvm::Expected<IndexFileIn> readIndexFile(llvm::StringRef, SymbolOrigin);
54
55// Specifies the contents of an index file to be written.
56struct 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.
75llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const IndexFileOut &O);
76
77// Convert a single symbol to YAML, a nice debug representation.
78std::string toYAML(const Symbol &);
79std::string toYAML(const std::pair<SymbolID, ArrayRef<Ref>> &);
80std::string toYAML(const Relation &);
81std::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.
85std::unique_ptr<SymbolIndex> loadIndex(llvm::StringRef Filename,
86 SymbolOrigin Origin, bool UseDex = true);
87
88} // namespace clangd
89} // namespace clang
90
91#endif
92

source code of clang-tools-extra/clangd/index/Serialization.h