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_RIFF_H 25 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_INDEX_RIFF_H 26 27 #include "Headers.h" 28 #include "Index.h" 29 #include "index/Symbol.h" 30 #include "clang/Tooling/CompilationDatabase.h" 31 #include "llvm/Support/Error.h" 32 33 namespace clang { 34 namespace clangd { 35 36 enum class IndexFileFormat { 37 RIFF, // Versioned binary format, suitable for production use. 38 YAML, // Human-readable format, suitable for experiments and debugging. 39 }; 40 41 // Holds the contents of an index file that was read. 42 struct IndexFileIn { 43 llvm::Optional<SymbolSlab> Symbols; 44 llvm::Optional<RefSlab> Refs; 45 llvm::Optional<RelationSlab> Relations; 46 // Keys are URIs of the source files. 47 llvm::Optional<IncludeGraph> Sources; 48 // This contains only the Directory and CommandLine. 49 llvm::Optional<tooling::CompileCommand> Cmd; 50 }; 51 // Parse an index file. The input must be a RIFF or YAML file. 52 llvm::Expected<IndexFileIn> readIndexFile(llvm::StringRef); 53 54 // Specifies the contents of an index file to be written. 55 struct IndexFileOut { 56 const SymbolSlab *Symbols = nullptr; 57 const RefSlab *Refs = nullptr; 58 const RelationSlab *Relations = nullptr; 59 // Keys are URIs of the source files. 60 const IncludeGraph *Sources = nullptr; 61 // TODO: Support serializing Dex posting lists. 62 IndexFileFormat Format = IndexFileFormat::RIFF; 63 const tooling::CompileCommand *Cmd = nullptr; 64 65 IndexFileOut() = default; IndexFileOutIndexFileOut66 IndexFileOut(const IndexFileIn &I) 67 : Symbols(I.Symbols ? I.Symbols.getPointer() : nullptr), 68 Refs(I.Refs ? I.Refs.getPointer() : nullptr), 69 Relations(I.Relations ? I.Relations.getPointer() : nullptr), 70 Sources(I.Sources ? I.Sources.getPointer() : nullptr), 71 Cmd(I.Cmd ? I.Cmd.getPointer() : nullptr) {} 72 }; 73 // Serializes an index file. 74 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const IndexFileOut &O); 75 76 // Convert a single symbol to YAML, a nice debug representation. 77 std::string toYAML(const Symbol &); 78 std::string toYAML(const std::pair<SymbolID, ArrayRef<Ref>> &); 79 std::string toYAML(const Relation &); 80 std::string toYAML(const Ref &); 81 82 // Deserialize a single symbol from YAML. 83 llvm::Expected<clangd::Symbol> symbolFromYAML(StringRef YAML, 84 llvm::UniqueStringSaver *Strings); 85 llvm::Expected<clangd::Ref> refFromYAML(StringRef YAML, 86 llvm::UniqueStringSaver *Strings); 87 88 // Build an in-memory static index from an index file. 89 // The size should be relatively small, so data can be managed in memory. 90 std::unique_ptr<SymbolIndex> loadIndex(llvm::StringRef Filename, 91 bool UseDex = true); 92 93 } // namespace clangd 94 } // namespace clang 95 96 #endif 97