Migrating to Swift Playground Books

The other day, whilst preparing my submission for this year’s Swift Student Challenge, I (once again) ran over one of the more widely known issues with Swift Playgrounds. I seemingly randomly got runtime errors such as “Abort() called”, especially when using SwiftUI for my live views. These errors, usually resulting from bugs in Swift Playgrounds itself, can often be resolved by disabling “Enable Results”. It would, however, be sort of awkward to ask those judging my playground to disable said mode themselves, I thought, and thus began searching for a way to disable this function entirely. In the end, I opted for a Swift Playground Book instead of a regular Playground as this, amongst many other advantages, allows me to use Manifest.plist-files to disable said mode. In this article, I want to give tips on how to easily migrate an existing playground to a playground book.

Using the Template

The blank playground book template

As you can see, this template also provides us with a LiveViewTestApp. But I will not go into details about that one at this point. First of all, you might want to customise the metadata contained in the top-level Manifest.plist (i.e., PlaygroundBook/Manifest.plist). For instance, you might want to change the playground’s Name, or add an ImageReference to it.

Importing Playground Pages

The shortest possible Manifest.plist

However, I just want to advise you, that these manifests are an extremely powerful tool for us playground creators! Apple gives us more details on this here.

Lastly, we need to make sure that everything we just imported is referenced correctly. Long story short, playground books are structured hierarchically — which practically means that everything must be referenced in its parent’s manifest. Most importantly for us, that means we have to make sure that all our playground pages are being referenced in our chapter’s Manifest.plist’s Pages-array. For instance:

A playground page must be referenced by its directory name

If you changed the top-level structure (i.e., added, removed, or renamed chapters), make sure that they’re being referenced correctly in the book’s Manifest.plist as well.


“Compiling” the Playground Book

Make sure to select the PlaygroundBook target. What device you select on the right-hand side doesn’t matter in this case.

Clicking Run now results in a .playgroundbook-file being built. You can find that file in your project’s Products/ folder. Using Control-Click → Show in Finder → Share you can for instance air-drop it to an iPad.

Disabling the “Enable Results”-mode

Disabling Playground Logging

A Huge Disadvantage

Hi there, my name is Julian and I’m currently a student. I’ve been programming for about seven years and am mainly focussed on app development. WWDC20-Scholar.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store