How swiftlang/swiftly works
Project type and purpose
• swiftly is a cross-platform (Linux/macOS) command-line tool written in Swift for installing, managing, and switching between multiple Swift toolchains.
• It communicates with external Swift.org APIs, downloads archived toolchains, extracts them, manages local installation directories, and updates shell environment settings.
File structure
• Top-level “Sources/Swiftly” contains the CLI entrypoint and subcommands (Install, Use, Update, Uninstall, List, Run, SelfUpdate, etc.).
• “Sources/SwiftlyCore” holds shared logic: HTTPClient, file‐management, error handling, version modeling, platform abstractions.
• “Sources/SwiftlyDownloadAPI” and “Sources/SwiftlyWebsiteAPI” each contain generated OpenAPI clients for external servers.
• “Sources/CLibArchive” provides a C wrapper for .tar/.zip extraction.
• “Sources/LinuxPlatform” and “Sources/MacOSPlatform” adapt platform‐specific behaviors.
• Plugins and Tools directories implement ancillary tasks (documentation generation, release builds).
• Tests exercise each CLI command and core module.
• Configuration and build by Swift Package Manager (Package.swift, Package.resolved). CI pipelines in .github/workflows.
a. CLI Frontend
• Single executable (“swiftly”) exposing subcommands.
• Parses user input and invokes corresponding command handler in SwiftlyCore.
b. Core Library
• ModeledCommandLine, Commands, Messages, Error types, version/file‐path utilities.
• HTTPClient for REST calls.
• Platform adapters select Linux vs. macOS logic.
c. Download & Website API Clients
• OpenAPI-generated modules for querying available toolchains and fetching release metadata.
d. Archive Extraction Layer
• CLibArchive bridging to libarchive for unpacking toolchain archives.
e. File System & Env Manager
• Creates installation directory structure (e.g. ~/.swiftpm or ~/.local/share/swiftly), symlinks binaries, writes env.sh/env.fish.
f. External Services
• Swift.org download servers and website APIs.
g. Shell Integration
• Sourced scripts modifying $PATH to point at selected toolchain.
h. Plugins & Tools
Relationships & data flows
• User types “swiftly install <version>” → CLI Frontend → CoreLibrary.InstallCommand
→ HTTPClient calls DownloadAPI to get URL and checksum
→ HTTPClient downloads archive
→ ArchiveExtraction extracts into local install root
→ FileSystem writes binaries and updates symlinks
→ CoreLibrary reports success via Messages.
• “swiftly use <version>” → CoreLibrary switches active symlink + updates shell env script.
• All commands go through the shared CoreLibrary and may call Platform adapters.
• Self-update works similarly but downloads a new CLI executable and replaces the current one.
Architectural patterns & design principles
• Modular layering: CLI runner → core logic → infrastructure (HTTP, FS, archive) → external APIs.
• Dependency inversion: high-level commands depend on abstract HTTPClient and FileManager interfaces.
• Separation of concerns: platform-specific code in dedicated modules; API clients auto-generated.
• Test coverage layer exercises each command through its public interface.