Merge branch 'main' of github.com:cmcgee1024/swiftly into full_install_tests

Author: cmcgee1024

.github/workflows/build_release.yml

@@ -23,10 +23,19 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Build Artifact
+      - name: Build Release Artifact
         run: swift run build-swiftly-release ${{ inputs.skip }} ${{ inputs.version }}
-      - name: Upload Artifact
+      - name: Upload Release Artifact
         uses: actions/upload-artifact@v4
         with:
+          name: swiftly-release-x86_64
           path: .build/release/swiftly-*.tar.gz
           if-no-files-found: error
+      - name: Build Documentation Artifacts
+        run: swift package --allow-writing-to-directory .build/docs generate-documentation --target SwiftlyDocs --output-path .build/docs
+      - name: Upload Documentation Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: swiftly-docs
+          path: .build/docs/**
+          if-no-files-found: error

.github/workflows/pull_request.yml

@@ -123,5 +123,27 @@ jobs:
       linux_os_versions: "[\"jammy\"]"
       linux_exclude_swift_versions: "[{\"swift_version\": \"nightly-main\"},{\"swift_version\": \"nightly-6.0\"},{\"swift_version\": \"5.8\"},{\"swift_version\": \"5.9\"},{\"swift_version\": \"5.10\"}]"
       linux_pre_build_command: ./scripts/prep-gh-action.sh
-      linux_build_command: swift run swiftformat --lint --dryrun .
+      linux_build_command: swift run swiftformat --lint --dryrun . || (echo "Please run 'swift run swiftformat .' to format the source code."; exit 1)
       enable_windows_checks: false
+
+  docscheck:
+    name: Documentation Check
+    runs-on: ubuntu-latest
+    container:
+      image: "swift:6.0-noble"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Prepare the action
+        run: ./scripts/prep-gh-action.sh && ./scripts/install-libarchive.sh
+      - name: Generate Swiftly CLI Reference and Check for Differences
+        run: swift package plugin --allow-writing-to-package-directory generate-docs-reference && git config --global --add safe.directory $(pwd) && git diff --exit-code Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md || (echo "The documentation hasn't been updated with the latest swiftly command-line reference. Please run 'swift package plugin generate-docs-reference' and commit/push the changes."; exit 1)
+      - name: Generate Documentation Set
+        run: swift package --allow-writing-to-directory .build/docs generate-documentation --target SwiftlyDocs --output-path .build/docs
+      - name: Upload Documentation Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: swiftly-docs
+          path: .build/docs/**
+          if-no-files-found: error
+          retention-days: 1

Documentation/SwiftlyDocs.docc/automated-install.md

@@ -4,18 +4,26 @@ Swiftly can be installed automatically in places like build/CI systems.
 
 This guide will help you to script to the installation of swiftly and toolchains so that it can be unattended. We assume that you have working understanding of your build system. The examples are based on a typical Unix environment.
 
-First, download a swiftly binary from a trusted source, such as your artifact repository, or a well-known website for the operating system (e.g. Linux) and processor architecture (e.g. arm64, or x86_64). Here's an example using the popular curl command.
+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.
 
 ```
-curl -L <trusted_location_of_swiftly> > swiftly
+curl -L <location_of_swiftly_swift_org> > 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:
+
+```
+curl -L <location_of_swiftly_swift_org> > 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.
 
-Once swiftly is downloaded you can run the init subcommand to finish the installation. This command will use the default initialization options and proceed without prompting.
+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:
 
 ```
-./swiftly init --assume-yes
+./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.

Documentation/SwiftlyDocs.docc/getting-started.md

@@ -1,31 +1,46 @@
 # Getting Started with Swiftly
 
-To download swiftly and install Swift, run the following in your terminal, then follow the on-screen instructions:
+Start using swiftly and swift.
 
-```
-curl -L https://swiftlang.github.io/swiftly/swiftly-install.sh | bash
-```
+To get started with swiftly you can download it from [swift.org](https://swift.org/download), and extract the package.
 
-Alternatively, you can download the swiftly binary and install itself like this:
+@TabNavigator {
+    @Tab("Linux") {
+        If you are using Linux then you can verify and extract the archive like this:
 
-```
-swiftly init
-```
+        ```
+        sha256sum swiftly-x.y.z.tar.gz # Check that the hash matches what's reported on swift.org
+        tar zxf swiftly-x.y.z.tar.gz
+        ```
 
-Once swiftly is installed you can use it to install the latest available swift toolchain like this:
+        Now run swiftly init to finish the installation:
 
-```
-$ swiftly install latest
+        ```
+        ./swiftly init
+        ```
+    }
+
+    @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):
+
+        ```
+        installer -pkg swift-x.y.z.pkg -target CurrentUserHomeDirectory
+        ```
+
+        Now run swiftly init to finish the installation:
 
-Fetching the latest stable Swift release...
-Installing Swift 5.8.1
-Downloaded 488.5 MiB of 488.5 MiB
-Extracting toolchain...
-Swift 5.8.1 installed successfully!
+        ```
+        $HOME/usr/local/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.
+
+```
 $ swift --version
 
-Swift version 5.8.1 (swift-5.8.1-RELEASE)
+Swift version 6.0.1 (swift-6.0.1-RELEASE)
 Target: x86_64-unknown-linux-gnu
 
 $ swift build    # Build with the latest (5.8.1) toolchain
@@ -58,6 +73,17 @@ Uninstall this toolchain after you're finished with it:
 $ swiftly uninstall main-snapshot
 ```
 
+# Proxy
+
+Swiftly downloads a list of toolchains from https://www.swift.org/ and retrieves them from Apple/Akamai 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.
+
+To download latest nightly snapshot using a proxy:
+```
+$ export https_proxy=http://proxy:3128
+$ swiftly install main-snapshot
+```
+
 # See Also:
 
 - [Install Toolchains](install-toolchains)

Documentation/SwiftlyDocs.docc/swiftly-cli-reference.md

@@ -23,7 +23,7 @@ swiftly [--version] [--help]
 Install a new toolchain.
 
 ```
-swiftly install [<version>] [--use] [--verify|no-verify] [--post-install-file=<post-install-file>] [--assume-yes] [--version] [--help]
+swiftly install [<version>] [--use] [--verify|no-verify] [--post-install-file=<post-install-file>] [--assume-yes] [--verbose] [--version] [--help]
 ```
 
 **version:**
@@ -81,6 +81,11 @@ written to this file as commands that can be run after the installation.
 *Disable confirmation prompts by assuming 'yes'*
 
 
+**--verbose:**
+
+*Enable verbose reporting from swiftly*
+
+
 **--version:**
 
 *Show the version.*
@@ -143,7 +148,7 @@ Note that listing available snapshots before the latest release (major and minor
 Set the in-use toolchain. If no toolchain is provided, print the currently in-use toolchain, if any.
 
 ```
-swiftly use [--print-location] [--global-default] [--assume-yes] [<toolchain>] [--version] [--help]
+swiftly use [--print-location] [--global-default] [--assume-yes] [--verbose] [<toolchain>] [--version] [--help]
 ```
 
 **--print-location:**
@@ -161,6 +166,11 @@ swiftly use [--print-location] [--global-default] [--assume-yes] [<toolchain>] [
 *Disable confirmation prompts by assuming 'yes'*
 
 
+**--verbose:**
+
+*Enable verbose reporting from swiftly*
+
+
 **toolchain:**
 
 *The toolchain to use.*
@@ -210,7 +220,7 @@ Likewise, the latest snapshot associated with a given development branch can be
 Remove an installed toolchain.
 
 ```
-swiftly uninstall <toolchain> [--assume-yes] [--version] [--help]
+swiftly uninstall <toolchain> [--assume-yes] [--verbose] [--version] [--help]
 ```
 
 **toolchain:**
@@ -249,6 +259,11 @@ Finally, all installed toolchains can be uninstalled by specifying 'all':
 *Disable confirmation prompts by assuming 'yes'*
 
 
+**--verbose:**
+
+*Enable verbose reporting from swiftly*
+
+
 **--version:**
 
 *Show the version.*
@@ -309,7 +324,7 @@ The installed snapshots for a given devlopment branch can be listed by specifyin
 Update an installed toolchain to a newer version.
 
 ```
-swiftly update [<toolchain>] [--assume-yes] [--verify|no-verify] [--post-install-file=<post-install-file>] [--version] [--help]
+swiftly update [<toolchain>] [--assume-yes] [--verbose] [--verify|no-verify] [--post-install-file=<post-install-file>] [--version] [--help]
 ```
 
 **toolchain:**
@@ -355,6 +370,11 @@ A specific snapshot toolchain can be updated by including the date:
 *Disable confirmation prompts by assuming 'yes'*
 
 
+**--verbose:**
+
+*Enable verbose reporting from swiftly*
+
+
 **--verify|no-verify:**
 
 *Verify the toolchain's PGP signature before proceeding with installation.*
@@ -385,7 +405,7 @@ written to this file as commands that can be run after the installation.
 Perform swiftly initialization into your user account.
 
 ```
-swiftly init [--no-modify-profile] [--overwrite] [--platform=<platform>] [--assume-yes] [--version] [--help]
+swiftly init [--no-modify-profile] [--overwrite] [--platform=<platform>] [--skip-install] [--assume-yes] [--verbose] [--version] [--help]
 ```
 
 **--no-modify-profile:**
@@ -400,14 +420,24 @@ swiftly init [--no-modify-profile] [--overwrite] [--platform=<platform>] [--assu
 
 **--platform=\<platform\>:**
 
-*Specify the current Linux platform for swiftly.*
+*Specify the current Linux platform for swiftly*
+
+
+**--skip-install:**
+
+*Skip installing the latest toolchain*
 
 
 **--assume-yes:**
 
 *Disable confirmation prompts by assuming 'yes'*
 
 
+**--verbose:**
+
+*Enable verbose reporting from swiftly*
+
+
 **--version:**
 
 *Show the version.*
@@ -425,9 +455,19 @@ swiftly init [--no-modify-profile] [--overwrite] [--platform=<platform>] [--assu
 Update the version of swiftly itself.
 
 ```
-swiftly self-update [--version] [--help]
+swiftly self-update [--assume-yes] [--verbose] [--version] [--help]
 ```
 
+**--assume-yes:**
+
+*Disable confirmation prompts by assuming 'yes'*
+
+
+**--verbose:**
+
+*Enable verbose reporting from swiftly*
+
+
 **--version:**
 
 *Show the version.*

README.md

@@ -6,12 +6,8 @@ Ongoing maintenance and stewardship of this project is led by the [SSWG](https:/
 
 ### Installation
 
-To download swiftly and install Swift, run the following in your terminal, then follow the on-screen instructions.
-```
-curl -L https://swiftlang.github.io/swiftly/swiftly-install.sh | bash
-```
+Download the swiftly package from [swift.org](https://swift.org/download) and it can install itself with init:
 
-Alternatively, you can download the swiftly binary and it can install itself:
 ```
 swiftly init
 ```

Sources/LinuxPlatform/Linux.swift

@@ -327,7 +327,7 @@ public struct Linux: Platform {
         }
     }
 
-    public func install(from tmpFile: URL, version: ToolchainVersion) throws {
+    public func install(from tmpFile: URL, version: ToolchainVersion, verbose: Bool) throws {
         guard tmpFile.fileExists() else {
             throw Error(message: "\(tmpFile) doesn't exist")
         }
@@ -348,7 +348,14 @@ public struct Linux: Platform {
             let relativePath = name.drop { c in c != "/" }.dropFirst()
 
             // prepend /path/to/swiftlyHomeDir/toolchains/<toolchain> to each file name
-            return toolchainDir.appendingPathComponent(String(relativePath))
+            let destination = toolchainDir.appendingPathComponent(String(relativePath))
+
+            if verbose {
+                SwiftlyCore.print("\(destination.path)")
+            }
+
+            // prepend /path/to/swiftlyHomeDir/toolchains/<toolchain> to each file name
+            return destination
         }
     }
 
@@ -390,7 +397,7 @@ public struct Linux: Platform {
         FileManager.default.temporaryDirectory.appendingPathComponent("swiftly-\(UUID())")
     }
 
-    public func verifySignature(httpClient: SwiftlyHTTPClient, archiveDownloadURL: URL, archive: URL) async throws {
+    public func verifySignature(httpClient: SwiftlyHTTPClient, archiveDownloadURL: URL, archive: URL, verbose: Bool) async throws {
         SwiftlyCore.print("Downloading toolchain signature...")
         let sigFile = self.getTempFilePath()
         let _ = FileManager.default.createFile(atPath: sigFile.path, contents: nil)
@@ -405,7 +412,7 @@ public struct Linux: Platform {
 
         SwiftlyCore.print("Verifying toolchain signature...")
         do {
-            try self.runProgram("gpg", "--verify", sigFile.path, archive.path)
+            try self.runProgram("gpg", "--verify", sigFile.path, archive.path, quiet: !verbose)
         } catch {
             throw Error(message: "Signature verification failed: \(error).")
         }