clang 20.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
124 std::string OutputFile;
125 std::vector<std::string> Targets;
126 bool IncludeSystemHeaders;
127 bool PhonyTarget;
128 bool AddMissingHeaderDeps;
129 bool SeenMissingHeader;
130 bool IncludeModuleFiles;
131 DependencyOutputFormat OutputFormat;
132 unsigned InputFileIndex;
133};
134
135/// Collects the dependencies for imported modules into a directory. Users
136/// should attach to the AST reader whenever a module is loaded.
138 std::string DestDir;
139 bool HasErrors = false;
140 llvm::StringSet<> Seen;
141 llvm::vfs::YAMLVFSWriter VFSWriter;
142 llvm::FileCollector::PathCanonicalizer Canonicalizer;
143
144 std::error_code copyToRoot(StringRef Src, StringRef Dst = {});
145
146public:
147 ModuleDependencyCollector(std::string DestDir)
148 : DestDir(std::move(DestDir)) {}
150
151 StringRef getDest() { return DestDir; }
152 virtual bool insertSeen(StringRef Filename) { return Seen.insert(Filename).second; }
153 virtual void addFile(StringRef Filename, StringRef FileDst = {});
154
155 virtual void addFileMapping(StringRef VPath, StringRef RPath) {
156 VFSWriter.addFileMapping(VPath, RPath);
157 }
158
159 void attachToPreprocessor(Preprocessor &PP) override;
160 void attachToASTReader(ASTReader &R) override;
161
162 virtual void writeFileMap();
163 virtual bool hasErrors() { return HasErrors; }
164};
165
166/// AttachDependencyGraphGen - Create a dependency graph generator, and attach
167/// it to the given preprocessor.
168void AttachDependencyGraphGen(Preprocessor &PP, StringRef OutputFile,
169 StringRef SysRoot);
170
171/// AttachHeaderIncludeGen - Create a header include list generator, and attach
172/// it to the given preprocessor.
173///
174/// \param DepOpts - Options controlling the output.
175/// \param ShowAllHeaders - If true, show all header information instead of just
176/// headers following the predefines buffer. This is useful for making sure
177/// includes mentioned on the command line are also reported, but differs from
178/// the default behavior used by -H.
179/// \param OutputPath - If non-empty, a path to write the header include
180/// information to, instead of writing to stderr.
181/// \param ShowDepth - Whether to indent to show the nesting of the includes.
182/// \param MSStyle - Whether to print in cl.exe /showIncludes style.
183void AttachHeaderIncludeGen(Preprocessor &PP,
184 const DependencyOutputOptions &DepOpts,
185 bool ShowAllHeaders = false,
186 StringRef OutputPath = {},
187 bool ShowDepth = true, bool MSStyle = false);
188
189/// The ChainedIncludesSource class converts headers to chained PCHs in
190/// memory, mainly for testing.
191IntrusiveRefCntPtr<ExternalSemaSource>
192createChainedIncludesSource(CompilerInstance &CI,
193 IntrusiveRefCntPtr<ExternalSemaSource> &Reader);
194
195/// Optional inputs to createInvocation.
197 /// Receives diagnostics encountered while parsing command-line flags.
198 /// If not provided, these are printed to stderr.
200 /// Used e.g. to probe for system headers locations.
201 /// If not provided, the real filesystem is used.
202 /// FIXME: the driver does perform some non-virtualized IO.
204 /// Whether to attempt to produce a non-null (possibly incorrect) invocation
205 /// if any errors were encountered.
206 /// By default, always return null on errors.
207 bool RecoverOnError = false;
208 /// Allow the driver to probe the filesystem for PCH files.
209 /// This is used to replace -include with -include-pch in the cc1 args.
210 /// FIXME: ProbePrecompiled=true is a poor, historical default.
211 /// It misbehaves if the PCH file is from GCC, has the wrong version, etc.
212 bool ProbePrecompiled = false;
213 /// If set, the target is populated with the cc1 args produced by the driver.
214 /// This may be populated even if createInvocation returns nullptr.
215 std::vector<std::string> *CC1Args = nullptr;
216};
217
218/// Interpret clang arguments in preparation to parse a file.
219///
220/// This simulates a number of steps Clang takes when its driver is invoked:
221/// - choosing actions (e.g compile + link) to run
222/// - probing the system for settings like standard library locations
223/// - spawning a cc1 subprocess to compile code, with more explicit arguments
224/// - in the cc1 process, assembling those arguments into a CompilerInvocation
225/// which is used to configure the parser
226///
227/// This simulation is lossy, e.g. in some situations one driver run would
228/// result in multiple parses. (Multi-arch, CUDA, ...).
229/// This function tries to select a reasonable invocation that tools should use.
230///
231/// Args[0] should be the driver name, such as "clang" or "/usr/bin/g++".
232/// Absolute path is preferred - this affects searching for system headers.
233///
234/// May return nullptr if an invocation could not be determined.
235/// See CreateInvocationOptions::ShouldRecoverOnErrors to try harder!
236std::unique_ptr<CompilerInvocation>
238 CreateInvocationOptions Opts = {});
239
240} // namespace clang
241
242#endif // LLVM_CLANG_FRONTEND_UTILS_H
Defines the Diagnostic-related interfaces.
StringRef Filename
Definition: Format.cpp:3051
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:383
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:231
Collects the dependencies for imported modules into a directory.
Definition: Utils.h:137
void attachToASTReader(ASTReader &R) override
~ModuleDependencyCollector() override
Definition: Utils.h:149
virtual void addFileMapping(StringRef VPath, StringRef RPath)
Definition: Utils.h:155
void attachToPreprocessor(Preprocessor &PP) override
virtual void addFile(StringRef Filename, StringRef FileDst={})
virtual bool insertSeen(StringRef Filename)
Definition: Utils.h:152
ModuleDependencyCollector(std::string DestDir)
Definition: Utils.h:147
virtual bool hasErrors()
Definition: Utils.h:163
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:138
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...
Optional inputs to createInvocation.
Definition: Utils.h:196
IntrusiveRefCntPtr< DiagnosticsEngine > Diags
Receives diagnostics encountered while parsing command-line flags.
Definition: Utils.h:199
bool ProbePrecompiled
Allow the driver to probe the filesystem for PCH files.
Definition: Utils.h:212
bool RecoverOnError
Whether to attempt to produce a non-null (possibly incorrect) invocation if any errors were encounter...
Definition: Utils.h:207
IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS
Used e.g.
Definition: Utils.h:203
std::vector< std::string > * CC1Args
If set, the target is populated with the cc1 args produced by the driver.
Definition: Utils.h:215