clang 19.0.0git
Utils.h
Go to the documentation of this file.
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
17#include "clang/Basic/LLVM.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
34namespace clang {
35
36class ASTReader;
37class CompilerInstance;
38class CompilerInvocation;
39class DiagnosticsEngine;
40class ExternalSemaSource;
41class FrontendOptions;
42class PCHContainerReader;
43class Preprocessor;
44class PreprocessorOptions;
45class PreprocessorOutputOptions;
46class CodeGenOptions;
47
48/// InitializePreprocessor - Initialize the preprocessor getting it and the
49/// environment ready to process a single file.
50void InitializePreprocessor(Preprocessor &PP, const PreprocessorOptions &PPOpts,
51 const PCHContainerReader &PCHContainerRdr,
52 const FrontendOptions &FEOpts,
53 const CodeGenOptions &CodeGenOpts);
54
55/// DoPrintPreprocessedInput - Implement -E mode.
56void 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.
64public:
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
90protected:
91 /// Return true if the filename was added to the list of dependencies, false
92 /// otherwise.
93 bool addDependency(StringRef Filename);
94
95private:
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.
105public:
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
117protected:
118 void outputDependencyFile(llvm::raw_ostream &OS);
119
120private:
122
123 std::string OutputFile;
124 std::vector<std::string> Targets;
125 bool IncludeSystemHeaders;
126 bool PhonyTarget;
127 bool AddMissingHeaderDeps;
128 bool SeenMissingHeader;
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.
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
145public:
146 ModuleDependencyCollector(std::string DestDir)
147 : DestDir(std::move(DestDir)) {}
149
150 StringRef getDest() { return DestDir; }
151 virtual bool insertSeen(StringRef Filename) { return Seen.insert(Filename).second; }
152 virtual void addFile(StringRef Filename, StringRef FileDst = {});
153
154 virtual void addFileMapping(StringRef VPath, StringRef RPath) {
155 VFSWriter.addFileMapping(VPath, 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.
167void 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.
182void AttachHeaderIncludeGen(Preprocessor &PP,
183 const DependencyOutputOptions &DepOpts,
184 bool ShowAllHeaders = 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.
190IntrusiveRefCntPtr<ExternalSemaSource>
191createChainedIncludesSource(CompilerInstance &CI,
192 IntrusiveRefCntPtr<ExternalSemaSource> &Reader);
193
194/// Optional inputs to createInvocation.
196 /// Receives diagnostics encountered while parsing command-line flags.
197 /// If not provided, these are printed to stderr.
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.
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!
235std::unique_ptr<CompilerInvocation>
237 CreateInvocationOptions Opts = {});
238
239} // namespace clang
240
241#endif // LLVM_CLANG_FRONTEND_UTILS_H
Defines the Diagnostic-related interfaces.
StringRef Filename
Definition: Format.cpp:2975
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified.
Reads an AST files chain containing the contents of a translation unit.
Definition: ASTReader.h:366
An interface for collecting the dependencies of a compilation.
Definition: Utils.h:63
virtual void maybeAddDependency(StringRef Filename, bool FromModule, bool IsSystem, bool IsModuleFile, bool IsMissing)
Add a dependency Filename if it has not been seen before and sawDependency() returns true.
bool addDependency(StringRef Filename)
Return true if the filename was added to the list of dependencies, false otherwise.
virtual void attachToPreprocessor(Preprocessor &PP)
ArrayRef< std::string > getDependencies() const
Definition: Utils.h:69
virtual void finishedMainFile(DiagnosticsEngine &Diags)
Called when the end of the main file is reached.
Definition: Utils.h:79
virtual void attachToASTReader(ASTReader &R)
virtual bool needSystemDependencies()
Return true if system files should be passed to sawDependency().
Definition: Utils.h:82
virtual bool sawDependency(StringRef Filename, bool FromModule, bool IsSystem, bool IsModuleFile, bool IsMissing)
Called when a new file is seen.
Builds a dependency file when attached to a Preprocessor (for includes) and ASTReader (for module imp...
Definition: Utils.h:104
void outputDependencyFile(llvm::raw_ostream &OS)
void attachToPreprocessor(Preprocessor &PP) override
void finishedMainFile(DiagnosticsEngine &Diags) override
Called when the end of the main file is reached.
bool needSystemDependencies() final
Return true if system files should be passed to sawDependency().
Definition: Utils.h:112
bool sawDependency(StringRef Filename, bool FromModule, bool IsSystem, bool IsModuleFile, bool IsMissing) final
Called when a new file is seen.
DependencyOutputOptions - Options for controlling the compiler dependency file generation.
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:192
Collects the dependencies for imported modules into a directory.
Definition: Utils.h:136
void attachToASTReader(ASTReader &R) override
~ModuleDependencyCollector() override
Definition: Utils.h:148
virtual void addFileMapping(StringRef VPath, StringRef RPath)
Definition: Utils.h:154
void attachToPreprocessor(Preprocessor &PP) override
virtual void addFile(StringRef Filename, StringRef FileDst={})
virtual bool insertSeen(StringRef Filename)
Definition: Utils.h:151
ModuleDependencyCollector(std::string DestDir)
Definition: Utils.h:146
virtual bool hasErrors()
Definition: Utils.h:162
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:128
The JSON file list parser is used to communicate input to InstallAPI.
void InitializePreprocessor(Preprocessor &PP, const PreprocessorOptions &PPOpts, const PCHContainerReader &PCHContainerRdr, const FrontendOptions &FEOpts, const CodeGenOptions &CodeGenOpts)
InitializePreprocessor - Initialize the preprocessor getting it and the environment ready to process ...
IntrusiveRefCntPtr< ExternalSemaSource > createChainedIncludesSource(CompilerInstance &CI, IntrusiveRefCntPtr< ExternalSemaSource > &Reader)
The ChainedIncludesSource class converts headers to chained PCHs in memory, mainly for testing.
std::unique_ptr< CompilerInvocation > createInvocation(ArrayRef< const char * > Args, CreateInvocationOptions Opts={})
Interpret clang arguments in preparation to parse a file.
void DoPrintPreprocessedInput(Preprocessor &PP, raw_ostream *OS, const PreprocessorOutputOptions &Opts)
DoPrintPreprocessedInput - Implement -E mode.
DependencyOutputFormat
DependencyOutputFormat - Format for the compiler dependency file.
void AttachHeaderIncludeGen(Preprocessor &PP, const DependencyOutputOptions &DepOpts, bool ShowAllHeaders=false, StringRef OutputPath={}, bool ShowDepth=true, bool MSStyle=false)
AttachHeaderIncludeGen - Create a header include list generator, and attach it to the given preproces...
void AttachDependencyGraphGen(Preprocessor &PP, StringRef OutputFile, StringRef SysRoot)
AttachDependencyGraphGen - Create a dependency graph generator, and attach it to the given preprocess...
Definition: Format.h:5427
Optional inputs to createInvocation.
Definition: Utils.h:195
IntrusiveRefCntPtr< DiagnosticsEngine > Diags
Receives diagnostics encountered while parsing command-line flags.
Definition: Utils.h:198
bool ProbePrecompiled
Allow the driver to probe the filesystem for PCH files.
Definition: Utils.h:211
bool RecoverOnError
Whether to attempt to produce a non-null (possibly incorrect) invocation if any errors were encounter...
Definition: Utils.h:206
IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS
Used e.g.
Definition: Utils.h:202
std::vector< std::string > * CC1Args
If set, the target is populated with the cc1 args produced by the driver.
Definition: Utils.h:214