Swift Snippets

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.

Documentation

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.

export SWIFTPM_ENABLE_SNIPPETS=1

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.

Syntax

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.

The //! comment is 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.

The MARK: Hide comment tells the snippet system that the line and subsequent lines should be hidden but kept for building and running. A MARK: Show line 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 Sources directory

No configuration or manifest changes are necessary!

Additional notes

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.

Demo

I created this little intro video.

Usage in the wild

I checked the following repositories from Apple and none of those are leveraging Snippets :(

• github.com/apple/swift
• github.com/apple/swift-package-manager
• github.com/apple/swift-argument-parser
• github.com/apple/swift-nio
• github.com/apple/swift-syntax
• github.com/apple/swift-log
• github.com/apple/swift-collections
• github.com/apple/swift-async-algorithms

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.

Future

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.