Merge branch 'main' into patch-1

Author: MaxDesiatov

.github/workflows/build_release.yml

@@ -7,15 +7,15 @@ on:
         description: "Version of swiftly to build release artifacts"
         required: true
         type: string
-        default: "0.4.0"
+        default: "1.1.0"
       skip:
         description: "Perform release checks, such as the git tag, and swift version, or '--skip' to skip that."
         required: true
         type: string
         default: "--skip"
 
 env:
-  SWIFTLY_BOOTSTRAP_VERSION: 0.4.0-dev
+  SWIFTLY_BOOTSTRAP_VERSION: 1.0.0
 
 jobs:
   buildrelease:

.github/workflows/pull_request.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 env:
-  SWIFTLY_BOOTSTRAP_VERSION: 0.4.0-dev
+  SWIFTLY_BOOTSTRAP_VERSION: 1.0.0
 
 jobs:
   soundness:
@@ -50,14 +50,49 @@ jobs:
       - name: Prepare the action
         run: ./scripts/prep-gh-action.sh --install-swiftly
       - name: Build Artifact
-        run: swift run build-swiftly-release --use-rhel-ubi9 --skip "999.0.0"
+        run: swift run build-swiftly-release --test --skip "999.0.0"
       - name: Upload Artifact
         uses: actions/upload-artifact@v4
         with:
           name: swiftly-release-x86_64
           path: .build/release/swiftly-*.tar.gz
           if-no-files-found: error
           retention-days: 1
+      - name: Upload Tests
+        uses: actions/upload-artifact@v4
+        with:
+          name: swiftly-tests-x86_64
+          path: .build/debug/test-swiftly-linux-x86_64.tar.gz
+          if-no-files-found: error
+          retention-days: 1
+
+  releasetest:
+    name: Test Release / ${{matrix.shell.pkg}}
+    needs: releasebuildcheck
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shell: [
+          {"pkg": "bash", "bin": "/bin/bash"},
+          {"pkg": "zsh", "bin": "/bin/zsh"},
+          {"pkg": "fish", "bin": "/bin/fish"}
+        ]
+    container:
+      image: "ubuntu:24.04"
+    steps:
+      - name: Prepare System
+        run: apt-get update && DEBIAN_FRONTEND=noninteractive TZ=Etc/UTC apt-get -y install ca-certificates gpg tzdata ${{matrix.shell.pkg}} && chsh -s ${{matrix.shell.bin}}
+      - name: Download Release
+        uses: actions/download-artifact@v4
+        with:
+          name: swiftly-release-x86_64
+      - name: Download Tests
+        uses: actions/download-artifact@v4
+        with:
+          name: swiftly-tests-x86_64
+      - name: Extract and Run Workflow Tests
+        run: cp swiftly-*.tar.gz /root/swiftly.tar.gz && cp test-swiftly-*.tar.gz /root && cd /root && tar zxf test-swiftly-*.tar.gz && ./test-swiftly -y ./swiftly.tar.gz
 
   formatcheck:
     name: Format Check

.swift-version

@@ -1 +1 @@
-6.0.3
+6.1.0

DESIGN.md

@@ -341,7 +341,7 @@ CC=clang swiftly run +latest make
 
 ## Detailed Design
 
-Swiftly itself will be a SPM project consisting of several executable products, one per supported platform, and all of these will share the core module that handles argument parsing, printing help information, and dispatching commands. Each platform’s executable will be built to statically link the stdlib so that they can be run without having installed Swift first.
+Swiftly itself will be a SwiftPM project consisting of several executable products, one per supported platform, and all of these will share the core module that handles argument parsing, printing help information, and dispatching commands. Each platform’s executable will be built to statically link the stdlib so that they can be run without having installed Swift first.
 
 Within the core module, the following protocol will be defined:
 
@@ -440,7 +440,7 @@ Determining whether the system has these installed or not is a bit of a tricky p
 
 If neither of these steps find the package, then we'll consider the dependency as not installed, and print a message that shows users how to install it using the system package manager (e.g. `apt` on Ubuntu).
 
-SPM has some code for detecting system libraries too, so it's possible we could integrate that here instead of using this approach.
+SwiftPM has some code for detecting system libraries too, so it's possible we could integrate that here instead of using this approach.
 
 #### Downloading a toolchain
 

Documentation/SwiftlyDocs.docc/SwiftlyDocs.md

@@ -6,6 +6,9 @@ Install and manage your Swift programming language toolchains.
     @DisplayName("Swiftly")
 }
 
