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, 87 bool SupportContainedRefs); 88 89 } // namespace clangd 90 } // namespace clang 91 92 #endif 93