llvm.20.SwiftCompiler.Compiler-Driver

Swift Compiler Driver

本文基于Swift 5.5的源码: https://github.com/apple/swift/tree/release/5.5

1. Driver Tool

Ref[2] 是Driver命令行工具的CMakeLists.txt文件。

add_swift_host_tool(swift-frontend
  driver.cpp
  autolink_extract_main.cpp
  modulewrap_main.cpp
  swift_api_digester_main.cpp
  swift_indent_main.cpp
  swift_symbolgraph_extract_main.cpp
  swift_api_extract_main.cpp
  SWIFT_COMPONENT compiler
)
target_link_libraries(swift-frontend
                      PRIVATE
                        swiftAPIDigester
                        swiftDriver
                        swiftFrontendTool
                        swiftSymbolGraphGen
                        LLVMBitstreamReader)

1.1 Driver Tool Source Files

Main函数

通过add_swift_host_tool()来定义Driver Tool的源文件，其中driver.cpp为源文件的"入口"，该文件中定义了main()函数。

main()函数的主体逻辑如下所示:

int main(int argc_, const char **argv_) {
// ... ... 

  // Check if this invocation should execute a subcommand.
  StringRef ExecName = llvm::sys::path::stem(argv[0]);
  SmallString<256> SubcommandName;
  bool isRepl = false;
  if (shouldRunAsSubcommand(ExecName, SubcommandName, argv, isRepl)) { // Branch-A
  // ... ...

  return 2;
  }

  if (isRepl) {
    // Preserve argv for the stack trace.
    SmallVector<const char *, 256> replArgs(argv.begin(), argv.end());
    replArgs.erase(&replArgs[1]);
    return run_driver(ExecName, replArgs); // Branch-B
  } else {
    return run_driver(ExecName, argv); // Branch-C
  }

}

当以"/usr/bin/swiftc --driver-mode=swift -L /Users/zhangchong/SpareTime/DangerUsage/.build/debug -I /Users/zhangchong/SpareTime/DangerUsage/.build/debug -lDanger /var/folders/g0/wz34vwx54616p8q9thj8yyd00000gp/T/_tmp_dangerfile.swift runner"调用swiftc时, main函数会进入到Branch-C。

run_driver函数

在执行"/usr/bin/swiftc --driver-mode=swift -L /Users/zhangchong/SpareTime/DangerUsage/.build/debug -I /Users/zhangchong/SpareTime/DangerUsage/.build/debug -lDanger /var/folders/g0/wz34vwx54616p8q9thj8yyd00000gp/T/_tmp_dangerfile.swift runner"时，run_driver函数实际上执行Part-D部分。

static int run_driver(StringRef ExecName,
                       const ArrayRef<const char *> argv) {

  // Part-A: Check the first argument.
  // Handle integrated tools.
  if (argv.size() > 1) {
    StringRef FirstArg(argv[1]);
    if (FirstArg == "-frontend") {
      return performFrontend(llvm::makeArrayRef(argv.data()+2,
                                                argv.data()+argv.size()),
                             argv[0], (void *)(intptr_t)getExecutablePath);
    }
    if (FirstArg == "-modulewrap") {
      return modulewrap_main(llvm::makeArrayRef(argv.data()+2,
                                                argv.data()+argv.size()),
                             argv[0], (void *)(intptr_t)getExecutablePath);
    }

    // Run the integrated Swift frontend when called as "swift-frontend" but
    // without a leading "-frontend".
    if (!FirstArg.startswith("--driver-mode=")
        && ExecName == "swift-frontend") {
      return performFrontend(llvm::makeArrayRef(argv.data()+1,
                                                argv.data()+argv.size()),
                             argv[0], (void *)(intptr_t)getExecutablePath);
    }
  }


// ... ...
  
  // Part-B: Should we disable the new swift-driver?
  if (!shouldDisallowNewDriver(ExecName, argv)) {
    SmallString<256> NewDriverPath(llvm::sys::path::parent_path(Path));
    if (appendSwiftDriverName(NewDriverPath) &&
        llvm::sys::fs::exists(NewDriverPath)) {   

        // ... ... 
       return 2;
    }
  }

  // Part-C: Select the different tools based on the kind of Driver instance.
  Driver TheDriver(Path, ExecName, argv, Diags);
  switch (TheDriver.getDriverKind()) {
  case Driver::DriverKind::AutolinkExtract:
    return autolink_extract_main(
      TheDriver.getArgsWithoutProgramNameAndDriverMode(argv),
      argv[0], (void *)(intptr_t)getExecutablePath);
  case Driver::DriverKind::SwiftIndent:
    return swift_indent_main(
      TheDriver.getArgsWithoutProgramNameAndDriverMode(argv),
      argv[0], (void *)(intptr_t)getExecutablePath);
  case Driver::DriverKind::SymbolGraph:
      return swift_symbolgraph_extract_main(TheDriver.getArgsWithoutProgramNameAndDriverMode(argv), argv[0], (void *)(intptr_t)getExecutablePath);
  case Driver::DriverKind::APIExtract:
    return swift_api_extract_main(
        TheDriver.getArgsWithoutProgramNameAndDriverMode(argv), argv[0],
        (void *)(intptr_t)getExecutablePath);
  case Driver::DriverKind::APIDigester:
    return swift_api_digester_main(
        TheDriver.getArgsWithoutProgramNameAndDriverMode(argv), argv[0],
        (void *)(intptr_t)getExecutablePath);
  default:
    break;
  }

  // Part-D: Do the real compilation. (ignore the error check.)
  // Parse the arguments that from the command line.
  std::unique_ptr<llvm::opt::InputArgList> ArgList =
    TheDriver.parseArgStrings(ArrayRef<const char*>(argv).slice(1));
  // Build a ToolChain instance.
  std::unique_ptr<ToolChain> TC = TheDriver.buildToolChain(*ArgList);
  // Build a Compilation instance. 
  std::unique_ptr<Compilation> C =
      TheDriver.buildCompilation(*TC, std::move(ArgList));
  if (C) {
    // Build the task queue from the Compilation instance.
    std::unique_ptr<sys::TaskQueue> TQ = TheDriver.buildTaskQueue(*C);
    if (!TQ)
        return 1;
    // Run the jobs which are generated from the task queue.
    return C->performJobs(std::move(TQ)).exitCode;
  }

  return 0;  

}

