From d94c5476ca753cb09dd0aa0cd0e19b0062f9a205 Mon Sep 17 00:00:00 2001 From: Chris McGee Date: Fri, 7 Feb 2025 15:44:23 -0500 Subject: [PATCH] Update documentation and online help to add more clarity about the global default and in-use toolchains Skip prompting to update an existing swift version file Add more informative messages when using toolchains to indicate what actually changed --- .../SwiftlyDocs.docc/swiftly-cli-reference.md | 6 +-- .../SwiftlyDocs.docc/use-toolchains.md | 42 +++++++++++++++++-- Sources/Swiftly/Use.swift | 26 ++++++------ 3 files changed, 54 insertions(+), 20 deletions(-) diff --git a/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md b/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md index 1a69f011..1ba9b5a6 100644 --- a/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md +++ b/Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md @@ -145,7 +145,7 @@ Note that listing available snapshots before the latest release (major and minor ## use -Set the in-use toolchain. If no toolchain is provided, print the currently in-use toolchain, if any. +Set the in-use or default toolchain. If no toolchain is provided, print the currently in-use toolchain, if any. ``` swiftly use [--print-location] [--global-default] [--assume-yes] [--verbose] [] [--version] [--help] @@ -158,7 +158,7 @@ swiftly use [--print-location] [--global-default] [--assume-yes] [--verbose] [ Note: The toolchain must be installed on your system before you can run with it. + +The `.swift version` file, if it is present in your working directory (or parent) will select the toolchain that is in use. If you are working in a directory that doesn't have this file, then you can set a global default toolchain to use in these places. + +``` +$ swiftly use --global-default 6.0.1 +``` + +Here the `--global-default` flag ensures that the default is set globally to the "6.0.1" toolchain whenever there isn't a swift version file, and there isn't a version specified in the `swiftly run` command. Also, this flag doesn't attempt to create a swift version file, or update it if it already exists. + +## In use toolchains and default toolchains + +When you list installed toolchains or use the `swiftly use` command to print the current in use toolchain there will be tags for both "in use" and "default." Sometimes the same toolchain will have both tags! + +``` +$ swiftly list +Installed release toolchains +---------------------------- +Swift 6.0.3 +Swift 6.0.2 (in use) (default) + +Installed snapshot toolchains +----------------------------- +``` + +Whenever a toolchain is tagged as "in use" indicates the toolchain that will be used when running toolchain commands from your current working directory. The one that is selected is based either on what is in a `.swift-version` file or the global default if there is no such file there. + +The default tag is used to show the global default toolchain, which is independent of any swift version file. The global default is there for cases where the file doesn't exist. It sets the toolchain that is in use in those cases. diff --git a/Sources/Swiftly/Use.swift b/Sources/Swiftly/Use.swift index 29f3cfd9..18db0245 100644 --- a/Sources/Swiftly/Use.swift +++ b/Sources/Swiftly/Use.swift @@ -4,13 +4,13 @@ import SwiftlyCore internal struct Use: SwiftlyCommand { public static var configuration = CommandConfiguration( - abstract: "Set the in-use toolchain. If no toolchain is provided, print the currently in-use toolchain, if any." + abstract: "Set the in-use or default toolchain. If no toolchain is provided, print the currently in-use toolchain, if any." ) @Flag(name: .shortAndLong, help: "Print the location of the in-use toolchain. This is valid only when there is no toolchain argument.") var printLocation: Bool = false - @Flag(name: .shortAndLong, help: "Use the global default, ignoring any .swift-version files.") + @Flag(name: .shortAndLong, help: "Set the global default toolchain that is used when there are no .swift-version files.") var globalDefault: Bool = false @OptionGroup var root: GlobalOptions @@ -19,7 +19,10 @@ internal struct Use: SwiftlyCommand { "The toolchain to use.", discussion: """ - If no toolchain is provided, the currently in-use toolchain will be printed, if any: + If no toolchain is provided, the currently in-use toolchain will be printed, if any. \ + This is based on the current working directory and `.swift-version` files if one is \ + present. If the in-use toolchain is also the global default then it will be shown as \ + the default. $ swiftly use @@ -107,18 +110,13 @@ internal struct Use: SwiftlyCommand { internal static func execute(_ toolchain: ToolchainVersion, globalDefault: Bool, assumeYes: Bool = true, _ config: inout Config) async throws { let (selectedVersion, result) = try await selectToolchain(config: &config, globalDefault: globalDefault) - if case let .swiftVersionFile(versionFile, _, _) = result { - if !assumeYes { - SwiftlyCore.print("The file `\(versionFile)` will be updated to set the new in-use toolchain for this project. Alternatively, you can set your default globally with the `--global-default` flag. Proceed with modifying this file?") - - guard SwiftlyCore.promptForConfirmation(defaultBehavior: true) else { - SwiftlyCore.print("Aborting setting in-use toolchain") - return - } - } + var message: String + if case let .swiftVersionFile(versionFile, _, _) = result { // We don't care in this case if there were any problems with the swift version files, just overwrite it with the new value try toolchain.name.write(to: versionFile, atomically: true, encoding: .utf8) + + message = "The file `\(versionFile)` has been set to `\(toolchain)`" } else if let newVersionFile = findNewVersionFile(), !globalDefault { if !assumeYes { SwiftlyCore.print("A new file `\(newVersionFile)` will be created to set the new in-use toolchain for this project. Alternatively, you can set your default globally with the `--global-default` flag. Proceed with creating this file?") @@ -130,12 +128,14 @@ internal struct Use: SwiftlyCommand { } try toolchain.name.write(to: newVersionFile, atomically: true, encoding: .utf8) + + message = "The file `\(newVersionFile)` has been set to `\(toolchain)`" } else { config.inUse = toolchain try config.save() + message = "The global default toolchain has set to `\(toolchain)`" } - var message = "Set the in-use toolchain to \(toolchain)" if let selectedVersion = selectedVersion { message += " (was \(selectedVersion.name))" }