Job.h

Go to the documentation of this file.

//===- Job.h - Commands to Execute ------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_CLANG_DRIVER_JOB_H
#define LLVM_CLANG_DRIVER_JOB_H
 
#include "clang/Basic/LLVM.h"
#include "clang/Driver/InputInfo.h"
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/DenseMap.h"
#include "llvm/ADT/SmallVector.h"
#include "llvm/ADT/StringRef.h"
#include "llvm/ADT/iterator.h"
#include "llvm/Option/Option.h"
#include "llvm/Support/Program.h"
#include <memory>
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
namespace clang {
namespace driver {
 
class Action;
class InputInfo;
class Tool;
 
struct CrashReportInfo {
  StringRef Filename;
  StringRef VFSPath;
 
  CrashReportInfo(StringRef Filename, StringRef VFSPath)
      : Filename(Filename), VFSPath(VFSPath) {}
};
 
// Encodes the kind of response file supported for a command invocation.
// Response files are necessary if the command line gets too large, requiring
// the arguments to be transferred to a file.
struct ResponseFileSupport {
  enum ResponseFileKind {
    // Provides full support for response files, which means we can transfer
    // all tool input arguments to a file.
    RF_Full,
    // Input file names can live in a file, but flags can't. This is a special
    // case for old versions of Apple's ld64.
    RF_FileList,
    // Does not support response files: all arguments must be passed via
    // command line.
    RF_None
  };
  /// The level of support for response files.
  ResponseFileKind ResponseKind;
 
  /// The encoding to use when writing response files on Windows. Ignored on
  /// other host OSes.
  ///
  /// Windows use cases: - GCC and Binutils on mingw only accept ANSI response
  /// files encoded with the system current code page.
  /// - MSVC's CL.exe and LINK.exe accept UTF16 on Windows.
  /// - Clang accepts both UTF8 and UTF16.
  ///
  /// FIXME: When GNU tools learn how to parse UTF16 on Windows, we should
  /// always use UTF16 for Windows, which is the Windows official encoding for
  /// international characters.
  llvm::sys::WindowsEncodingMethod ResponseEncoding;
 
  /// What prefix to use for the command-line argument when passing a response
  /// file.
  const char *ResponseFlag;
 
  /// Returns a ResponseFileSupport indicating that response files are not
  /// supported.
  static constexpr ResponseFileSupport None() {
    return {RF_None, llvm::sys::WEM_UTF8, nullptr};
  }
 
  /// Returns a ResponseFileSupport indicating that response files are
  /// supported, using the @file syntax. On windows, the file is written in the
  /// UTF8 encoding. On other OSes, no re-encoding occurs.
  static constexpr ResponseFileSupport AtFileUTF8() {
    return {RF_Full, llvm::sys::WEM_UTF8, "@"};
  }
 
  /// Returns a ResponseFileSupport indicating that response files are
  /// supported, using the @file syntax. On windows, the file is written in the
  /// current ANSI code-page encoding. On other OSes, no re-encoding occurs.
  static constexpr ResponseFileSupport AtFileCurCP() {
    return {RF_Full, llvm::sys::WEM_CurrentCodePage, "@"};
  }
 
  /// Returns a ResponseFileSupport indicating that response files are
  /// supported, using the @file syntax. On windows, the file is written in the
  /// UTF-16 encoding. On other OSes, no re-encoding occurs.
  static constexpr ResponseFileSupport AtFileUTF16() {
    return {RF_Full, llvm::sys::WEM_UTF16, "@"};
  }
};
 
/// Command - An executable path/name and argument vector to
/// execute.
class Command {
public:
  using ErrorCodeDiagMapTy = llvm::DenseMap<int, std::string>;
  using ErrorCodeExitMapTy = llvm::DenseMap<int, bool>;
 
private:
  /// Source - The action which caused the creation of this job.
  const Action &Source;
 
  /// Tool - The tool which caused the creation of this job.
  const Tool &Creator;
 
  /// Whether and how to generate response files if the arguments are too long.
  ResponseFileSupport ResponseSupport;
 
  /// The executable to run.
  const char *Executable;
 
