A critical look at Swift Snippets (Swift 5.7)
An experimental feature in Swift 5.7 (SPM, DocC) that does not get much love
3 min read
When I read VS Code Swift extension lesser known features I stumbled upon Swift Snippets.
A Swift Snippet is a new feature of Swift 5.7. They are single Swift files meant to demonstrate features of a Swift package. They can be used to provide code displayed inline in documentation, or complete sample projects.
I vaguely remembered a post in the Swift forums from 2021.
Snippets were available for testing in the Trunk Development snapshots back then.
Swift 5.7 was released in September 2022, and I was curious about where the feature is today and if I can find any adoption.
The Swift forums post is still the best documentation I can find. I am slightly surprised that no dedicated README exists in the Swift Package Manager repository. But then the feature is still experimental.
Enable experimental subcommand
You must set an environment variable to discover the feature in
swift package --help.
Only then does the new subcommand
swift package learn get listed.
swift package learn
swift package learn is a teaching tool that lets you view and run snippets. Snippets are small, focused, single Swift files intended to host example code that teaches a specific concept or API.
Here is an example of a snippet file.
//! Fizz fizz fizz. import SnippetTest fizz() // MARK: Hide print("Hidden code printed to the console!") // MARK: Show // More fizzing. fizz()
The code is from the example package shared in the Swift Forums post.
The snippet imports the
SnippetTest target from its Swift Package and calls the top-level function
fuzz twice. The file also contains a print statement and various annotations.
//! commentis presented as a brief explanation for the snippet. This comment does not show inline in the source but at the top or in a listing for searching and browsing. Feel free to use regular comments if you need to explain the flow of a snippet.
MARK: Hidecomment tells the snippet system that the line and subsequent lines should be hidden but kept for building and running. A
MARK: Showline will toggle that and lines will start showing again. This is how you separate presentation code from demo code, or glue code if you like.
Those snippet files must exist in a
Snippets directory alongside the familiar
No configuration or manifest changes are necessary!
Swift Package Manager treats each snippet file as an executable target and builds them alongside the other targets in a package. Any compiler error in your snippet will be reported as part of the
swift build for the package. This is true even if you did not set the environment variable.
I created this little intro video.
Usage in the wild
I checked the following repositories from Apple and none of those are leveraging Snippets :(
There are two pending pull requests to leverage snippets in swift-syntax and swift-markdown
Interestingly there seems to be an integration with swift-docc, but that feature is not documented!
A broader GitHub search did also not reveal that major open-source projects picked up to use Swift Snippets.
The outlook for this feature is pessimistic considering the low adoption rate. This might change if Apple invests in better documentation and adopts Snippets in their own repositories.
Did you find this article valuable?
Support Marco Eidinger by becoming a sponsor. Any amount is appreciated!