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

Author: cmcgee1024

.github/workflows/build_release.yml

@@ -7,7 +7,7 @@ on:
         description: "Version of swiftly to build release artifacts"
         required: true
         type: string
-        default: "0.3.0"
+        default: "0.4.0-dev"
       skip:
         description: "Perform release checks, such as the git tag, and swift version, or '--skip' to skip that."
         required: true
@@ -23,10 +23,19 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Build Artifact
-        run: swift run build-swiftly-release ${{ inputs.skip }} ${{ inputs.version }}
-      - name: Upload Artifact
+      - name: Build Release Artifact
+        run: swift run build-swiftly-release --use-rhel-ubi9 ${{ inputs.skip }} ${{ inputs.version }}
+      - 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

@@ -23,7 +23,6 @@ jobs:
     name: Test
     uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
     with:
-      # Amazon Linux 2 won't work with GH infrastructure
       linux_os_versions: "[\"jammy\", \"focal\", \"rhel-ubi9\", \"noble\", \"bookworm\", \"fedora39\"]"
       # We only care about the current stable release, because that's where we make our swiftly releases
       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\"}]"
@@ -39,10 +38,11 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Build Artifact
-        run: swift run build-swiftly-release --skip "999.0.0"
+        run: swift run build-swiftly-release --use-rhel-ubi9 --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
@@ -57,3 +57,25 @@ jobs:
       linux_pre_build_command: ./scripts/prep-gh-action.sh
       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,45 @@
 # 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
-```
+        ```
+        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
+        ```
+    }
 
-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!
+    @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:
+
+        ```
+        ~/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

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,14 @@ 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.
+Install swiftly using a script (hosted from this repository) using the command:
+
 ```
 curl -L https://swiftlang.github.io/swiftly/swiftly-install.sh | bash
 ```
 
-Alternatively, you can download the swiftly binary and it can install itself:
+In the future, download the swiftly package from [swift.org](https://swift.org/download) and it can install itself with init:
+
 ```
 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).")
         }