Version 1.0.0: SwiftPM Plugin Support

[kateinoigakukun]

Breaking changes:

carton CLI is now slimmed down to be a SwiftPM Plugin.
This means that you can now use carton by just declaring it as a dependency in your Package.swift file.

dependencies: [
    .package(url: "https://github.com/swiftwasm/carton", from: "1.0.0"),
],

This change requires Swift 5.9.2's SwiftPM to make cross-compilation work well, so Swift 5.9.1 or earlier is no longer supported.

Each carton subcommand is now split into a separate SwiftPM plugin.

Old command	New command
carton dev	swift run carton dev
carton test	swift run carton test
carton bundle	swift run carton bundle

Also carton no longer supports the following features:

• carton init command (use swift package init --type executable instead)

Internal changes:

• Reduce build time by removing unnecessary dependencies: 96.97s -> 25.26s
• No longer directly depend on SwiftPM as a library. This means that carton no longer has to be updated when SwiftPM is updated (hopefully).

Our new SwiftPM plugin oriented architecture is illustrated in the following diagram:

sequenceDiagram
    participant SwiftRunCarton as swift run carton
    participant SwiftPM
    participant CartonDevPlugin as carton-dev Plugin
    participant CartonFrontend
    SwiftRunCarton->>SwiftPM: exec
    SwiftPM->>CartonDevPlugin: spawn
    CartonDevPlugin->>SwiftPM: Build product
    SwiftPM->>CartonDevPlugin: Build artifacts
    CartonDevPlugin->>CartonFrontend: spawn
    note right of CartonDevPlugin: Establish IPC
    CartonFrontend->>CartonDevPlugin: File changed
    CartonDevPlugin->>SwiftPM: Build product
    SwiftPM->>CartonDevPlugin: Build artifacts
    CartonDevPlugin->>CartonFrontend: Reload browsers

Loading

Rationale on the design decision

Why not be a simple SwiftPM Plugin? Why use swift run?

swift run carton is a thin wrapper of SwiftPM Plugin to work around some SwiftPM Plugin limitations for the following purposes:

• to install appropriate SwiftWasm toolchain if it's not installed and to use it for the later invocations
  • This step will be eventually removed once SwiftPM provides a good way to manage Swift SDKs declaratively and Xcode toolchain provides WebAssembly target. (OSS toolchain already provides it)
• to grant the SwiftPM Plugin process appropriate permissions to write to the file system
  • "dev" and "test" subcommands require listening TCP sockets but SwiftPM doesn't provide a way to
    express this requirement in the package manifest
  • "bundle" subcommand requires writing to the file system to "./Bundle" directory. This is to keep soft compatibility with the default behavior of the previous version of Carton
• to give the SwiftPM build system the target triple by default
  • SwiftPM doesn't provide a way to control the target triple from plugin process
• to pre-build {package-name}PackageTests product before running plugin process
  • SwiftPM doesn't support building only "all tests" product from plugin process, so we have to build it before running the CartonTest plugin process

This swift run wrapper should be eventually removed once SwiftPM provides a way to express those requirements.

How does this affect Swift SDK support?

This design gives us better integration with SwiftPM build system and you will get more control over your build.

If you installed Swift SDK and Swift 5.9.2 from https://www.swift.org/download, you can use the SDK by directly invoking SwiftPM Plugin like below:

# carton dev
$ swift package --disable-sandbox --experimental-swift-sdk 5.9-SNAPSHOT-2024-02-15-a-wasm carton-dev

# carton test
$ swift build --experimental-swift-sdk 5.9-SNAPSHOT-2024-02-15-a-wasm --product "ExamplePackageTests"
$ swift package --disable-sandbox --experimental-swift-sdk 5.9-SNAPSHOT-2024-02-15-a-wasm carton-test

# carton bundle
$ swift package --experimental-swift-sdk DEVELOPMENT-SNAPSHOT-2024-02-08-a-wasm carton-bundle

Note that if you use SwiftPM Plugin directly, you need to ensure that the swift command is set up by yourself and teach SwiftPM for some permission options.