clang  16.0.0git
Job.h
Go to the documentation of this file.
1 //===- Job.h - Commands to Execute ------------------------------*- 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 #ifndef LLVM_CLANG_DRIVER_JOB_H
10 #define LLVM_CLANG_DRIVER_JOB_H
11 
12 #include "clang/Basic/LLVM.h"
13 #include "clang/Driver/InputInfo.h"
14 #include "llvm/ADT/ArrayRef.h"
15 #include "llvm/ADT/Optional.h"
16 #include "llvm/ADT/SmallVector.h"
17 #include "llvm/ADT/StringRef.h"
18 #include "llvm/ADT/iterator.h"
19 #include "llvm/Option/Option.h"
20 #include "llvm/Support/Program.h"
21 #include <memory>
22 #include <string>
23 #include <utility>
24 #include <vector>
25 
26 namespace clang {
27 namespace driver {
28 
29 class Action;
30 class InputInfo;
31 class Tool;
32 
34  StringRef Filename;
35  StringRef VFSPath;
36 
37  CrashReportInfo(StringRef Filename, StringRef VFSPath)
39 };
40 
41 // Encodes the kind of response file supported for a command invocation.
42 // Response files are necessary if the command line gets too large, requiring
43 // the arguments to be transferred to a file.
46  // Provides full support for response files, which means we can transfer
47  // all tool input arguments to a file.
49  // Input file names can live in a file, but flags can't. This is a special
50  // case for old versions of Apple's ld64.
52  // Does not support response files: all arguments must be passed via
53  // command line.
55  };
56  /// The level of support for response files.
58 
59  /// The encoding to use when writing response files on Windows. Ignored on
60  /// other host OSes.
61  ///
62  /// Windows use cases: - GCC and Binutils on mingw only accept ANSI response
63  /// files encoded with the system current code page.
64  /// - MSVC's CL.exe and LINK.exe accept UTF16 on Windows.
65  /// - Clang accepts both UTF8 and UTF16.
66  ///
67  /// FIXME: When GNU tools learn how to parse UTF16 on Windows, we should
68  /// always use UTF16 for Windows, which is the Windows official encoding for
69  /// international characters.
70  llvm::sys::WindowsEncodingMethod ResponseEncoding;
71 
72  /// What prefix to use for the command-line argument when passing a response
73  /// file.
74  const char *ResponseFlag;
75 
76  /// Returns a ResponseFileSupport indicating that response files are not
77  /// supported.
78  static constexpr ResponseFileSupport None() {
79  return {RF_None, llvm::sys::WEM_UTF8, nullptr};
80  }
81 
82  /// Returns a ResponseFileSupport indicating that response files are
83  /// supported, using the @file syntax. On windows, the file is written in the
84  /// UTF8 encoding. On other OSes, no re-encoding occurs.
85  static constexpr ResponseFileSupport AtFileUTF8() {
86  return {RF_Full, llvm::sys::WEM_UTF8, "@"};
87  }
88 
89  /// Returns a ResponseFileSupport indicating that response files are
90  /// supported, using the @file syntax. On windows, the file is written in the
91  /// current ANSI code-page encoding. On other OSes, no re-encoding occurs.
92  static constexpr ResponseFileSupport AtFileCurCP() {
93  return {RF_Full, llvm::sys::WEM_CurrentCodePage, "@"};
94  }
95 
96  /// Returns a ResponseFileSupport indicating that response files are
97  /// supported, using the @file syntax. On windows, the file is written in the
98  /// UTF-16 encoding. On other OSes, no re-encoding occurs.
99  static constexpr ResponseFileSupport AtFileUTF16() {
100  return {RF_Full, llvm::sys::WEM_UTF16, "@"};
101  }
102 };
103 
104 /// Command - An executable path/name and argument vector to
105 /// execute.
106 class Command {
107  /// Source - The action which caused the creation of this job.
108  const Action &Source;
109 
110  /// Tool - The tool which caused the creation of this job.
111  const Tool &Creator;
112 
113  /// Whether and how to generate response files if the arguments are too long.
114  ResponseFileSupport ResponseSupport;
115 
116  /// The executable to run.
117  const char *Executable;
118 
119  /// The list of program arguments (not including the implicit first
120  /// argument, which will be the executable).
121  llvm::opt::ArgStringList Arguments;
122 
123  /// The list of program inputs.
124  std::vector<InputInfo> InputInfoList;
125 
126  /// The list of program arguments which are outputs. May be empty.
127  std::vector<std::string> OutputFilenames;
128 
129  /// Response file name, if this command is set to use one, or nullptr
130  /// otherwise
131  const char *ResponseFile = nullptr;
132 
133  /// The input file list in case we need to emit a file list instead of a
134  /// proper response file
135  llvm::opt::ArgStringList InputFileList;
136 
137  /// String storage if we need to create a new argument to specify a response
138  /// file
139  std::string ResponseFileFlag;
140 
141  /// See Command::setEnvironment
142  std::vector<const char *> Environment;
143 
144  /// Optional redirection for stdin, stdout, stderr.
145  std::vector<Optional<std::string>> RedirectFiles;
146 
147  /// Information on executable run provided by OS.
149 
150  /// When a response file is needed, we try to put most arguments in an
151  /// exclusive file, while others remains as regular command line arguments.
152  /// This functions fills a vector with the regular command line arguments,
153  /// argv, excluding the ones passed in a response file.
154  void buildArgvForResponseFile(llvm::SmallVectorImpl<const char *> &Out) const;
155 
156  /// Encodes an array of C strings into a single string separated by whitespace.
157  /// This function will also put in quotes arguments that have whitespaces and
158  /// will escape the regular backslashes (used in Windows paths) and quotes.
159  /// The results are the contents of a response file, written into a raw_ostream.
160  void writeResponseFile(raw_ostream &OS) const;
161 
162 public:
163  /// Whether to print the input filenames when executing.
164  bool PrintInputFilenames = false;
165 
166  /// Whether the command will be executed in this process or not.
167  bool InProcess = false;
168 
169  Command(const Action &Source, const Tool &Creator,
170  ResponseFileSupport ResponseSupport, const char *Executable,
171  const llvm::opt::ArgStringList &Arguments, ArrayRef<InputInfo> Inputs,
172  ArrayRef<InputInfo> Outputs = None);
173  // FIXME: This really shouldn't be copyable, but is currently copied in some
174  // error handling in Driver::generateCompilationDiagnostics.
175  Command(const Command &) = default;
176  virtual ~Command() = default;
177 
178  virtual void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote,
179  CrashReportInfo *CrashInfo = nullptr) const;
180 
181  virtual int Execute(ArrayRef<Optional<StringRef>> Redirects,
182  std::string *ErrMsg, bool *ExecutionFailed) const;
183 
184  /// getSource - Return the Action which caused the creation of this job.
185  const Action &getSource() const { return Source; }
186 
187  /// getCreator - Return the Tool which caused the creation of this job.
188  const Tool &getCreator() const { return Creator; }
189 
190  /// Returns the kind of response file supported by the current invocation.
192  return ResponseSupport;
193  }
194 
195  /// Set to pass arguments via a response file when launching the command
196  void setResponseFile(const char *FileName);
197 
198  /// Set an input file list, necessary if you specified an RF_FileList response
199  /// file support.
200  void setInputFileList(llvm::opt::ArgStringList List) {
201  InputFileList = std::move(List);
202  }
203 
204  /// Sets the environment to be used by the new process.
205  /// \param NewEnvironment An array of environment variables.
206  /// \remark If the environment remains unset, then the environment
207  /// from the parent process will be used.
208  virtual void setEnvironment(llvm::ArrayRef<const char *> NewEnvironment);
209 
210  void setRedirectFiles(const std::vector<Optional<std::string>> &Redirects);
211 
212  void replaceArguments(llvm::opt::ArgStringList List) {
213  Arguments = std::move(List);
214  }
215 
216  void replaceExecutable(const char *Exe) { Executable = Exe; }
217 
218  const char *getExecutable() const { return Executable; }
219 
220  const llvm::opt::ArgStringList &getArguments() const { return Arguments; }
221 
222  const std::vector<InputInfo> &getInputInfos() const { return InputInfoList; }
223 
224  const std::vector<std::string> &getOutputFilenames() const {
225  return OutputFilenames;
226  }
227 
229  return ProcStat;
230  }
231 
232 protected:
233  /// Optionally print the filenames to be compiled
234  void PrintFileNames() const;
235 };
236 
237 /// Use the CC1 tool callback when available, to avoid creating a new process
238 class CC1Command : public Command {
239 public:
240  CC1Command(const Action &Source, const Tool &Creator,
241  ResponseFileSupport ResponseSupport, const char *Executable,
242  const llvm::opt::ArgStringList &Arguments,
243  ArrayRef<InputInfo> Inputs, ArrayRef<InputInfo> Outputs = None);
244 
245  void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote,
246  CrashReportInfo *CrashInfo = nullptr) const override;
247 
248  int Execute(ArrayRef<Optional<StringRef>> Redirects, std::string *ErrMsg,
249  bool *ExecutionFailed) const override;
250 
251  void setEnvironment(llvm::ArrayRef<const char *> NewEnvironment) override;
252 };
253 
254 /// Like Command, but always pretends that the wrapped command succeeded.
255 class ForceSuccessCommand : public Command {
256 public:
257  ForceSuccessCommand(const Action &Source_, const Tool &Creator_,
258  ResponseFileSupport ResponseSupport,
259  const char *Executable_,
260  const llvm::opt::ArgStringList &Arguments_,
261  ArrayRef<InputInfo> Inputs,
262  ArrayRef<InputInfo> Outputs = None);
263 
264  void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote,
265  CrashReportInfo *CrashInfo = nullptr) const override;
266 
267  int Execute(ArrayRef<Optional<StringRef>> Redirects, std::string *ErrMsg,
268  bool *ExecutionFailed) const override;
269 };
270 
271 /// JobList - A sequence of jobs to perform.
272 class JobList {
273 public:
275  using size_type = list_type::size_type;
276  using iterator = llvm::pointee_iterator<list_type::iterator>;
277  using const_iterator = llvm::pointee_iterator<list_type::const_iterator>;
278 
279 private:
280  list_type Jobs;
281 
282 public:
283  void Print(llvm::raw_ostream &OS, const char *Terminator,
284  bool Quote, CrashReportInfo *CrashInfo = nullptr) const;
285 
286  /// Add a job to the list (taking ownership).
287  void addJob(std::unique_ptr<Command> J) { Jobs.push_back(std::move(J)); }
288 
289  /// Clear the job list.
290  void clear();
291 
292  const list_type &getJobs() const { return Jobs; }
293 
294  bool empty() const { return Jobs.empty(); }
295  size_type size() const { return Jobs.size(); }
296  iterator begin() { return Jobs.begin(); }
297  const_iterator begin() const { return Jobs.begin(); }
298  iterator end() { return Jobs.end(); }
299  const_iterator end() const { return Jobs.end(); }
300 };
301 
302 } // namespace driver
303 } // namespace clang
304 
305 #endif // LLVM_CLANG_DRIVER_JOB_H
clang::driver::ResponseFileSupport::AtFileUTF16
static constexpr ResponseFileSupport AtFileUTF16()
Definition: Job.h:99
clang::driver::ResponseFileSupport::RF_Full
@ RF_Full
Definition: Job.h:48
clang::driver::Command::Command
Command(const Action &Source, const Tool &Creator, ResponseFileSupport ResponseSupport, const char *Executable, const llvm::opt::ArgStringList &Arguments, ArrayRef< InputInfo > Inputs, ArrayRef< InputInfo > Outputs=None)
Definition: Job.cpp:38
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition: CMakeLists.txt:22
clang::driver::ResponseFileSupport::AtFileUTF8
static constexpr ResponseFileSupport AtFileUTF8()
Definition: Job.h:85
clang::driver::JobList::empty
bool empty() const
Definition: Job.h:294
clang::driver::Command::PrintInputFilenames
bool PrintInputFilenames
Whether to print the input filenames when executing.
Definition: Job.h:164
llvm::SmallVector
Definition: LLVM.h:38
clang::driver::Action
Action - Represent an abstract compilation step to perform.
Definition: Action.h:47
clang::driver::Command::setRedirectFiles
void setRedirectFiles(const std::vector< Optional< std::string >> &Redirects)
Definition: Job.cpp:304
clang::driver::JobList::begin
iterator begin()
Definition: Job.h:296
clang::driver::Command::replaceArguments
void replaceArguments(llvm::opt::ArgStringList List)
Definition: Job.h:212
clang::driver::JobList::Print
void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote, CrashReportInfo *CrashInfo=nullptr) const
Definition: Job.cpp:465
clang::driver::Command::getProcessStatistics
Optional< llvm::sys::ProcessStatistics > getProcessStatistics() const
Definition: Job.h:228
clang::driver::CC1Command
Use the CC1 tool callback when available, to avoid creating a new process.
Definition: Job.h:238
clang::driver::Command::Execute
virtual int Execute(ArrayRef< Optional< StringRef >> Redirects, std::string *ErrMsg, bool *ExecutionFailed) const
Definition: Job.cpp:317
clang::driver::JobList::getJobs
const list_type & getJobs() const
Definition: Job.h:292
clang::driver::CC1Command::Execute
int Execute(ArrayRef< Optional< StringRef >> Redirects, std::string *ErrMsg, bool *ExecutionFailed) const override
Definition: Job.cpp:398
llvm::Optional< llvm::sys::ProcessStatistics >
clang::driver::CrashReportInfo
Definition: Job.h:33
clang::driver::CC1Command::Print
void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote, CrashReportInfo *CrashInfo=nullptr) const override
Definition: Job.cpp:391
clang::driver::JobList::clear
void clear()
Clear the job list.
Definition: Job.cpp:471
clang::driver::JobList::end
iterator end()
Definition: Job.h:298
clang::driver::CC1Command::CC1Command
CC1Command(const Action &Source, const Tool &Creator, ResponseFileSupport ResponseSupport, const char *Executable, const llvm::opt::ArgStringList &Arguments, ArrayRef< InputInfo > Inputs, ArrayRef< InputInfo > Outputs=None)
Definition: Job.cpp:381
clang::driver::Command::InProcess
bool InProcess
Whether the command will be executed in this process or not.
Definition: Job.h:167
clang::driver::ResponseFileSupport::ResponseEncoding
llvm::sys::WindowsEncodingMethod ResponseEncoding
The encoding to use when writing response files on Windows.
Definition: Job.h:70
InputInfo.h
clang::driver::ResponseFileSupport::ResponseFileKind
ResponseFileKind
Definition: Job.h:45
clang::driver::Command::getResponseFileSupport
const ResponseFileSupport & getResponseFileSupport()
Returns the kind of response file supported by the current invocation.
Definition: Job.h:191
clang::driver::Tool
Tool - Information on a specific compilation tool.
Definition: Tool.h:32
clang::driver::JobList::const_iterator
llvm::pointee_iterator< list_type::const_iterator > const_iterator
Definition: Job.h:277
clang::driver::CrashReportInfo::CrashReportInfo
CrashReportInfo(StringRef Filename, StringRef VFSPath)
Definition: Job.h:37
clang::driver::Command::getCreator
const Tool & getCreator() const
getCreator - Return the Tool which caused the creation of this job.
Definition: Job.h:188
clang::driver::ResponseFileSupport::AtFileCurCP
static constexpr ResponseFileSupport AtFileCurCP()
Definition: Job.h:92
clang::driver::Command::PrintFileNames
void PrintFileNames() const
Optionally print the filenames to be compiled.
Definition: Job.cpp:309
clang::driver::ForceSuccessCommand
Like Command, but always pretends that the wrapped command succeeded.
Definition: Job.h:255
clang::driver::JobList
JobList - A sequence of jobs to perform.
Definition: Job.h:272
clang::driver::CrashReportInfo::Filename
StringRef Filename
Definition: Job.h:34
clang::driver::CC1Command::setEnvironment
void setEnvironment(llvm::ArrayRef< const char * > NewEnvironment) override
Sets the environment to be used by the new process.
Definition: Job.cpp:435
clang::driver::CrashReportInfo::VFSPath
StringRef VFSPath
Definition: Job.h:35
clang::driver::Command::getInputInfos
const std::vector< InputInfo > & getInputInfos() const
Definition: Job.h:222
clang::driver::Command::setInputFileList
void setInputFileList(llvm::opt::ArgStringList List)
Set an input file list, necessary if you specified an RF_FileList response file support.
Definition: Job.h:200
clang::driver::ResponseFileSupport::ResponseFlag
const char * ResponseFlag
What prefix to use for the command-line argument when passing a response file.
Definition: Job.h:74
clang::driver::ResponseFileSupport::ResponseKind
ResponseFileKind ResponseKind
The level of support for response files.
Definition: Job.h:57
clang::driver::Command
Command - An executable path/name and argument vector to execute.
Definition: Job.h:106
clang::driver::Command::getArguments
const llvm::opt::ArgStringList & getArguments() const
Definition: Job.h:220
clang::driver::JobList::size_type
list_type::size_type size_type
Definition: Job.h:275
clang::driver::ForceSuccessCommand::Print
void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote, CrashReportInfo *CrashInfo=nullptr) const override
Definition: Job.cpp:449
clang::driver::Command::getOutputFilenames
const std::vector< std::string > & getOutputFilenames() const
Definition: Job.h:224
llvm::ArrayRef
Definition: LLVM.h:34
clang::driver::JobList::size
size_type size() const
Definition: Job.h:295
LLVM.h
clang::driver::Command::setResponseFile
void setResponseFile(const char *FileName)
Set to pass arguments via a response file when launching the command.
Definition: Job.cpp:292
clang::driver::Command::getSource
const Action & getSource() const
getSource - Return the Action which caused the creation of this job.
Definition: Job.h:185
clang::driver::Command::getExecutable
const char * getExecutable() const
Definition: Job.h:218
clang::driver::JobList::iterator
llvm::pointee_iterator< list_type::iterator > iterator
Definition: Job.h:276
clang::driver::ResponseFileSupport::RF_None
@ RF_None
Definition: Job.h:54
clang::driver::JobList::addJob
void addJob(std::unique_ptr< Command > J)
Add a job to the list (taking ownership).
Definition: Job.h:287
clang::driver::JobList::end
const_iterator end() const
Definition: Job.h:299
clang::driver::Command::replaceExecutable
void replaceExecutable(const char *Exe)
Definition: Job.h:216
clang
Definition: CalledOnceCheck.h:17
clang::driver::JobList::begin
const_iterator begin() const
Definition: Job.h:297
clang::driver::Command::Print
virtual void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote, CrashReportInfo *CrashInfo=nullptr) const
Definition: Job.cpp:201
clang::driver::ForceSuccessCommand::ForceSuccessCommand
ForceSuccessCommand(const Action &Source_, const Tool &Creator_, ResponseFileSupport ResponseSupport, const char *Executable_, const llvm::opt::ArgStringList &Arguments_, ArrayRef< InputInfo > Inputs, ArrayRef< InputInfo > Outputs=None)
Definition: Job.cpp:441
clang::driver::Command::setEnvironment
virtual void setEnvironment(llvm::ArrayRef< const char * > NewEnvironment)
Sets the environment to be used by the new process.
Definition: Job.cpp:298
clang::driver::Command::~Command
virtual ~Command()=default
clang::driver::ResponseFileSupport::RF_FileList
@ RF_FileList
Definition: Job.h:51
llvm::SmallVectorImpl
Definition: Randstruct.h:18
clang::driver::ResponseFileSupport::None
static constexpr ResponseFileSupport None()
Returns a ResponseFileSupport indicating that response files are not supported.
Definition: Job.h:78
clang::driver::ForceSuccessCommand::Execute
int Execute(ArrayRef< Optional< StringRef >> Redirects, std::string *ErrMsg, bool *ExecutionFailed) const override
Definition: Job.cpp:455
clang::driver::ResponseFileSupport
Definition: Job.h:44