  /// The container for custom driver-set diagnostic messages that are
  /// produced upon particular error codes returned by the command.
  /// In order to add such a diagnostic for an external tool, consider the
  /// following criteria:
  /// 1) Does the command's executable return different codes upon different
  ///    types of errors?
  /// 2) If the executable provides a single error code for various error types,
  ///    is only a certain type of failure expected to occur within the driver
  ///    flow? E.g. the driver guarantees a valid input to the tool, so any
  ///    "invalid input" error can be ruled out
  ErrorCodeDiagMapTy ErrorCodeDiagMap;
 
  /// Similar to the container for the diagnostic messages, this container
  /// is used to signify if the toolchain should error and exit right away
  /// or if we should continue compilation.
  ErrorCodeExitMapTy ErrorCodeExitMap;
 
  /// Optional argument to prepend.
  const char *PrependArg;
 
  /// The list of program arguments (not including the implicit first
  /// argument, which will be the executable).
  llvm::opt::ArgStringList Arguments;
 
  /// The list of program inputs.
  std::vector<InputInfo> InputInfoList;
 
  /// The list of program arguments which are outputs. May be empty.
  std::vector<std::string> OutputFilenames;
 
  /// Response file name, if this command is set to use one, or nullptr
  /// otherwise
  const char *ResponseFile = nullptr;
 
  /// The input file list in case we need to emit a file list instead of a
  /// proper response file
  llvm::opt::ArgStringList InputFileList;
 
  /// String storage if we need to create a new argument to specify a response
  /// file
  std::string ResponseFileFlag;
 
  /// See Command::setEnvironment
  std::vector<const char *> Environment;
 
  /// Optional redirection for stdin, stdout, stderr.
  std::vector<std::optional<std::string>> RedirectFiles;
 
  /// Information on executable run provided by OS.
  mutable std::optional<llvm::sys::ProcessStatistics> ProcStat;
 
  /// When a response file is needed, we try to put most arguments in an
  /// exclusive file, while others remains as regular command line arguments.
  /// This functions fills a vector with the regular command line arguments,
  /// argv, excluding the ones passed in a response file.
  void buildArgvForResponseFile(llvm::SmallVectorImpl<const char *> &Out) const;
 
  /// Encodes an array of C strings into a single string separated by whitespace.
  /// This function will also put in quotes arguments that have whitespaces and
  /// will escape the regular backslashes (used in Windows paths) and quotes.
  /// The results are the contents of a response file, written into a raw_ostream.
  void writeResponseFile(raw_ostream &OS) const;
 
public:
  /// Whether to print the input filenames when executing.
  bool PrintInputFilenames = false;
 
  /// Whether the command will be executed in this process or not.
  bool InProcess = false;
 
  Command(const Action &Source, const Tool &Creator,
          ResponseFileSupport ResponseSupport, const char *Executable,
          const llvm::opt::ArgStringList &Arguments, ArrayRef<InputInfo> Inputs,
          ArrayRef<InputInfo> Outputs = std::nullopt,
          const char *PrependArg = nullptr);
  // FIXME: This really shouldn't be copyable, but is currently copied in some
  // error handling in Driver::generateCompilationDiagnostics.
  Command(const Command &) = default;
  virtual ~Command() = default;
 
  virtual void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote,
                     CrashReportInfo *CrashInfo = nullptr) const;
 
  virtual int Execute(ArrayRef<std::optional<StringRef>> Redirects,
                      std::string *ErrMsg, bool *ExecutionFailed) const;
 
  /// Store a custom driver diagnostic message upon a particular error code
  /// returned by the command
  void addDiagForErrorCode(int ErrorCode, StringRef CustomDiag);
 
  /// Store if the compilation should exit upon a particular error code
  /// returned by the command
  void addExitForErrorCode(int ErrorCode, bool Exit);
 
  /// Get the custom driver diagnostic message for a particular error code
  /// if such was stored. Returns an empty string if no diagnostic message
  /// was found for the given error code.
  StringRef getDiagForErrorCode(int ErrorCode) const;
 
