CrossTranslationUnit.h source code [clang_source_code/include/clang/CrossTU/CrossTranslationUnit.h]

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