Macro Adoption Concerns around SwiftSyntax

Thanks for sharing your concerns @stephencelis

Regarding (1) SwiftSyntax build times

Yes, that is cost of building a macro at the moment and unfortunately I don't have any suggestion of how to improve this situation at the moment. Installing swift-syntax into the toolchain will only work in cases where that installed version happens to match the one that SwiftPM resolved, which won't match if we need to create a patch release of swift-syntax or the Swift 5.10 compiler is used with swift-syntax 509.

Regarding (2) SwiftSyntax Version Dependency

I have just composed an article that describes how macros should adjust their versions when updating to a new major swift-syntax version: Add an article that describes how macros should be versioned when updating their swift-syntax dependency by ahoppen · Pull Request #2024 · apple/swift-syntax · GitHub. Let me know if that answers your questions. The TL;DR is: Update the minor version of a macro when updating its swift-syntax version dependency.

Regarding (3a) SwiftSyntax API Breakage

swift-syntax has matured significantly over the last few months, the main driver being the drastic increase in our user base from macro authors. This has involved a significant number of rapid changes, with the goal of delivering a solid release alongside Swift 5.9. The latest changes you comment on are due to Significant changes in the latest swift-syntax 509 prerelease, which we decided to land now to reduce the churn of the Swift 5.10-aligned release of swift-syntax.

We are anticipating that swift-syntax's API will become a lot more stable after its Swift 5.9-aligned release, though there will always be some API breakages in swift-syntax as the swift language itself evolves. We will do our best to mitigate these changes through API deprecations, which we have already been doing between the latest snapshot releases.

Regarding (3b) Lack of Examples

The swift-syntax repository contains a couple of examples that are guaranteed to always be up-to-date by a CI job. We'll also incorporate @Douglas_Gregor's list of example macros into there as well (#2026). Similarly swift-format is a sizable client of swift-syntax that's always compatible with the latest swift-syntax release. Beyond these, are there any particular examples you think are missing?

Regarding (3b) Lack of Documentation

With the two WWDC presentations on macros, Expand on Swift macros and Write Swift macros I think we have two good ways of getting started with macro development. allows browsing the swift-syntax API and allows interactive exploration of the syntax tree. I agree that it would always be good to have more documentation, but I think we aren't in a terribly bad spot at the moment. If there's anything you feel is missing, pull requests and/or issues are always welcome.