+Swiftly helps you to easily install different Swift toolchains locally on your account.
+It provides a single path to install, update, remove, or run commands with a specific Swift toolchain.
+
 ## Topics
 
 - <doc:getting-started>

Documentation/SwiftlyDocs.docc/automated-install.md

@@ -1,75 +1,95 @@
-# Install Swiftly Automatically
+# Install swiftly automatically
 
 Automatically install swiftly and Swift toolchains.
 
 This guide helps you to automate the installation of swiftly and toolchains so that it can run unattended, for example in build or continous integration systems.
-We assume that you have working understanding of your build system. The examples are based on a typical Unix environment.
+This guide assumes that you have working understanding of your build system.
+The examples are based on a typical Unix environment.
 
-First, download the swiftly binary from swift.org for your operating system (e.g. Linux) and processor architecture (e.g. arm64, or x86_64). Here's an example using the popular curl command.
+### Download the binary
+
+First, download the swiftly binary from swift.org for your operating system (for example, Linux) and processor architecture (for example `arm64` or `x86_64`).
+Here's an example using the popular curl command.
 
 ```
-curl -L <location_of_swiftly_swift_org> > swiftly.tar.gz
+curl -L https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz > swiftly.tar.gz
 tar zxf swiftly.tar.gz
 ```
 
-On macOS you can download the pkg file and extract it like this from the command-line:
+On macOS, download the pkg file and extract it like this from the command-line:
 
 ```
-curl -L <location_of_swiftly_swift_org> > swiftly.pkg
+curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
 installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
 ```
 
-> Tip: If you are using Linux you will need the "ca-certificates" package for the root certificate authorities that will establish the trust that swiftly needs to make API requests that it needs. This package is frequently pre-installed on end-user environments, but may not be present in more minimal installations.
+> Tip: If you are using Linux you will need GPG and the "ca-certificates" package for the root certificate authorities that will establish the trust that swiftly needs to make API requests that it needs. This package is frequently pre-installed on end-user environments, but may not be present in more minimal installations.
+
+### Install swiftly
 
-Once swiftly is downloaded you can run the init subcommand to finish the installation. This command will print verbose outputs, assume yes for all prompts, and skip the automatic installation of the latest swift toolchain:
+Once swiftly is downloaded, run the `init` subcommand to finish the installation.
+The following example command prints verbose outputs, assume yes for all prompts, and skips the automatic installation of the latest swift toolchain:
 
 ```
 ./swiftly init --verbose --assume-yes --skip-install    # the swiftly binary is extracted to ~/local/bin/swiftly on macOS
 ```
 
-Swiftly is installed, but the current shell may not yet be updated with the new environment variables, such as the PATH. The init command prints instructions on how to update the current shell environment without opening a new shell. This is an example of the output taken from Linux, but the details might be different for other OSes, username, or shell.
+Swiftly is installed, but the current shell may not yet be updated with the new environment variables, such as `PATH`.
+The `init` command prints instructions on how to update the current shell environment without opening a new shell.
+The following output is an example from Linux, the details might be different for other OSes, username, or shell:
 
 ```
 To begin using installed swiftly from your current shell, first run the following command:
 
 . "/root/.local/share/swiftly/env.sh"
 ```
 
-> Note: on macOS systems you may need to run 'hash -r' to recalculate the zsh PATH cache when installing swiftly and toolchains.
+> Note: on macOS, run 'hash -r' to recalculate the zsh PATH cache when installing swiftly and toolchains.
+
+You can go ahead and add this command to the list of commands in your build script so that the build can proceed to call swiftly from the path. 
+
+### Install a toolchain
 
-You can go ahead and add this command to the list of commands in your build script so that the build can proceed to call swiftly from the path. The usual next step is to install a specific swift toolchain like this:
+The usual next step is to install a specific swift toolchain using the `install` command with the `--post-install-file` option:
 
 ```
 swiftly install 5.10.1 --post-install-file=post-install.sh
 ```
 
-It's possible that there will be some post-installation steps to prepare the build system for using the swift toolchain. The `post-install-file` option gives a file, post-install.sh, that is created if there are post installation steps for this toolchain. You can check if the file exists and run it to perform those final steps. If the build runs as the root user you can check it and run it like this in a typical Unix shell:
+It's possible that there will be some post-installation steps to prepare the system for using the swift toolchain.
+If additional post-install steps are needed to use the toolchain they are written to the file you specified; `post-install.sh` in the example above.
+You can check if the file exists and run it to perform those final steps.
+If the build runs as the root user you can check it and run it like this in a typical Unix shell:
 
 ```
 if [ -f post-install.sh ]; then
     . post-install.sh
 fi
 ```
 
