What is the correct way to include Playgrounds in a Swift Package?

Question

When I publish a Swift Package, I like to include some Playgrounds to show examples of how to use the package. Prior to Swift 5.4, I was able to do this in a relatively straightforward way, but now none of my Playgrounds ever sees the contents of my package module. It doesn't make any sense to me.

I've followed the exact pattern illustrated by Apple's own WWDC videos, which is to have a Playgrounds/ folder as a peer to your Sources/ folder, and then just import the package module.

The import works, but the Playground always reports that it cannot find any of the types from inside the module. They are all marked public, and as I mentioned before, these used to work just fine.

This doesn't work for me in Swift 5.4 or 5.5, in Xcode 12.5 or 13 Beta.

I assume there must be some setting or configuration I am not understanding. Can somebody please explain the best practice here?

For reference, here is one of my simple Swift Packages that has Playgrounds that currently do not work: https://github.com/dunesailer/Wordsmith

EDIT: It gets even stranger. I have a different Swift Package structured what appears to me to be the exact same way, but its Playgrounds work fine. Whaaat? That one is here: https://github.com/dunesailer/Aesthete

Answer 1

If you move/ delete the folders Chemical Names, Work Titles and Person Names inside Playgrounds/, all the playgrounds work fine. It looks like Xcode doesn't support folders in Playgrounds/ (/ it's a bug).

So to work around this issue, just put all your playgrounds in the same folder.

EDIT: It looks like this works inconsistently. I've submitted a bug report/ Feedback for Developer Tools in Feedback Assistant.

---

A longer term workaround is to use DocC (arrived in Xcode 13 beta), which will support more advanced tutorials/ articles in the repo.

Answer 2

Use workspace.

(Xcode: File: New: Workspace)

You use it as "container" for both your package, playground (or app target for that matter). The important thing is to add each of these to the workspace by using "Add files to ..." button in the lower-left section of the Xcode, and from there on, open the .xcworkspace file:

1. to edit your package
2. to run playground file.

You can follow instructions from here.

https://stackoverflow.com/a/67580251/13292535