  /// Will the tool exit when a particular error code is encountered. Returns
  /// true if not set (always exit)
  bool getWillExitForErrorCode(int ErrorCode) const;
 
  /// getSource - Return the Action which caused the creation of this job.
  const Action &getSource() const { return Source; }
 
  /// getCreator - Return the Tool which caused the creation of this job.
  const Tool &getCreator() const { return Creator; }
 
  /// Returns the kind of response file supported by the current invocation.
  const ResponseFileSupport &getResponseFileSupport() {
    return ResponseSupport;
  }
 
  /// Set to pass arguments via a response file when launching the command
  void setResponseFile(const char *FileName);
 
  /// Set an input file list, necessary if you specified an RF_FileList response
  /// file support.
  void setInputFileList(llvm::opt::ArgStringList List) {
    InputFileList = std::move(List);
  }
 
  /// Sets the environment to be used by the new process.
  /// \param NewEnvironment An array of environment variables.
  /// \remark If the environment remains unset, then the environment
  ///         from the parent process will be used.
  virtual void setEnvironment(llvm::ArrayRef<const char *> NewEnvironment);
 
  void
  setRedirectFiles(const std::vector<std::optional<std::string>> &Redirects);
 
  void replaceArguments(llvm::opt::ArgStringList List) {
    Arguments = std::move(List);
  }
 
  void replaceExecutable(const char *Exe) { Executable = Exe; }
 
  const char *getExecutable() const { return Executable; }
 
  const llvm::opt::ArgStringList &getArguments() const { return Arguments; }
 
  const std::vector<InputInfo> &getInputInfos() const { return InputInfoList; }
 
  const std::vector<std::string> &getOutputFilenames() const {
    return OutputFilenames;
  }
 
  std::optional<llvm::sys::ProcessStatistics> getProcessStatistics() const {
    return ProcStat;
  }
 
protected:
  /// Optionally print the filenames to be compiled
  void PrintFileNames() const;
};
 
/// Use the CC1 tool callback when available, to avoid creating a new process
class CC1Command : public Command {
public:
  CC1Command(const Action &Source, const Tool &Creator,
             ResponseFileSupport ResponseSupport, const char *Executable,
             const llvm::opt::ArgStringList &Arguments,
             ArrayRef<InputInfo> Inputs,
             ArrayRef<InputInfo> Outputs = std::nullopt,
             const char *PrependArg = nullptr);
 
  void Print(llvm::raw_ostream &OS, const char *Terminator, bool Quote,
             CrashReportInfo *CrashInfo = nullptr) const override;
 
  int Execute(ArrayRef<std::optional<StringRef>> Redirects, std::string *ErrMsg,
              bool *ExecutionFailed) const override;
 
  void setEnvironment(llvm::ArrayRef<const char *> NewEnvironment) override;
};
 
/// JobList - A sequence of jobs to perform.
class JobList {
public:
  using list_type = SmallVector<std::unique_ptr<Command>, 4>;
  using size_type = list_type::size_type;
  using iterator = llvm::pointee_iterator<list_type::iterator>;
  using const_iterator = llvm::pointee_iterator<list_type::const_iterator>;
 
private:
  list_type Jobs;
 
public:
  void Print(llvm::raw_ostream &OS, const char *Terminator,
             bool Quote, CrashReportInfo *CrashInfo = nullptr) const;
 
  /// Add a job to the list (taking ownership).
  void addJob(std::unique_ptr<Command> J) { Jobs.push_back(std::move(J)); }
 
  /// Clear the job list.
  void clear();
 
  /// Return a mutable list of Jobs for llvm-foreach wrapping.
  list_type &getJobsForOverride() { return Jobs; }
  const list_type &getJobs() const { return Jobs; }
 
  bool empty() const { return Jobs.empty(); }
  size_type size() const { return Jobs.size(); }
  iterator begin() { return Jobs.begin(); }
  const_iterator begin() const { return Jobs.begin(); }
  iterator end() { return Jobs.end(); }
  const_iterator end() const { return Jobs.end(); }
};
 
} // namespace driver
} // namespace clang
 
#endif // LLVM_CLANG_DRIVER_JOB_H