1 //===- Tooling.h - Framework for standalone Clang tools ---------*- 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 implements functions to run clang tools standalone instead
10 // of running them as a plugin.
11 //
12 // A ClangTool is initialized with a CompilationDatabase and a set of files
13 // to run over. The tool will then run a user-specified FrontendAction over
14 // all TUs in which the given files are compiled.
15 //
16 // It is also possible to run a FrontendAction over a snippet of code by
17 // calling runToolOnCode, which is useful for unit testing.
18 //
19 // Applications that need more fine grained control over how to run
20 // multiple FrontendActions over code can use ToolInvocation.
21 //
22 // Example tools:
23 // - running clang -fsyntax-only over source code from an editor to get
24 // fast syntax checks
25 // - running match/replace tools over C++ code
26 //
27 //===----------------------------------------------------------------------===//
28
29 #ifndef LLVM_CLANG_TOOLING_TOOLING_H
30 #define LLVM_CLANG_TOOLING_TOOLING_H
31
32 #include "clang/AST/ASTConsumer.h"
33 #include "clang/Basic/FileManager.h"
34 #include "clang/Basic/LLVM.h"
35 #include "clang/Frontend/FrontendAction.h"
36 #include "clang/Frontend/PCHContainerOperations.h"
37 #include "clang/Tooling/ArgumentsAdjusters.h"
38 #include "llvm/ADT/ArrayRef.h"
39 #include "llvm/ADT/IntrusiveRefCntPtr.h"
40 #include "llvm/ADT/StringMap.h"
41 #include "llvm/ADT/StringRef.h"
42 #include "llvm/ADT/StringSet.h"
43 #include "llvm/ADT/Twine.h"
44 #include "llvm/Option/Option.h"
45 #include "llvm/Support/VirtualFileSystem.h"
46 #include <memory>
47 #include <string>
48 #include <utility>
49 #include <vector>
50
51 namespace clang {
52
53 class CompilerInstance;
54 class CompilerInvocation;
55 class DiagnosticConsumer;
56 class DiagnosticsEngine;
57 class SourceManager;
58
59 namespace driver {
60
61 class Compilation;
62
63 } // namespace driver
64
65 namespace tooling {
66
67 class CompilationDatabase;
68
69 /// Retrieves the flags of the `-cc1` job in `Compilation` that has only source
70 /// files as its inputs.
71 /// Returns nullptr if there are no such jobs or multiple of them. Note that
72 /// offloading jobs are ignored.
73 const llvm::opt::ArgStringList *
74 getCC1Arguments(DiagnosticsEngine *Diagnostics,
75 driver::Compilation *Compilation);
76
77 /// Interface to process a clang::CompilerInvocation.
78 ///
79 /// If your tool is based on FrontendAction, you should be deriving from
80 /// FrontendActionFactory instead.
81 class ToolAction {
82 public:
83 virtual ~ToolAction();
84
85 /// Perform an action for an invocation.
86 virtual bool
87 runInvocation(std::shared_ptr<CompilerInvocation> Invocation,
88 FileManager *Files,
89 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
90 DiagnosticConsumer *DiagConsumer) = 0;
91 };
92
93 /// Interface to generate clang::FrontendActions.
94 ///
95 /// Having a factory interface allows, for example, a new FrontendAction to be
96 /// created for each translation unit processed by ClangTool. This class is
97 /// also a ToolAction which uses the FrontendActions created by create() to
98 /// process each translation unit.
99 class FrontendActionFactory : public ToolAction {
100 public:
101 ~FrontendActionFactory() override;
102
103 /// Invokes the compiler with a FrontendAction created by create().
104 bool runInvocation(std::shared_ptr<CompilerInvocation> Invocation,
105 FileManager *Files,
106 std::shared_ptr<PCHContainerOperations> PCHContainerOps,
107 DiagnosticConsumer *DiagConsumer) override;
108
109 /// Returns a new clang::FrontendAction.
110 virtual std::unique_ptr<FrontendAction> create() = 0;
111 };
112
113 /// Returns a new FrontendActionFactory for a given type.
114 ///
115 /// T must derive from clang::FrontendAction.
116 ///
117 /// Example:
118 /// FrontendActionFactory *Factory =
119 /// newFrontendActionFactory<clang::SyntaxOnlyAction>();
120 template <typename T>
121 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory();
122
123 /// Callbacks called before and after each source file processed by a
124 /// FrontendAction created by the FrontedActionFactory returned by \c
125 /// newFrontendActionFactory.
126 class SourceFileCallbacks {
127 public:
128 virtual ~SourceFileCallbacks() = default;
129
130 /// Called before a source file is processed by a FrontEndAction.
131 /// \see clang::FrontendAction::BeginSourceFileAction
handleBeginSource(CompilerInstance & CI)132 virtual bool handleBeginSource(CompilerInstance &CI) {
133 return true;
134 }
135
136 /// Called after a source file is processed by a FrontendAction.
137 /// \see clang::FrontendAction::EndSourceFileAction
handleEndSource()138 virtual void handleEndSource() {}
139 };
140
141 /// Returns a new FrontendActionFactory for any type that provides an
142 /// implementation of newASTConsumer().
143 ///
144 /// FactoryT must implement: ASTConsumer *newASTConsumer().
145 ///
146 /// Example:
147 /// struct ProvidesASTConsumers {
148 /// clang::ASTConsumer *newASTConsumer();
149 /// } Factory;
150 /// std::unique_ptr<FrontendActionFactory> FactoryAdapter(
151 /// newFrontendActionFactory(&Factory));
152 template <typename FactoryT>
153 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
154 FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks = nullptr);
155
156 /// Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag.
157 ///
158 /// \param ToolAction The action to run over the code.
159 /// \param Code C++ code.
160 /// \param FileName The file name which 'Code' will be mapped as.
161 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
162 /// clang modules.
163 ///
164 /// \return - True if 'ToolAction' was successfully executed.
165 bool runToolOnCode(std::unique_ptr<FrontendAction> ToolAction, const Twine &Code,
166 const Twine &FileName = "input.cc",
167 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
168 std::make_shared<PCHContainerOperations>());
169
170 /// The first part of the pair is the filename, the second part the
171 /// file-content.
172 using FileContentMappings = std::vector<std::pair<std::string, std::string>>;
173
174 /// Runs (and deletes) the tool on 'Code' with the -fsyntax-only flag and
175 /// with additional other flags.
176 ///
177 /// \param ToolAction The action to run over the code.
178 /// \param Code C++ code.
179 /// \param Args Additional flags to pass on.
180 /// \param FileName The file name which 'Code' will be mapped as.
181 /// \param ToolName The name of the binary running the tool. Standard library
182 /// header paths will be resolved relative to this.
183 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
184 /// clang modules.
185 ///
186 /// \return - True if 'ToolAction' was successfully executed.
187 bool runToolOnCodeWithArgs(
188 std::unique_ptr<FrontendAction> ToolAction, const Twine &Code,
189 const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
190 const Twine &ToolName = "clang-tool",
191 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
192 std::make_shared<PCHContainerOperations>(),
193 const FileContentMappings &VirtualMappedFiles = FileContentMappings());
194
195 // Similar to the overload except this takes a VFS.
196 bool runToolOnCodeWithArgs(
197 std::unique_ptr<FrontendAction> ToolAction, const Twine &Code,
198 llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS,
199 const std::vector<std::string> &Args, const Twine &FileName = "input.cc",
200 const Twine &ToolName = "clang-tool",
201 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
202 std::make_shared<PCHContainerOperations>());
203
204 /// Builds an AST for 'Code'.
205 ///
206 /// \param Code C++ code.
207 /// \param FileName The file name which 'Code' will be mapped as.
208 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
209 /// clang modules.
210 ///
211 /// \return The resulting AST or null if an error occurred.
212 std::unique_ptr<ASTUnit>
213 buildASTFromCode(StringRef Code, StringRef FileName = "input.cc",
214 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
215 std::make_shared<PCHContainerOperations>());
216
217 /// Builds an AST for 'Code' with additional flags.
218 ///
219 /// \param Code C++ code.
220 /// \param Args Additional flags to pass on.
221 /// \param FileName The file name which 'Code' will be mapped as.
222 /// \param ToolName The name of the binary running the tool. Standard library
223 /// header paths will be resolved relative to this.
224 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
225 /// clang modules.
226 ///
227 /// \param Adjuster A function to filter the command line arguments as specified.
228 ///
229 /// \return The resulting AST or null if an error occurred.
230 std::unique_ptr<ASTUnit> buildASTFromCodeWithArgs(
231 StringRef Code, const std::vector<std::string> &Args,
232 StringRef FileName = "input.cc", StringRef ToolName = "clang-tool",
233 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
234 std::make_shared<PCHContainerOperations>(),
235 ArgumentsAdjuster Adjuster = getClangStripDependencyFileAdjuster(),
236 const FileContentMappings &VirtualMappedFiles = FileContentMappings(),
237 DiagnosticConsumer *DiagConsumer = nullptr);
238
239 /// Utility to run a FrontendAction in a single clang invocation.
240 class ToolInvocation {
241 public:
242 /// Create a tool invocation.
243 ///
244 /// \param CommandLine The command line arguments to clang. Note that clang
245 /// uses its binary name (CommandLine[0]) to locate its builtin headers.
246 /// Callers have to ensure that they are installed in a compatible location
247 /// (see clang driver implementation) or mapped in via mapVirtualFile.
248 /// \param FAction The action to be executed.
249 /// \param Files The FileManager used for the execution. Class does not take
250 /// ownership.
251 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
252 /// clang modules.
253 ToolInvocation(std::vector<std::string> CommandLine,
254 std::unique_ptr<FrontendAction> FAction, FileManager *Files,
255 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
256 std::make_shared<PCHContainerOperations>());
257
258 /// Create a tool invocation.
259 ///
260 /// \param CommandLine The command line arguments to clang.
261 /// \param Action The action to be executed.
262 /// \param Files The FileManager used for the execution.
263 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
264 /// clang modules.
265 ToolInvocation(std::vector<std::string> CommandLine, ToolAction *Action,
266 FileManager *Files,
267 std::shared_ptr<PCHContainerOperations> PCHContainerOps);
268
269 ~ToolInvocation();
270
271 /// Set a \c DiagnosticConsumer to use during driver command-line parsing and
272 /// the action invocation itself.
setDiagnosticConsumer(DiagnosticConsumer * DiagConsumer)273 void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
274 this->DiagConsumer = DiagConsumer;
275 }
276
277 /// Set a \c DiagnosticOptions to use during driver command-line parsing.
setDiagnosticOptions(DiagnosticOptions * DiagOpts)278 void setDiagnosticOptions(DiagnosticOptions *DiagOpts) {
279 this->DiagOpts = DiagOpts;
280 }
281
282 /// Run the clang invocation.
283 ///
284 /// \returns True if there were no errors during execution.
285 bool run();
286
287 private:
288 bool runInvocation(const char *BinaryName,
289 driver::Compilation *Compilation,
290 std::shared_ptr<CompilerInvocation> Invocation,
291 std::shared_ptr<PCHContainerOperations> PCHContainerOps);
292
293 std::vector<std::string> CommandLine;
294 ToolAction *Action;
295 bool OwnsAction;
296 FileManager *Files;
297 std::shared_ptr<PCHContainerOperations> PCHContainerOps;
298 DiagnosticConsumer *DiagConsumer = nullptr;
299 DiagnosticOptions *DiagOpts = nullptr;
300 };
301
302 /// Utility to run a FrontendAction over a set of files.
303 ///
304 /// This class is written to be usable for command line utilities.
305 /// By default the class uses ClangSyntaxOnlyAdjuster to modify
306 /// command line arguments before the arguments are used to run
307 /// a frontend action. One could install an additional command line
308 /// arguments adjuster by calling the appendArgumentsAdjuster() method.
309 class ClangTool {
310 public:
311 /// Constructs a clang tool to run over a list of files.
312 ///
313 /// \param Compilations The CompilationDatabase which contains the compile
314 /// command lines for the given source paths.
315 /// \param SourcePaths The source files to run over. If a source files is
316 /// not found in Compilations, it is skipped.
317 /// \param PCHContainerOps The PCHContainerOperations for loading and creating
318 /// clang modules.
319 /// \param BaseFS VFS used for all underlying file accesses when running the
320 /// tool.
321 /// \param Files The file manager to use for underlying file operations when
322 /// running the tool.
323 ClangTool(const CompilationDatabase &Compilations,
324 ArrayRef<std::string> SourcePaths,
325 std::shared_ptr<PCHContainerOperations> PCHContainerOps =
326 std::make_shared<PCHContainerOperations>(),
327 IntrusiveRefCntPtr<llvm::vfs::FileSystem> BaseFS =
328 llvm::vfs::getRealFileSystem(),
329 IntrusiveRefCntPtr<FileManager> Files = nullptr);
330
331 ~ClangTool();
332
333 /// Set a \c DiagnosticConsumer to use during parsing.
setDiagnosticConsumer(DiagnosticConsumer * DiagConsumer)334 void setDiagnosticConsumer(DiagnosticConsumer *DiagConsumer) {
335 this->DiagConsumer = DiagConsumer;
336 }
337
338 /// Map a virtual file to be used while running the tool.
339 ///
340 /// \param FilePath The path at which the content will be mapped.
341 /// \param Content A null terminated buffer of the file's content.
342 void mapVirtualFile(StringRef FilePath, StringRef Content);
343
344 /// Append a command line arguments adjuster to the adjuster chain.
345 ///
346 /// \param Adjuster An argument adjuster, which will be run on the output of
347 /// previous argument adjusters.
348 void appendArgumentsAdjuster(ArgumentsAdjuster Adjuster);
349
350 /// Clear the command line arguments adjuster chain.
351 void clearArgumentsAdjusters();
352
353 /// Runs an action over all files specified in the command line.
354 ///
355 /// \param Action Tool action.
356 ///
357 /// \returns 0 on success; 1 if any error occurred; 2 if there is no error but
358 /// some files are skipped due to missing compile commands.
359 int run(ToolAction *Action);
360
361 /// Create an AST for each file specified in the command line and
362 /// append them to ASTs.
363 int buildASTs(std::vector<std::unique_ptr<ASTUnit>> &ASTs);
364
365 /// Sets whether working directory should be restored after calling run(). By
366 /// default, working directory is restored. However, it could be useful to
367 /// turn this off when running on multiple threads to avoid the raciness.
368 void setRestoreWorkingDir(bool RestoreCWD);
369
370 /// Sets whether an error message should be printed out if an action fails. By
371 /// default, if an action fails, a message is printed out to stderr.
372 void setPrintErrorMessage(bool PrintErrorMessage);
373
374 /// Returns the file manager used in the tool.
375 ///
376 /// The file manager is shared between all translation units.
getFiles()377 FileManager &getFiles() { return *Files; }
378
getSourcePaths()379 llvm::ArrayRef<std::string> getSourcePaths() const { return SourcePaths; }
380
381 private:
382 const CompilationDatabase &Compilations;
383 std::vector<std::string> SourcePaths;
384 std::shared_ptr<PCHContainerOperations> PCHContainerOps;
385
386 llvm::IntrusiveRefCntPtr<llvm::vfs::OverlayFileSystem> OverlayFileSystem;
387 llvm::IntrusiveRefCntPtr<llvm::vfs::InMemoryFileSystem> InMemoryFileSystem;
388 llvm::IntrusiveRefCntPtr<FileManager> Files;
389
390 // Contains a list of pairs (<file name>, <file content>).
391 std::vector<std::pair<StringRef, StringRef>> MappedFileContents;
392
393 llvm::StringSet<> SeenWorkingDirectories;
394
395 ArgumentsAdjuster ArgsAdjuster;
396
397 DiagnosticConsumer *DiagConsumer = nullptr;
398
399 bool RestoreCWD = true;
400 bool PrintErrorMessage = true;
401 };
402
403 template <typename T>
newFrontendActionFactory()404 std::unique_ptr<FrontendActionFactory> newFrontendActionFactory() {
405 class SimpleFrontendActionFactory : public FrontendActionFactory {
406 public:
407 std::unique_ptr<FrontendAction> create() override {
408 return std::make_unique<T>();
409 }
410 };
411
412 return std::unique_ptr<FrontendActionFactory>(
413 new SimpleFrontendActionFactory);
414 }
415
416 template <typename FactoryT>
newFrontendActionFactory(FactoryT * ConsumerFactory,SourceFileCallbacks * Callbacks)417 inline std::unique_ptr<FrontendActionFactory> newFrontendActionFactory(
418 FactoryT *ConsumerFactory, SourceFileCallbacks *Callbacks) {
419 class FrontendActionFactoryAdapter : public FrontendActionFactory {
420 public:
421 explicit FrontendActionFactoryAdapter(FactoryT *ConsumerFactory,
422 SourceFileCallbacks *Callbacks)
423 : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
424
425 std::unique_ptr<FrontendAction> create() override {
426 return std::make_unique<ConsumerFactoryAdaptor>(ConsumerFactory,
427 Callbacks);
428 }
429
430 private:
431 class ConsumerFactoryAdaptor : public ASTFrontendAction {
432 public:
433 ConsumerFactoryAdaptor(FactoryT *ConsumerFactory,
434 SourceFileCallbacks *Callbacks)
435 : ConsumerFactory(ConsumerFactory), Callbacks(Callbacks) {}
436
437 std::unique_ptr<ASTConsumer>
438 CreateASTConsumer(CompilerInstance &, StringRef) override {
439 return ConsumerFactory->newASTConsumer();
440 }
441
442 protected:
443 bool BeginSourceFileAction(CompilerInstance &CI) override {
444 if (!ASTFrontendAction::BeginSourceFileAction(CI))
445 return false;
446 if (Callbacks)
447 return Callbacks->handleBeginSource(CI);
448 return true;
449 }
450
451 void EndSourceFileAction() override {
452 if (Callbacks)
453 Callbacks->handleEndSource();
454 ASTFrontendAction::EndSourceFileAction();
455 }
456
457 private:
458 FactoryT *ConsumerFactory;
459 SourceFileCallbacks *Callbacks;
460 };
461 FactoryT *ConsumerFactory;
462 SourceFileCallbacks *Callbacks;
463 };
464
465 return std::unique_ptr<FrontendActionFactory>(
466 new FrontendActionFactoryAdapter(ConsumerFactory, Callbacks));
467 }
468
469 /// Returns the absolute path of \c File, by prepending it with
470 /// the current directory if \c File is not absolute.
471 ///
472 /// Otherwise returns \c File.
473 /// If 'File' starts with "./", the returned path will not contain the "./".
474 /// Otherwise, the returned path will contain the literal path-concatenation of
475 /// the current directory and \c File.
476 ///
477 /// The difference to llvm::sys::fs::make_absolute is the canonicalization this
478 /// does by removing "./" and computing native paths.
479 ///
480 /// \param File Either an absolute or relative path.
481 std::string getAbsolutePath(StringRef File);
482
483 /// An overload of getAbsolutePath that works over the provided \p FS.
484 llvm::Expected<std::string> getAbsolutePath(llvm::vfs::FileSystem &FS,
485 StringRef File);
486
487 /// Changes CommandLine to contain implicit flags that would have been
488 /// defined had the compiler driver been invoked through the path InvokedAs.
489 ///
490 /// For example, when called with \c InvokedAs set to `i686-linux-android-g++`,
491 /// the arguments '-target', 'i686-linux-android`, `--driver-mode=g++` will
492 /// be inserted after the first argument in \c CommandLine.
493 ///
494 /// This function will not add new `-target` or `--driver-mode` flags if they
495 /// are already present in `CommandLine` (even if they have different settings
496 /// than would have been inserted).
497 ///
498 /// \pre `llvm::InitializeAllTargets()` has been called.
499 ///
500 /// \param CommandLine the command line used to invoke the compiler driver or
501 /// Clang tool, including the path to the executable as \c CommandLine[0].
502 /// \param InvokedAs the path to the driver used to infer implicit flags.
503 ///
504 /// \note This will not set \c CommandLine[0] to \c InvokedAs. The tooling
505 /// infrastructure expects that CommandLine[0] is a tool path relative to which
506 /// the builtin headers can be found.
507 void addTargetAndModeForProgramName(std::vector<std::string> &CommandLine,
508 StringRef InvokedAs);
509
510 /// Creates a \c CompilerInvocation.
511 CompilerInvocation *newInvocation(DiagnosticsEngine *Diagnostics,
512 const llvm::opt::ArgStringList &CC1Args,
513 const char *const BinaryName);
514
515 } // namespace tooling
516
517 } // namespace clang
518
519 #endif // LLVM_CLANG_TOOLING_TOOLING_H
520