-> Note: If the build system runs your script as a regular user then you will need to take this into account by either pre-installing the toolchain's system dependencies or running the `post-install.sh` script in a secure manner as the administrative user.
+> Note: If the system runs your script as a regular user then you will need to take this into account by either pre-installing the toolchain's system dependencies or running the `post-install.sh` script in a secure manner as the administrative user.
+
+### Customize the installation
 
 If you want to install swiftly, or the binaries that it manages into different locations these can be customized using environment variables before running `swiftly init`.
 
-```
-SWIFTLY_HOME_DIR - The location of the swiftly configuration files, and environment scripts
-SWIFTLY_BIN_DIR - The location of the swiftly binary and toolchain symbolic links (e.g. swift, swiftc, etc.)
-```
+- term `SWIFTLY_HOME_DIR`: The location of the swiftly configuration files, and environment scripts
+- term `SWIFTLY_BIN_DIR`: The location of the swiftly binary and toolchain symbolic links (for example swift, swiftc, and so on)
+- term `TMPDIR`: The temporary directory swiftly uses to hold large files, such as downloads, until it cleans them up.
 
-Sometimes the build system platform can't be automatically detected, or isn't supported by swift. You can provide the platform as an option to the swiftly init subcommand:
+Sometimes swiftly can't automatically detect the system platform, or isn't supported by swift.
+You can provide the platform as an option to the `swiftly init` subcommand:
 
 ```
 swiftly init --platform=<platform_name>
 ```
 
-There are other customizable options, such as overwrite. For more details about the available options, check the help:
+There are other customizable options, such as overwrite.
+For more details about the available options, check the help:
 
 ```
 swiftly init --help
 ```
 
-In summary, swiftly can be installed and install toolchains unattended on build and CI-style systems. This HOWTO guide has outlined the process to script the process covering some of the different options available to you.
+In summary, swiftly can be installed and install toolchains unattended on build and CI-style systems.
+This guide has outlined the process to script the process covering some of the different options available to you.

Documentation/SwiftlyDocs.docc/getting-started.md

@@ -1,15 +1,16 @@
-# Getting Started with Swiftly
+# Getting started with swiftly
 
