1 | //===- Utils.h - Misc utilities for the front-end ---------------*- 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 header contains miscellaneous utilities for various front-end actions. |
10 | // |
11 | //===----------------------------------------------------------------------===// |
12 | |
13 | #ifndef LLVM_CLANG_FRONTEND_UTILS_H |
14 | #define LLVM_CLANG_FRONTEND_UTILS_H |
15 | |
16 | #include "clang/Basic/Diagnostic.h" |
17 | #include "clang/Basic/LLVM.h" |
18 | #include "clang/Driver/OptionUtils.h" |
19 | #include "clang/Frontend/DependencyOutputOptions.h" |
20 | #include "llvm/ADT/ArrayRef.h" |
21 | #include "llvm/ADT/IntrusiveRefCntPtr.h" |
22 | #include "llvm/ADT/StringMap.h" |
23 | #include "llvm/ADT/StringRef.h" |
24 | #include "llvm/ADT/StringSet.h" |
25 | #include "llvm/Support/FileCollector.h" |
26 | #include "llvm/Support/VirtualFileSystem.h" |
27 | #include <cstdint> |
28 | #include <memory> |
29 | #include <string> |
30 | #include <system_error> |
31 | #include <utility> |
32 | #include <vector> |
33 | |
34 | namespace clang { |
35 | |
36 | class ASTReader; |
37 | class CompilerInstance; |
38 | class CompilerInvocation; |
39 | class DiagnosticsEngine; |
40 | class ExternalSemaSource; |
41 | class FrontendOptions; |
42 | class PCHContainerReader; |
43 | class Preprocessor; |
44 | class PreprocessorOptions; |
45 | class PreprocessorOutputOptions; |
46 | class CodeGenOptions; |
47 | |
48 | /// InitializePreprocessor - Initialize the preprocessor getting it and the |
49 | /// environment ready to process a single file. |
50 | void InitializePreprocessor(Preprocessor &PP, const PreprocessorOptions &PPOpts, |
51 | const PCHContainerReader &PCHContainerRdr, |
52 | const FrontendOptions &FEOpts, |
53 | const CodeGenOptions &CodeGenOpts); |
54 | |
55 | /// DoPrintPreprocessedInput - Implement -E mode. |
56 | void DoPrintPreprocessedInput(Preprocessor &PP, raw_ostream *OS, |
57 | const PreprocessorOutputOptions &Opts); |
58 | |
59 | /// An interface for collecting the dependencies of a compilation. Users should |
60 | /// use \c attachToPreprocessor and \c attachToASTReader to get all of the |
61 | /// dependencies. |
62 | /// FIXME: Migrate DependencyGraphGen to use this interface. |
63 | class DependencyCollector { |
64 | public: |
65 | virtual ~DependencyCollector(); |
66 | |
67 | virtual void attachToPreprocessor(Preprocessor &PP); |
68 | virtual void attachToASTReader(ASTReader &R); |
69 | ArrayRef<std::string> getDependencies() const { return Dependencies; } |
70 | |
71 | /// Called when a new file is seen. Return true if \p Filename should be added |
72 | /// to the list of dependencies. |
73 | /// |
74 | /// The default implementation ignores <built-in> and system files. |
75 | virtual bool sawDependency(StringRef Filename, bool FromModule, |
76 | bool IsSystem, bool IsModuleFile, bool IsMissing); |
77 | |
78 | /// Called when the end of the main file is reached. |
79 | virtual void finishedMainFile(DiagnosticsEngine &Diags) {} |
80 | |
81 | /// Return true if system files should be passed to sawDependency(). |
82 | virtual bool needSystemDependencies() { return false; } |
83 | |
84 | /// Add a dependency \p Filename if it has not been seen before and |
85 | /// sawDependency() returns true. |
86 | virtual void maybeAddDependency(StringRef Filename, bool FromModule, |
87 | bool IsSystem, bool IsModuleFile, |
88 | bool IsMissing); |
89 | |
90 | protected: |
91 | /// Return true if the filename was added to the list of dependencies, false |
92 | /// otherwise. |
93 | bool addDependency(StringRef Filename); |
94 | |
95 | private: |
96 | llvm::StringSet<> Seen; |
97 | std::vector<std::string> Dependencies; |
98 | }; |
99 | |
100 | /// Builds a dependency file when attached to a Preprocessor (for includes) and |
101 | /// ASTReader (for module imports), and writes it out at the end of processing |
102 | /// a source file. Users should attach to the ast reader whenever a module is |
103 | /// loaded. |
104 | class DependencyFileGenerator : public DependencyCollector { |
105 | public: |
106 | DependencyFileGenerator(const DependencyOutputOptions &Opts); |
107 | |
108 | void attachToPreprocessor(Preprocessor &PP) override; |
109 | |
110 | void finishedMainFile(DiagnosticsEngine &Diags) override; |
111 | |
112 | bool needSystemDependencies() final { return IncludeSystemHeaders; } |
113 | |
114 | bool sawDependency(StringRef Filename, bool FromModule, bool IsSystem, |
115 | bool IsModuleFile, bool IsMissing) final; |
116 | |
117 | protected: |
118 | void outputDependencyFile(llvm::raw_ostream &OS); |
119 | |
120 | private: |
121 | void outputDependencyFile(DiagnosticsEngine &Diags); |
122 | |
123 | std::string OutputFile; |
124 | std::vector<std::string> Targets; |
125 | bool ; |
126 | bool PhonyTarget; |
127 | bool ; |
128 | bool ; |
129 | bool IncludeModuleFiles; |
130 | DependencyOutputFormat OutputFormat; |
131 | unsigned InputFileIndex; |
132 | }; |
133 | |
134 | /// Collects the dependencies for imported modules into a directory. Users |
135 | /// should attach to the AST reader whenever a module is loaded. |
136 | class ModuleDependencyCollector : public DependencyCollector { |
137 | std::string DestDir; |
138 | bool HasErrors = false; |
139 | llvm::StringSet<> Seen; |
140 | llvm::vfs::YAMLVFSWriter VFSWriter; |
141 | llvm::FileCollector::PathCanonicalizer Canonicalizer; |
142 | |
143 | std::error_code copyToRoot(StringRef Src, StringRef Dst = {}); |
144 | |
145 | public: |
146 | ModuleDependencyCollector(std::string DestDir) |
147 | : DestDir(std::move(DestDir)) {} |
148 | ~ModuleDependencyCollector() override { writeFileMap(); } |
149 | |
150 | StringRef getDest() { return DestDir; } |
151 | virtual bool insertSeen(StringRef Filename) { return Seen.insert(key: Filename).second; } |
152 | virtual void addFile(StringRef Filename, StringRef FileDst = {}); |
153 | |
154 | virtual void addFileMapping(StringRef VPath, StringRef RPath) { |
155 | VFSWriter.addFileMapping(VirtualPath: VPath, RealPath: RPath); |
156 | } |
157 | |
158 | void attachToPreprocessor(Preprocessor &PP) override; |
159 | void attachToASTReader(ASTReader &R) override; |
160 | |
161 | virtual void writeFileMap(); |
162 | virtual bool hasErrors() { return HasErrors; } |
163 | }; |
164 | |
165 | /// AttachDependencyGraphGen - Create a dependency graph generator, and attach |
166 | /// it to the given preprocessor. |
167 | void AttachDependencyGraphGen(Preprocessor &PP, StringRef OutputFile, |
168 | StringRef SysRoot); |
169 | |
170 | /// AttachHeaderIncludeGen - Create a header include list generator, and attach |
171 | /// it to the given preprocessor. |
172 | /// |
173 | /// \param DepOpts - Options controlling the output. |
174 | /// \param ShowAllHeaders - If true, show all header information instead of just |
175 | /// headers following the predefines buffer. This is useful for making sure |
176 | /// includes mentioned on the command line are also reported, but differs from |
177 | /// the default behavior used by -H. |
178 | /// \param OutputPath - If non-empty, a path to write the header include |
179 | /// information to, instead of writing to stderr. |
180 | /// \param ShowDepth - Whether to indent to show the nesting of the includes. |
181 | /// \param MSStyle - Whether to print in cl.exe /showIncludes style. |
182 | void (Preprocessor &PP, |
183 | const DependencyOutputOptions &DepOpts, |
184 | bool = false, |
185 | StringRef OutputPath = {}, |
186 | bool ShowDepth = true, bool MSStyle = false); |
187 | |
188 | /// The ChainedIncludesSource class converts headers to chained PCHs in |
189 | /// memory, mainly for testing. |
190 | IntrusiveRefCntPtr<ExternalSemaSource> |
191 | createChainedIncludesSource(CompilerInstance &CI, |
192 | IntrusiveRefCntPtr<ExternalSemaSource> &Reader); |
193 | |
194 | /// Optional inputs to createInvocation. |
195 | struct CreateInvocationOptions { |
196 | /// Receives diagnostics encountered while parsing command-line flags. |
197 | /// If not provided, these are printed to stderr. |
198 | IntrusiveRefCntPtr<DiagnosticsEngine> Diags = nullptr; |
199 | /// Used e.g. to probe for system headers locations. |
200 | /// If not provided, the real filesystem is used. |
201 | /// FIXME: the driver does perform some non-virtualized IO. |
202 | IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS = nullptr; |
203 | /// Whether to attempt to produce a non-null (possibly incorrect) invocation |
204 | /// if any errors were encountered. |
205 | /// By default, always return null on errors. |
206 | bool RecoverOnError = false; |
207 | /// Allow the driver to probe the filesystem for PCH files. |
208 | /// This is used to replace -include with -include-pch in the cc1 args. |
209 | /// FIXME: ProbePrecompiled=true is a poor, historical default. |
210 | /// It misbehaves if the PCH file is from GCC, has the wrong version, etc. |
211 | bool ProbePrecompiled = false; |
212 | /// If set, the target is populated with the cc1 args produced by the driver. |
213 | /// This may be populated even if createInvocation returns nullptr. |
214 | std::vector<std::string> *CC1Args = nullptr; |
215 | }; |
216 | |
217 | /// Interpret clang arguments in preparation to parse a file. |
218 | /// |
219 | /// This simulates a number of steps Clang takes when its driver is invoked: |
220 | /// - choosing actions (e.g compile + link) to run |
221 | /// - probing the system for settings like standard library locations |
222 | /// - spawning a cc1 subprocess to compile code, with more explicit arguments |
223 | /// - in the cc1 process, assembling those arguments into a CompilerInvocation |
224 | /// which is used to configure the parser |
225 | /// |
226 | /// This simulation is lossy, e.g. in some situations one driver run would |
227 | /// result in multiple parses. (Multi-arch, CUDA, ...). |
228 | /// This function tries to select a reasonable invocation that tools should use. |
229 | /// |
230 | /// Args[0] should be the driver name, such as "clang" or "/usr/bin/g++". |
231 | /// Absolute path is preferred - this affects searching for system headers. |
232 | /// |
233 | /// May return nullptr if an invocation could not be determined. |
234 | /// See CreateInvocationOptions::ShouldRecoverOnErrors to try harder! |
235 | std::unique_ptr<CompilerInvocation> |
236 | createInvocation(ArrayRef<const char *> Args, |
237 | CreateInvocationOptions Opts = {}); |
238 | |
239 | } // namespace clang |
240 | |
241 | #endif // LLVM_CLANG_FRONTEND_UTILS_H |
242 | |