SwiftSyntax is now a SwiftPM project

Announcements
1

SwiftSyntax is now a Swift package manager package that is being developed in its own repository at https://github.com/apple/swift-syntax.

Using SwiftSyntax

SwiftSyntax can be configured as the dependency of any other SwiftPM project by adding

.package(url: "https://github.com/apple/swift-syntax.git", .branch("<#Specify Release tag#>")),

to you dependencies and making the build target depend on SwiftSyntax using

.target(name: "MyTool", dependencies: ["SwiftSyntax"])

<#Specify Release tag#> needs to refer to a tagged release of SwiftSyntax. Tags will be created for every release of the compiler in the form swift-4.2-RELEASE and for every nightly build in the form swift-4.2-DEVELOPMENT-SNAPSHOT-2018-08-25-a. The latest tag as of now for Swift 4.2 is swift-4.2-DEVELOPMENT-SNAPSHOT-2018-08-25-a and for Swift 5.0 swift-DEVELOPMENT-SNAPSHOT-2018-08-25-a.

The Readme contains more detailed information on how to use SwiftSyntax.

From Swift 5.0 onwards, SwiftSyntax will no longer be included in the Open Source toolchains, giving a consistent behaviour across toolchains distributed through Xcode and swift.org.

At the moment, building SwiftSyntax on Linux is not supported but we would greatly appreciate pull requests to add that functionality. Here’s the JIRA issue for Linux support.

If you should hit any issues while using SwiftSyntax, we appreciate bug reports on bugs.swift.org in the SwiftSyntax component.

Contributing

Building SwiftSyntax locally

SwiftSyntax still relies on the main Swift repository for code generation of the syntax tree's layout. The main swift project is thus still needed to build the most recent version of SwiftSyntax locally. Refer to swift-syntax/README.md for the steps how to do this.

Swift-CI will automatically run the code generation step whenever a new toolchain (development snapshot or release) is published and create an appropriate tag for it as described above. Referring to these tags is the recommended way to use SwiftSyntax as a dependency.

CI Integration

The @swift-ci Please test on apple/swift command already tests SwiftSyntax. CI testing for the SwiftSyntax repository will be added in the near future, as will the automated generation of release tags.

36 Likes
2

Will there be semver releases too? Branch based dependencies can only be used at the top-level (i.e. only in the root package).

3

Given that SwiftSyntax isn't stable yet, there's not really any interesting semver to do, and there is value in including the Swift version number in the release name. Too bad only three components are allowed, or you could do, e.g. 0.4.2.x.

2 Likes
4

SwiftSyntax can use 0.x.x as it is considered to be unstable (although there is no special handling for that in SwiftPM (maybe there should be)). Swift version can be included in build metadata component. Example: 0.0.1+swift-4.2-DEVELOPMENT-SNAPSHOT-2018-08-25-a

5

Hm, that still seems like we're missing a component, since it means there'll only be one active tag. Maybe we can encode-as-one-number, so Swift 4.2.1 becomes 0.40201.0 or something?

3 Likes
6

After some discussion we decided to go with the version scheme that @jrose suggested.

7

Sorry for the newbie questions, I'm kind of new to the whole swift compiler project... But how does this project relate/compare to SourceKit?

In a blog post on swift.org I read that SourceKit could be used to execute refactoring operations. On the other hand, in the readme of lib/Syntax I read that libSyntax could be used for migrating swift code from one version to another. At first sight these projects (Syntax and SourceKit) seem to have a bit of overlapping functionality.

So is this (libSyntax / SwiftSyntax) something that could replace SourceKit in the longer term? Or is it just a lower level tool that will eventually be used by SourceKit? Or am I seeing things completely wrong here?

1 Like
8

SourceKit provides a way to interface with the compiler (via a C API) and primarily do semantic things that editors need, like provide code-completion. SwiftSyntax allows you to write swift code and manipulate programmatically the syntactic structure of swift sources. Currently there is only syntactic support, there is no way to do semantic queries via using SwiftSyntax.

SourceKit and SwiftSyntax are complementary, for example there is a SourceKit request to get the libSyntax tree for a swift file and then manipulate it by using SwiftSyntax. If at some point we provide a mechanism to do semantic queries on a SwiftSyntax tree it will most likely "funnel through" the SourceKit framework.

4 Likes
9

Thanks that’s clear