Enable host toolchain on macOS by default, improve README.md (#196)

It adds some documentation to help with common issues people run into. But primarily, this PR sets `--host-toolchain` on macOS by default, since most people are using Xcode and not the Swift OSS toolchain to run the generator and build using generated Swift SDKs.

---------

Co-authored-by: Max Desiatov <[email protected]>

Author: xtremekforever

README.md

@@ -116,6 +116,43 @@ for Ubuntu Jammy and Swift 5.9 this would be `swift:5.9-jammy-slim`. If you'd li
 an arbitrary Ubuntu Jammy system, make sure you pass `--static-swift-stdlib` flag to `swift build`, in addition
 to the `--experimental-swift-sdk` option.
 
+## Common Generator Options
+
+By default, on macOS hosts running on Apple Silicon, the Swift SDK Generator will create Swift SDKs
+for Ubuntu Jammy on aarch64, which matches the CPU architecture of the host. However, it is possible to change
+the default target architecture by passing the `--target-arch` flag:
+
+```bash
+swift run swift-sdk-generator make-linux-sdk --target-arch x86_64
+```
+
+This will default to building the Swift SDK for `x86_64-unknown-linux-gnu`. To build for other
+platforms and environments, supply the `--target` flag with the full target triple instead.
+
+The Linux distribution name and version can also be passed to change from the default of Ubuntu Jammy:
+
+```bash
+swift run swift-sdk-generator make-linux-sdk --distribution-name ubuntu --distribution-version 24.04
+```
+
+### Host Toolchain
+
+The host toolchain is not included in the generated Swift SDK by default on Linux to match the behavior
+of the [Static Linux Swift SDKs](https://www.swift.org/documentation/articles/static-linux-getting-started.html)
+downloadable from [swift.org](https://www.swift.org/install/). However, on macOS, since most users are using Xcode
+and are likely not using the Swift OSS toolchain to build and run Swift projects, the Swift host toolchain
+is included by *default*. This default behavior can be changed by passing  `--no-host-toolchain`:
+
+```bash
+swift run swift-sdk-generator make-linux-sdk --no-host-toolchain --target-arch x86_64
+```
+
+To generate the Swift SDK on Linux with the host toolchain included, add `--host-toolchain`:
+
+```bash
+swift run swift-sdk-generator make-linux-sdk --host-toolchain --target-arch aarch64
+```
+
 ## Building an SDK from a container image
 
 You can base your SDK on a container image, such as one of the
@@ -125,10 +162,10 @@ Jammy image:
 ```
 swift run swift-sdk-generator make-linux-sdk --with-docker
 ```
-To build a RHEL images, use the `--linux-distribution-name` option.
+To build a RHEL images, use the `--distribution-name` option.
 The following command will build a `ubi9`-based image:
 ```
-swift run swift-sdk-generator make-linux-sdk --with-docker --linux-distribution-name rhel
+swift run swift-sdk-generator make-linux-sdk --with-docker --distribution-name rhel
 ```
 
 You can also specify the base container image by name:
@@ -138,7 +175,7 @@ swift run swift-sdk-generator make-linux-sdk --from-container-image swift:5.9-ja
 ```
 
 ```
-swift run swift-sdk-generator make-linux-sdk --with-docker --linux-distribution-name rhel --from-container-image swift:5.9-rhel-ubi9
+swift run swift-sdk-generator make-linux-sdk --with-docker --distribution-name rhel --from-container-image swift:5.9-rhel-ubi9
 ```
 
 ### Including extra Linux libraries

Sources/GeneratorCLI/GeneratorCLI.swift

@@ -131,7 +131,7 @@ extension GeneratorCLI {
         but requires exactly the same version of the swift.org toolchain to be installed for it to work.
         """
     )
-    var hostToolchain: Bool = false
+    var hostToolchain: Bool = hostToolchainDefault
 
     @Option(
       help: """
@@ -149,17 +149,31 @@ extension GeneratorCLI {
     var host: Triple? = nil
 
     @Option(
-      help: """
-        The target triple of the bundle. The default depends on a recipe used for SDK generation. Pass `--help` to a specific recipe subcommand for more details.
-        """
+      help:
+        "The target triple of the bundle. The default depends on a recipe used for SDK generation."
     )
     var target: Triple? = nil
 
     @Option(help: "Deprecated. Use `--host` instead")
     var hostArch: Triple.Arch? = nil
-    @Option(help: "Deprecated. Use `--target` instead")
+    @Option(
+      help: """
+        The target arch of the bundle. The default depends on a recipe used for SDK generation. \
+        If this is passed, the target triple will default to `<target-arch>-unknown-linux-gnu`. \
+        Use the `--target` param to pass the full target triple if needed.
+        """
+    )
     var targetArch: Triple.Arch? = nil
 
+    /// Default to adding host toolchain when building on macOS
+    static var hostToolchainDefault: Bool {
+      #if os(macOS)
+        true
+      #else
+        false
+      #endif
+    }
+
     func deriveHostTriple() throws -> Triple {
       if let host {
         return host
@@ -204,7 +218,7 @@ extension GeneratorCLI {
         """,
       transform: LinuxDistribution.Name.init(nameString:)
     )
-    var linuxDistributionName = LinuxDistribution.Name.ubuntu
+    var distributionName = LinuxDistribution.Name.ubuntu
 
     @Option(
       help: """
@@ -214,7 +228,7 @@ extension GeneratorCLI {
         - Available options for RHEL: `ubi9` (default when `--distribution-name` is `rhel`).
         """
     )
-    var linuxDistributionVersion: String?
+    var distributionVersion: String?
 
     func deriveTargetTriple(hostTriple: Triple) -> Triple {
       if let target = generatorOptions.target {
@@ -223,8 +237,9 @@ extension GeneratorCLI {
       if let arch = generatorOptions.targetArch {
         let target = Triple(arch: arch, vendor: nil, os: .linux, environment: .gnu)
         appLogger.warning(
-          "deprecated: Please use `--target \(target.triple)` instead of `--target-arch \(arch)`"
+          "Using `--target-arch \(arch)` defaults to `\(target.triple)`. Use `--target` if you want to pass the full target triple."
         )
+        return target
       }
       return Triple(arch: hostTriple.arch!, vendor: nil, os: .linux, environment: .gnu)
     }
@@ -235,20 +250,20 @@ extension GeneratorCLI {
           "deprecated: Please explicitly specify the subcommand to run. For example: $ swift-sdk-generator make-linux-sdk"
         )
       }
-      let linuxDistributionDefaultVersion: String
-      switch self.linuxDistributionName {
+      let distributionDefaultVersion: String
+      switch self.distributionName {
       case .rhel:
-        linuxDistributionDefaultVersion = "ubi9"
+        distributionDefaultVersion = "ubi9"
       case .ubuntu:
-        linuxDistributionDefaultVersion = "22.04"
+        distributionDefaultVersion = "22.04"
       case .debian:
-        linuxDistributionDefaultVersion = "12"
+        distributionDefaultVersion = "12"
       }
-      let linuxDistributionVersion =
-        self.linuxDistributionVersion ?? linuxDistributionDefaultVersion
+      let distributionVersion =
+        self.distributionVersion ?? distributionDefaultVersion
       let linuxDistribution = try LinuxDistribution(
-        name: linuxDistributionName,
-        version: linuxDistributionVersion
+        name: distributionName,
+        version: distributionVersion
       )
       let hostTriple = try self.generatorOptions.deriveHostTriple()
       let targetTriple = self.deriveTargetTriple(hostTriple: hostTriple)

Sources/SwiftSDKGenerator/SystemUtils/GeneratorError.swift

@@ -41,7 +41,7 @@ extension GeneratorError: CustomStringConvertible {
       return "Process launched with \(commandInfo) failed with exit code \(exitCode)"
     case let .unknownLinuxDistribution(name, version):
       return
-        "Linux distribution `\(name)`\(version.map { " with version \($0)" } ?? "")` is not supported by this generator."
+        "Linux distribution `\(name)`\(version.map { " with version `\($0)`" } ?? "") is not supported by this generator."
     case let .unknownMacOSVersion(version):
       return "macOS version `\(version)` is not supported by this generator."
     case let .unknownCPUArchitecture(cpu):

Tests/SwiftSDKGeneratorTests/EndToEndTests.swift

@@ -140,7 +140,7 @@ final class RepeatedBuildTests: XCTestCase {
     do {
       try await Shell.run("docker ps")
       possibleArguments.append(
-        "--with-docker --linux-distribution-name rhel --linux-distribution-version ubi9"
+        "--with-docker --distribution-name rhel --distribution-version ubi9"
       )
     } catch {
       self.logger.warning(
@@ -223,8 +223,8 @@ struct SDKConfiguration {
       "--swift-version \(swiftVersion)-RELEASE",
       testLinuxSwiftSDKs ? "--host \(hostArch!)-unknown-linux-gnu" : nil,
       "--target \(architecture)-unknown-linux-gnu",
-      "--linux-distribution-name \(linuxDistributionName)",
-      "--linux-distribution-version \(linuxDistributionVersion)",
+      "--distribution-name \(linuxDistributionName)",
+      "--distribution-version \(linuxDistributionVersion)",
     ].compactMap { $0 }.joined(separator: " ")
   }
 }