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