/gsoc-2021-writeups

Write-ups of GSoC 2021 project "SwiftPM support for Swift scripts"

Apache License 2.0Apache-2.0

GSoC 2021: SwiftPM support for Swift scripts

This repository contains write-ups for my GSoC 2021 project SwiftPM support for Swift scripts, which summarizes the efforts and achievements. You can also learn how to check out the codes and give it a try.

Environment

I'm using macOS 11.5.2 with Xcode 13 beta 5 on an Intel Mac by the end of the coding period. That is, you're likely to build and use the toolchain smoothly if you're at the same version. It is also assumed to be compatible with macOS 11.5.1, macOS 12 beta and with Xcode 13 beta 4, but there's no guarantee.

Trying to use the toolchain on Windows is known to be problematic because these tools are not optimized for Windows use case. Linux support has not been tested yet, but all the changes are platform-neutral and thus not supposed to break Linux builds.

Remember that the supported Xcode versions are not documented in swift/utils/build-script, so you'll need to set SKIP_XCODE_VERSION_CHECK=1 before starting to build the toolchain on macOS.

Overview

The work is split into 4 separate repositories. For existing repositories like swift, swift-driver and swift-package-manager, changes stay in gsoc-2021 branch of my own fork. Code for package-syntax-parser is placed in a new repository.

Name Repository Branch Pull Request Write-up
swift stevapple/swift gsoc-2021 stevapple/swift#1 Link
swift-driver stevapple/swift-driver gsoc-2021 stevapple/swift-driver#1 Link
swiftpm stevapple/swift-package-manager gsoc-2021 stevapple/swift-package-manager#1 Link
package-syntax-parser stevapple/package-syntax-parser main - Link

Checkout

You can manually check out any of these repositories to dig into the codes. Any recent version of the toolchain can be used. If you want to check out all of them, you can use the utils/update-checkout from swift:

git clone -b gsoc-2021 https://github.com/stevapple/swift swift
cd swift
utils/update-checkout --clone

The commands above will clone all the repositories that are required to build the toolchain to your computer.

Build

You can build the toolchain following the Getting Started guide from swift. I recommend using Ninja instead of Xcode. A minimal build of the GSoC 2021 project uses the following config:

utils/build-script --skip-build-benchmarks \
  --skip-ios --skip-watchos --skip-tvos --swift-darwin-supported-archs "$(uname -m)" \
  --sccache --release-debuginfo --swift-disable-dead-stripping \
  --install-all --llbuild --swiftpm --swift-driver --swiftsyntax --package-parser

Run the command above from swift, and you'll get the toolchain at build/Ninja-RelWithDebInfoAssert/toolchain-macosx-x86_64/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr. This toolchain is incomplete for using with an IDE, but you can add its bin directory to $PATH and try it in command line.

Using the toolchain in Xcode has not been tested. If you'd like to have a try, run:

utils/build-toolchain $BUNDLE_PREFIX

where $BUNDLE_PREFIX is a string that will be prepended to the build date to give the bundle identifier of the toolchain's Info.plist. For instance, if $BUNDLE_PREFIX was com.example, the toolchain produced will have the bundle identifier com.example.YYYYMMDD. It will be created with a filename of the form: swift-LOCAL-YYYY-MM-DD-a-osx.tar.gz.

Usage

This project adds a swift-script tool that can execute single-file Swift scripts with @package declarations on imports, which indicates importing the target from the declared Swift package with the module's name. For example:

@package(url: "https://github.com/apple/swift-log.git", from: "1.0.0")
import Logging

will import the target named Logging from .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"). SwiftPM will assume the package name to be swift-log, inferred from the last path component.

You can use swift script run script.swift [arguments] to run a script with such syntax. Specify --quiet or --verbose to see less or more output from the build system. For the usage of other subcommands, see swift-package-manager or run swift script <subcommand> --help.

You may also use the swift shortcut provided by swift-driver. Driver calls like:

swift script.swift

will be automatically transformed into

swift-script run --quiet script.swift

if script.swift uses @package syntax.

Evolution

This project is intended to be the prototype of a new Swift feature, which will eventually go through the Swift Evolution process. The Swift Forums thread of the Evolution proposal is here.

I will continue to push the work forward after GSoC, until it completes the Evolution process. I regard it as a really exciting and promising feature, and I hope you'll like it.

Feel free to leave your comment!