Introduce a new executable, swift-help, which prints help info for tools

swift-help is extremely simple, but it allows -help handling to more easily
fit into the driver's Job model. A new SwiftOptions module contains the
option types and definitions which are shared with the driver.

Author: owenv

Package.swift

@@ -10,9 +10,15 @@ let package = Package(
     .executable(
       name: "swift-driver",
       targets: ["swift-driver"]),
+    .executable(
+      name: "swift-help",
+      targets: ["swift-help"]),
     .library(
       name: "SwiftDriver",
       targets: ["SwiftDriver"]),
+    .library(
+      name: "SwiftOptions",
+      targets: ["SwiftOptions"]),
   ],
   dependencies: [
     .package(url: "https://github.com/apple/swift-tools-support-core.git", .branch("master")),
@@ -23,16 +29,29 @@ let package = Package(
     /// The driver library.
     .target(
       name: "SwiftDriver",
-      dependencies: ["SwiftToolsSupport-auto", "llbuildSwift", "Yams"]),
+      dependencies: ["SwiftOptions", "SwiftToolsSupport-auto", "llbuildSwift", "Yams"]),
     .testTarget(
       name: "SwiftDriverTests",
       dependencies: ["SwiftDriver", "swift-driver"]),
 
+    /// The options library.
+    .target(
+      name: "SwiftOptions",
+      dependencies: ["SwiftToolsSupport-auto"]),
+    .testTarget(
+      name: "SwiftOptionsTests",
+      dependencies: ["SwiftOptions"]),
+
     /// The primary driver executable.
     .target(
       name: "swift-driver",
       dependencies: ["SwiftDriver"]),
 
+    /// The help executable.
+    .target(
+      name: "swift-help",
+      dependencies: ["SwiftOptions"]),
+
     /// The `makeOptions` utility (for importing option definitions).
     .target(
       name: "makeOptions",

README.md

@@ -102,7 +102,7 @@ $ swift build -Xcc -I/path/to/build/Ninja-ReleaseAssert/swift-.../include --prod
 Then, run `makeOptions` and redirect the output to overwrite `Options.swift`:
 
 ```
-$ .build/path/to/makeOptions > Sources/SwiftDriver/Options/Options.swift
+$ .build/path/to/makeOptions > Sources/SwiftOptions/Options.swift
 ```
 
 ### Development Plan

Sources/SwiftDriver/Driver/Driver.swift

@@ -12,6 +12,7 @@
 import TSCBasic
 import TSCUtility
 import Foundation
+import SwiftOptions
 
 /// How should the Swift module output be handled?
 public enum ModuleOutput: Equatable {
@@ -595,11 +596,6 @@ extension Driver {
       return try exec(path: toolchain.getToolPath(.swiftCompiler).pathString, args: driverKind.usageArgs + parsedOptions.commandLine)
     }
 
-    if parsedOptions.contains(.help) || parsedOptions.contains(.helpHidden) {
-      optionTable.printHelp(driverKind: driverKind, includeHidden: parsedOptions.contains(.helpHidden))
-      return
-    }
-
     if parsedOptions.hasArgument(.v) {
       try printVersion(outputStream: &stderrStream)
     }

Sources/SwiftDriver/Incremental Compilation/IncrementalCompilation.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 import TSCBasic
 import Foundation
+import SwiftOptions
 
 // FIXME: rename to something like IncrementalCompilationInitialState
 public struct IncrementalCompilation {

Sources/SwiftDriver/Jobs/CommandLineArguments.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 import TSCBasic
+import SwiftOptions
 
 /// Utilities for manipulating a list of command line arguments, including
 /// constructing one from a set of ParsedOptions.

Sources/SwiftDriver/Jobs/CompileJob.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 import TSCBasic
+import SwiftOptions
 
 extension Driver {
   /// Add the appropriate compile mode option to the command line for a compile job.

Sources/SwiftDriver/Jobs/DarwinToolchain+LinkerSupport.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 import TSCBasic
+import SwiftOptions
 
 extension DarwinToolchain {
   private func findARCLiteLibPath() throws -> AbsolutePath? {

Sources/SwiftDriver/Jobs/GenericUnixToolchain+LinkerSupport.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 import TSCBasic
+import SwiftOptions
 
 extension GenericUnixToolchain {
   private func defaultLinker(for targetTriple: Triple) -> String? {

Sources/SwiftDriver/Jobs/Job.swift

@@ -30,6 +30,7 @@ public struct Job: Codable, Equatable, Hashable {
     case verifyDebugInfo = "verify-debug-info"
     case printTargetInfo = "print-target-info"
     case versionRequest = "version-request"
+    case help
   }
 
   public enum ArgTemplate: Equatable, Hashable {

Sources/SwiftDriver/Jobs/Planning.swift

@@ -191,6 +191,19 @@ extension Driver {
                  requiresInPlaceExecution: true)
     }
 
+    if parsedOptions.contains(.help) || parsedOptions.contains(.helpHidden) {
+      var commandLine: [Job.ArgTemplate] = [.flag("-tool=\(driverKind.rawValue)")]
+      if parsedOptions.contains(.helpHidden) {
+        commandLine.append(.flag("-show-hidden"))
+      }
+      return Job(kind: .help,
+                 tool: .absolute(try toolchain.getToolPath(.swiftHelp)),
+                 commandLine: commandLine,
+                 inputs: [],
+                 outputs: [],
+                 requiresInPlaceExecution: true)
+    }
+
     return nil
   }
 

Sources/SwiftDriver/Jobs/Toolchain+InterpreterSupport.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 //
 import TSCBasic
+import SwiftOptions
 
 extension Toolchain {
   func addPathEnvironmentVariableIfNeeded(

Sources/SwiftDriver/Jobs/Toolchain+LinkerSupport.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 import TSCBasic
+import SwiftOptions
 
 extension Toolchain {
   // MARK: - Path computation

Sources/SwiftDriver/Toolchains/DarwinToolchain.swift

@@ -62,6 +62,8 @@ public final class DarwinToolchain: Toolchain {
       return try lookup(executable: "lldb")
     case .dwarfdump:
       return try lookup(executable: "dwarfdump")
+    case .swiftHelp:
+      return try lookup(executable: "swift-help")
     }
   }
 

Sources/SwiftDriver/Toolchains/GenericUnixToolchain.swift

@@ -61,6 +61,8 @@ public final class GenericUnixToolchain: Toolchain {
       return try lookup(executable: "lldb")
     case .dwarfdump:
       return try lookup(executable: "dwarfdump")
+    case .swiftHelp:
+      return try lookup(executable: "swift-help")
     }
   }
 

Sources/SwiftDriver/Toolchains/Toolchain.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 import Foundation
 import TSCBasic
+import SwiftOptions
 
 public enum Tool {
   case swiftCompiler
@@ -21,6 +22,7 @@ public enum Tool {
   case dsymutil
   case lldb
   case dwarfdump
+  case swiftHelp
 }
 
 /// Describes a toolchain, which includes information about compilers, linkers

Sources/SwiftDriver/Utilities/Diagnostics.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 import TSCBasic
+import SwiftOptions
 
 public typealias Diagnostic = TSCBasic.Diagnostic
 public typealias DiagnosticData = TSCBasic.DiagnosticData

Sources/SwiftDriver/Driver/DriverKind.swift renamed to Sources/SwiftOptions/DriverKind.swift

@@ -11,16 +11,16 @@
 //===----------------------------------------------------------------------===//
 
 /// Describes which mode the driver is in.
-public enum DriverKind {
-  case interactive
-  case batch
-  case moduleWrap
-  case frontend
-  case autolinkExtract
-  case indent
+public enum DriverKind: String {
+  case interactive = "swift"
+  case batch = "swiftc"
+  case moduleWrap = "swift-modulewrap"
+  case frontend = "swift-frontend"
+  case autolinkExtract = "swift-autolink-extract"
+  case indent = "swift-indent"
 
   /// Returns true if driver kind is Swift compiler.
-  var isSwiftCompiler: Bool {
+  public var isSwiftCompiler: Bool {
     return self == .interactive || self == .batch
   }
 }

Sources/SwiftDriver/Options/ExtraOptions.swift renamed to Sources/SwiftOptions/ExtraOptions.swift

@@ -17,17 +17,17 @@ public struct OptionAttributes: OptionSet, Hashable {
     self.rawValue = rawValue
   }
 
-  static let helpHidden                    = OptionAttributes(rawValue: 0x1)
-  static let frontend                      = OptionAttributes(rawValue: 0x2)
-  static let noDriver                      = OptionAttributes(rawValue: 0x4)
-  static let noInteractive                 = OptionAttributes(rawValue: 0x8)
-  static let noBatch                       = OptionAttributes(rawValue: 0x10)
-  static let doesNotAffectIncrementalBuild = OptionAttributes(rawValue: 0x20)
-  static let autolinkExtract               = OptionAttributes(rawValue: 0x40)
-  static let moduleWrap                    = OptionAttributes(rawValue: 0x80)
-  static let indent                        = OptionAttributes(rawValue: 0x100)
-  static let argumentIsPath                = OptionAttributes(rawValue: 0x200)
-  static let moduleInterface               = OptionAttributes(rawValue: 0x400)
+  public static let helpHidden                    = OptionAttributes(rawValue: 0x1)
+  public static let frontend                      = OptionAttributes(rawValue: 0x2)
+  public static let noDriver                      = OptionAttributes(rawValue: 0x4)
+  public static let noInteractive                 = OptionAttributes(rawValue: 0x8)
+  public static let noBatch                       = OptionAttributes(rawValue: 0x10)
+  public static let doesNotAffectIncrementalBuild = OptionAttributes(rawValue: 0x20)
+  public static let autolinkExtract               = OptionAttributes(rawValue: 0x40)
+  public static let moduleWrap                    = OptionAttributes(rawValue: 0x80)
+  public static let indent                        = OptionAttributes(rawValue: 0x100)
+  public static let argumentIsPath                = OptionAttributes(rawValue: 0x200)
+  public static let moduleInterface               = OptionAttributes(rawValue: 0x400)
 }
 
 /// Describes a command-line option.

Sources/SwiftDriver/Options/Option.swift renamed to Sources/SwiftOptions/Option.swift

@@ -18,7 +18,7 @@ public struct ParsedOption {
     case multiple([String])
 
     /// Retrieve the single-string argument.
-    var asSingle: String {
+    public var asSingle: String {
       switch self {
       case .single(let result):
         return result
@@ -29,7 +29,7 @@ public struct ParsedOption {
     }
 
     /// Retrieve multiple string arguments.
-    var asMultiple: [String] {
+    public var asMultiple: [String] {
       switch self {
       case .multiple(let result):
         return result
@@ -48,6 +48,12 @@ public struct ParsedOption {
 
   /// The index in the command line where this argument appeared.
   public let index: Int
+
+  public init(option: Option, argument: Argument, index: Int) {
+    self.option = option
+    self.argument = argument
+    self.index = index
+  }
 }
 
 extension ParsedOption: CustomStringConvertible {

Sources/SwiftDriver/Options/OptionParsing.swift renamed to Sources/SwiftOptions/OptionParsing.swift

@@ -0,0 +1,52 @@
+//===--------------- main.swift - Swift Help Main Entrypoint --------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2020 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+import SwiftOptions
+import TSCBasic
+import TSCLibc
+import TSCUtility
+
+extension DriverKind: StringEnumArgument {
+  public static var completion: ShellCompletion { .none }
+}
+
+struct Options {
+  var driverKind: DriverKind = .interactive
+  var showHidden: Bool = false
+}
+
+var args = CommandLine.arguments.dropFirst()
+let driverOptionTable = OptionTable()
+let parser = ArgumentParser(commandName: "swift help",
+                            usage: " ",
+                            overview: "Swift help tool",
+                            seeAlso: nil)
+let binder = ArgumentBinder<Options>()
+binder.bind(option: parser.add(option: "-show-hidden",
+                               usage: "List hidden (unsupported) options"),
+            to: { $0.showHidden = $1 })
+binder.bind(option: parser.add(option: "-tool", kind: DriverKind.self,
+                               usage: "The tool to list options of"),
+            to: { $0.driverKind = $1 })
+
+do {
+  let parseResult = try parser.parse(Array(CommandLine.arguments.dropFirst()))
+  var options = Options()
+  try binder.fill(parseResult: parseResult, into: &options)
+
+  // Print the option table.
+  driverOptionTable.printHelp(driverKind: options.driverKind,
+                              includeHidden: options.showHidden)
+} catch {
+  stderrStream <<< "error: " <<< error.localizedDescription
+  stderrStream.flush()
+  exit(EXIT_FAILURE)
+}