-Start using swiftly and swift.
+Start using swiftly and Swift.
 
 To get started with swiftly you can download it from [swift.org](https://swift.org/download), and extract the package.
 
 @TabNavigator {
     @Tab("Linux") {
-        If you are using Linux then you can verify and extract the archive like this:
+        If you are using Linux then you can download the binary:
 
         ```
-        tar zxf swiftly-x.y.z.tar.gz
+        curl -L https://download.swift.org/swiftly/linux/swiftly-$(uname -m).tar.gz > swiftly.tar.gz
+        tar zxf swiftly.tar.gz
         ```
 
         Now run swiftly init to finish the installation:
@@ -20,21 +21,24 @@ To get started with swiftly you can download it from [swift.org](https://swift.o
     }
 
     @Tab("macOS") {
-        On macOS you can either run the pkg installer from the command-line like this or just run the package by double-clicking on it (not recommended):
+        On macOS you can either run the pkg installer from the command-line like this or run the package by double-clicking on it (not recommended):
 
         ```
-        installer -pkg swift-x.y.z.pkg -target CurrentUserHomeDirectory
+        curl -L https://download.swift.org/swiftly/darwin/swiftly.pkg > swiftly.pkg
+        installer -pkg swiftly.pkg -target CurrentUserHomeDirectory
         ```
 
-        Now run swiftly init to finish the installation:
+        Once the package is installed, run `swiftly init` to finish the installation:
 
         ```
-        ~/usr/local/bin/swiftly init
+        ~/.swiftly/bin/swiftly init
         ```
     }
 }
 
-Swiftly will install itself and download the latest available Swift toolchain. Follow the prompts for any additional steps. Once everything is done you can begin using swift.
+Swiftly installs itself and downloads the latest available Swift toolchain.
+Follow the prompts for any additional steps that may be required.
+Once everything is done you can begin using swift.
 
 ```
 $ swift --version
@@ -72,20 +76,22 @@ Uninstall this toolchain after you're finished with it:
 $ swiftly uninstall main-snapshot
 ```
 
-# Proxy
+## Installing toolchains through an HTTP proxy
 
 Swiftly downloads a list of toolchains from https://www.swift.org/ and retrieves them from CDN via https://download.swift.org.
-If your environment requires a proxy, Swiftly will attempt to use the standard environment variables `http_proxy`, `HTTP_PROXY`, `https_proxy` or `HTTPS_PROXY` to determine which proxy server to use instead of making a direct connection.
+If your environment requires a proxy, Swiftly attempts to use the standard environment variables `http_proxy`, `HTTP_PROXY`, `https_proxy` or `HTTPS_PROXY` to determine which proxy server to use instead of making a direct connection.
 
 To download latest nightly snapshot using a proxy:
 ```
 $ export https_proxy=http://proxy:3128
 $ swiftly install main-snapshot
 ```
 
-# See Also:
+## See Also:
 
+- [Add shell autocompletions](shell-autocompletion)
 - [Install Toolchains](install-toolchains)
 - [Using Toolchains](use-toolchains)
 - [Uninstall Toolchains](uninstall-toolchains)
 - [Swiftly CLI Reference](swiftly-cli-reference)
+

Documentation/SwiftlyDocs.docc/install-toolchains.md

@@ -1,18 +1,21 @@
-# Install Swift Toolchains
+# Install Swift toolchains
 
 Install swift toolchains with Swiftly.
 
-Installing a swift toolchain using swiftly involves downloading it securely and extracting it into a well-known location in your account. Here we will guide you through the different ways you can install a swift toolchain. You will need to install swiftly first. The [Getting Started](getting-started.md) guide is a good place to start with swiftly.
+Installing a swift toolchain using swiftly involves downloading it securely and extracting it into a well-known location in your account.
+This guides you through the different ways you can install a swift toolchain.
+Follow the [Getting Started](getting-started.md) guide to install swiftly.
 
 The easiest way to install a swift toolchain is to select the latest stable release:
 
 ```
 $ swiftly install latest
 ```
 
-> Note: After you install a toolchain there may be certain system dependencies that are needed. Swiftly will provide instructions.
+> Note: After you install a toolchain there may be certain system dependencies that are needed.
+Swiftly provides instructions for any additional dependencies that need to be installed.
 
-If this is the only toolchain that is installed then swiftly will automatically "use" it so that when you run swift (or any other toolchain command) it will be this version.
+If this is the only installed toolchain, swiftly automatically uses it. When you run `swift` (or another toolchain command), it uses the installed version.
 
 ```
 $ swift --version
@@ -21,7 +24,8 @@ Swift version 5.8.1 (swift-5.8.1-RELEASE)
 Target: x86_64-unknown-linux-gnu
 ```
 
-You can be very specific about the released version that you want. We can install the 5.6.1 version like this:
+You can be very specific about the released version to install.
+For example, the following command installs the 5.6.1 toolchain version:
 
 ```
 $ swiftly install 5.6.1
@@ -33,13 +37,13 @@ Once you've installed more than one toolchain you may notice that swift is on th
 $ swiftly use 5.6.1
 ```
 
-You can also combine install and use into one command to automate this process with the `--use` switch on the install subcommand:
+You can combine `install` and `use` into one command with the `--use` switch on the `install` subcommand:
 
 ```
 $ swiftly install --use 5.7.1
 ```
 
-Sometimes you want the latest available patch of a minor release, such as 5.7. Let's omit the patch number so that we get the latest patch.
+Sometimes you want the latest available patch of a minor release, such as 5.7. If you omit the patch number from the release you request, swiftly installs the latest patch.
 
 ```
 $ swiftly install 5.7

Documentation/SwiftlyDocs.docc/shell-autocompletion.md

@@ -1,8 +1,8 @@
-# Add Shell Auto-completions
+# Add shell auto-completions
 
-Generate shell auto-completions for Swiftly.
+Generate shell autocompletions for swiftly.
 
-Swiftly can generate shell auto-completion scripts for your shell to automatically complete subcommands, arguments, options and flags. It does this using the [swift-argument-parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/installingcompletionscripts/), which has support for Bash, Z shell, and Fish.
+Swiftly can generate shell autocompletion scripts for your shell to automatically complete subcommands, arguments, options and flags. It does this using the [swift-argument-parser](https://apple.github.io/swift-argument-parser/documentation/argumentparser/installingcompletionscripts/), which has support for Bash, Z shell, and Fish.
 
 You can ask swiftly to generate the script using the hidden `--generate-completion-script` flag with the type of shell like this:
 
@@ -63,4 +63,4 @@ swiftly --generate-completion-script <shell>
     }
 }
 
-Once you have installed the completions you can type out a swiftly command, and press a special key (e.g. tab) and the shell will show you the available subcommand, argument, or options to make it easier to assemble a working command-line.
+Once you have installed the completions you can type out a swiftly command, and press a special key (for example, tab) and the shell will show you the available subcommand, argument, or options to make it easier to assemble a working command-line.