1//===--- CrossTranslationUnit.h - -------------------------------*- 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 an interface to load binary AST dumps on demand. This
10// feature can be utilized for tools that require cross translation unit
11// support.
12//
13//===----------------------------------------------------------------------===//
14#ifndef LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H
15#define LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H
16
17#include "clang/AST/ASTImporterLookupTable.h"
18#include "clang/Basic/LLVM.h"
19#include "llvm/ADT/DenseMap.h"
20#include "llvm/ADT/SmallPtrSet.h"
21#include "llvm/ADT/StringMap.h"
22#include "llvm/Support/Error.h"
23
24namespace clang {
25class CompilerInstance;
26class ASTContext;
27class ASTImporter;
28class ASTUnit;
29class DeclContext;
30class FunctionDecl;
31class NamedDecl;
32class TranslationUnitDecl;
33
34namespace cross_tu {
35
36enum class index_error_code {
37 unspecified = 1,
38 missing_index_file,
39 invalid_index_format,
40 multiple_definitions,
41 missing_definition,
42 failed_import,
43 failed_to_get_external_ast,
44 failed_to_generate_usr,
45 triple_mismatch,
46 lang_mismatch
47};
48
49class IndexError : public llvm::ErrorInfo<IndexError> {
50public:
51 static char ID;
52 IndexError(index_error_code C) : Code(C), LineNo(0) {}
53 IndexError(index_error_code C, std::string FileName, int LineNo = 0)
54 : Code(C), FileName(std::move(FileName)), LineNo(LineNo) {}
55 IndexError(index_error_code C, std::string FileName, std::string TripleToName,
56 std::string TripleFromName)
57 : Code(C), FileName(std::move(FileName)),
58 TripleToName(std::move(TripleToName)),
59 TripleFromName(std::move(TripleFromName)) {}
60 void log(raw_ostream &OS) const override;
61 std::error_code convertToErrorCode() const override;
62 index_error_code getCode() const { return Code; }
63 int getLineNum() const { return LineNo; }
64 std::string getFileName() const { return FileName; }
65 std::string getTripleToName() const { return TripleToName; }
66 std::string getTripleFromName() const { return TripleFromName; }
67
68private:
69 index_error_code Code;
70 std::string FileName;
71 int LineNo;
72 std::string TripleToName;
73 std::string TripleFromName;
74};
75
76/// This function parses an index file that determines which
77/// translation unit contains which definition.
78///
79/// The index file format is the following:
80/// each line consists of an USR and a filepath separated by a space.
81///
82/// \return Returns a map where the USR is the key and the filepath is the value
83/// or an error.
84llvm::Expected<llvm::StringMap<std::string>>
85parseCrossTUIndex(StringRef IndexPath, StringRef CrossTUDir);
86
87std::string createCrossTUIndexString(const llvm::StringMap<std::string> &Index);
88
89/// This class is used for tools that requires cross translation
90/// unit capability.
91///
92/// This class can load definitions from external AST files.
93/// The loaded definition will be merged back to the original AST using the
94/// AST Importer.
95/// In order to use this class, an index file is required that describes
96/// the locations of the AST files for each definition.
97///
98/// Note that this class also implements caching.
99class CrossTranslationUnitContext {
100public:
101 CrossTranslationUnitContext(CompilerInstance &CI);
102 ~CrossTranslationUnitContext();
103
104 /// This function loads a function definition from an external AST
105 /// file and merge it into the original AST.
106 ///
107 /// This method should only be used on functions that have no definitions in
108 /// the current translation unit. A function definition with the same
109 /// declaration will be looked up in the index file which should be in the
110 /// \p CrossTUDir directory, called \p IndexName. In case the declaration is
111 /// found in the index the corresponding AST file will be loaded and the
112 /// definition of the function will be merged into the original AST using
113 /// the AST Importer.
114 ///
115 /// \return The declaration with the definition will be returned.
116 /// If no suitable definition is found in the index file or multiple
117 /// definitions found error will be returned.
118 ///
119 /// Note that the AST files should also be in the \p CrossTUDir.
120 llvm::Expected<const FunctionDecl *>
121 getCrossTUDefinition(const FunctionDecl *FD, StringRef CrossTUDir,
122 StringRef IndexName, bool DisplayCTUProgress = false);
123
124 /// This function loads a function definition from an external AST
125 /// file.
126 ///
127 /// A function definition with the same declaration will be looked up in the
128 /// index file which should be in the \p CrossTUDir directory, called
129 /// \p IndexName. In case the declaration is found in the index the
130 /// corresponding AST file will be loaded.
131 ///
132 /// \return Returns a pointer to the ASTUnit that contains the definition of
133 /// the looked up function or an Error.
134 /// The returned pointer is never a nullptr.
135 ///
136 /// Note that the AST files should also be in the \p CrossTUDir.
137 llvm::Expected<ASTUnit *> loadExternalAST(StringRef LookupName,
138 StringRef CrossTUDir,
139 StringRef IndexName,
140 bool DisplayCTUProgress = false);
141
142 /// This function merges a definition from a separate AST Unit into
143 /// the current one which was created by the compiler instance that
144 /// was passed to the constructor.
145 ///
146 /// \return Returns the resulting definition or an error.
147 llvm::Expected<const FunctionDecl *> importDefinition(const FunctionDecl *FD);
148
149 /// Get a name to identify a function.
150 static std::string getLookupName(const NamedDecl *ND);
151
152 /// Emit diagnostics for the user for potential configuration errors.
153 void emitCrossTUDiagnostics(const IndexError &IE);
154
155private:
156 void lazyInitLookupTable(TranslationUnitDecl *ToTU);
157 ASTImporter &getOrCreateASTImporter(ASTContext &From);
158 const FunctionDecl *findFunctionInDeclContext(const DeclContext *DC,
159 StringRef LookupFnName);
160
161 llvm::StringMap<std::unique_ptr<clang::ASTUnit>> FileASTUnitMap;
162 llvm::StringMap<clang::ASTUnit *> FunctionASTUnitMap;
163 llvm::StringMap<std::string> FunctionFileMap;
164 llvm::DenseMap<TranslationUnitDecl *, std::unique_ptr<ASTImporter>>
165 ASTUnitImporterMap;
166 CompilerInstance &CI;
167 ASTContext &Context;
168 std::unique_ptr<ASTImporterLookupTable> LookupTable;
169};
170
171} // namespace cross_tu
172} // namespace clang
173
174#endif // LLVM_CLANG_CROSSTU_CROSSTRANSLATIONUNIT_H
175