clang-tools 17.0.0git
Serialization.h
Go to the documentation of this file.
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.
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.
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.
64 const tooling::CompileCommand *Cmd = nullptr;
65
66 IndexFileOut() = default;
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
std::string Filename
Filename as a string.
llvm::raw_string_ostream OS
Definition: TraceTests.cpp:160
An efficient structure of storing large set of symbol references in memory.
Definition: Ref.h:108
An immutable symbol container that stores a set of symbols.
Definition: Symbol.h:199
llvm::Expected< IndexFileIn > readIndexFile(llvm::StringRef Data, SymbolOrigin Origin)
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
llvm::StringMap< IncludeGraphNode > IncludeGraph
Definition: Headers.h:102
std::unique_ptr< SymbolIndex > loadIndex(llvm::StringRef SymbolFilename, SymbolOrigin Origin, bool UseDex)
std::string toYAML(const Symbol &)
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::optional< RelationSlab > Relations
Definition: Serialization.h:46
std::optional< SymbolSlab > Symbols
Definition: Serialization.h:44
std::optional< RefSlab > Refs
Definition: Serialization.h:45
std::optional< tooling::CompileCommand > Cmd
Definition: Serialization.h:50
std::optional< IncludeGraph > Sources
Definition: Serialization.h:48
const IncludeGraph * Sources
Definition: Serialization.h:61
const RelationSlab * Relations
Definition: Serialization.h:59
const tooling::CompileCommand * Cmd
Definition: Serialization.h:64
const SymbolSlab * Symbols
Definition: Serialization.h:57
IndexFileOut(const IndexFileIn &I)
Definition: Serialization.h:67
Represents a symbol occurrence in the source file.
Definition: Ref.h:85
Represents a relation between two symbols.
Definition: Relation.h:32