1.2 Driver Tool Dependencies

2. swiftDriver library

Ref[1] 是swiftDriver库的CMakeLists.txt文件。

3. Driver Mode

`--driver-mode`的定义在Options.inc文件中, Options.inc文件是生成的。

TODO: 如何生成Options.inc文件?

从https://gist.github.com/vitonzhangtt/7f6f6feaa0e61373d90bbf9291d2b66b#file-options-inc-L322 可以看出

`--driver-mode`的值可以为: swift, 或者swiftc。

3.1 Driver Kind

Driver是整个编译过程的"驱动器"，Driver Kind保存Driver的类型。

Driver Kind有一些作用:

1. 决定Driver对命令行参数的解析

2. 影响OutputInput的生成

https://github1s.com/apple/swift/blob/release/5.5/lib/Driver/Driver.cpp#L1472-L1475

  
// OutputInfo &OI
OI.CompilerOutputType = driverKind == DriverKind::Interactive
                              ? file_types::TY_Nothing
                              : CompilerOutputType;

3. 影响Compiler Mode

https://github1s.com/apple/swift/blob/release/5.5/lib/Driver/Driver.cpp#L1854-L1857

// const InputFileList &Inputs
  if (driverKind == Driver::DriverKind::Interactive)
    return Inputs.empty() ? OutputInfo::Mode::REPL
                          : OutputInfo::Mode::Immediate;

4. 影响-help选项的输出

https://github1s.com/apple/swift/blob/release/5.5/lib/Driver/Driver.cpp#L3535-L3540

3.2 DriverKind的计算

Driver Mode决定了部分DriverKind的取值。 

在Driver的构造函数中，首先进行DriverKind的计算:

Driver::Driver(StringRef DriverExecutable,
               StringRef Name,
               ArrayRef<const char *> Args,
               DiagnosticEngine &Diags)
  : Opts(createSwiftOptTable()), Diags(Diags),
    Name(Name), DriverExecutable(DriverExecutable),
    DefaultTargetTriple(llvm::sys::getDefaultTargetTriple()) {
      
  // The driver kind must be parsed prior to parsing arguments, since that
  // affects how arguments are parsed.
  parseDriverKind(Args.slice(1));
}

void Driver::parseDriverKind(ArrayRef<const char *> Args) {
  // The default driver kind is determined by Name.
  StringRef DriverName = Name;

  std::string OptName;
  // However, the driver kind may be overridden if the first argument is
  // --driver-mode.
  if (!Args.empty()) {
    OptName = getOpts().getOption(options::OPT_driver_mode).getPrefixedName();

    StringRef FirstArg(Args[0]);
    if (FirstArg.startswith(OptName))
      DriverName = FirstArg.drop_front(OptName.size());
  }

  Optional<DriverKind> Kind =
      llvm::StringSwitch<Optional<DriverKind>>(DriverName)
          .Case("swift", DriverKind::Interactive) // --driver-mode=swift
          .Case("swiftc", DriverKind::Batch).      // --driver-mode=swiftc 
          .Case("swift-autolink-extract", DriverKind::AutolinkExtract)
          .Case("swift-indent", DriverKind::SwiftIndent)
          .Case("swift-symbolgraph-extract", DriverKind::SymbolGraph)
          .Case("swift-api-extract", DriverKind::APIExtract)
          .Case("swift-api-digester", DriverKind::APIDigester)
          .Default(None);

  if (Kind.hasValue())
    driverKind = Kind.getValue(); // driverKind is member of Driver Class.
  else if (!OptName.empty())
    Diags.diagnose({}, diag::error_invalid_arg_value, OptName, DriverName);
}

Interactive:  swift --driver-mode=swift 

Batch:  swift --driver-mode=swiftc 

1. --driver-mode=swiftc 

swiftc --driver-mode=swiftc hello.swift

编译hello.swift文件，生成可执行文件hello。

2. --driver-mode=swift 

swiftc --driver-mode=swift hello.swift

编译并执行hello.swift文件。 

Next: swift-driver　

  

---

Reference

1. CMakeLists.txt for swiftDriver

https://github.com/apple/swift/blob/release/5.5/lib/Driver/CMakeLists.txt

2. CMakeLists.txt for swift-frontend 

https://github.com/apple/swift/blob/release/5.5/tools/driver/CMakeLists.txt 

3. Headers file for swiftDriver

https://github.com/apple/swift/tree/release/5.5/include/swift/Driver

4. Options.inc

https://gist.github.com/vitonzhangtt/7f6f6feaa0e61373d90bbf9291d2b66b