Swiftpack.co - Package - finestructure/Arena


🏟 Arena

Arena is a macOS command line tool to create an Xcode project with a Swift Playground that's readily set up to use a Swift Package Manager library. You can reference both Github and local repositories. The latter is especially useful to spin up a Playground while working on a library.

Arena demo

Arena can also create a Playground in "Playground Book" format, which is the file format supported by "Swift Playgrounds". These playgrounds can then be synced and opened on the iOS version of "Swift Playgrounds" as well.

Here is an overview of the arena command line interface:

arena --help
OVERVIEW: Creates an Xcode project with a Playground and one or more SPM libraries imported and ready for use.

USAGE: arena [--name <name>] [--libs <libs> ...] [--platform <platform>] [--force] [--outputdir <outputdir>] [--version] [--skip-open] [--book] [<dependencies> ...]

  <dependencies>          Dependency url(s) and (optionally) version specification

  -n, --name <name>       Name of directory and Xcode project (default: SPM-Playground)
  -l, --libs <libs>       Names of libraries to import (inferred if not provided)
  -p, --platform <platform>
                          Platform for Playground (one of 'macos', 'ios', 'tvos') (default: macos)
  -f, --force             Overwrite existing file/directory
  -o, --outputdir <outputdir>
                          Directory where project folder should be saved (default: /Users/sas/Projects/Arena)
  -v, --version           Show version
  --skip-open             Do not open project in Xcode on completion
  --book                  Create a Swift Playgrounds compatible Playground Book bundle (experimental).
  -h, --help              Show help information.


Import Github repository

arena https://github.com/finestructure/Gala
➡️ Package: https://github.com/finestructure/Gala @ from(0.2.1)
🔧 Resolving package dependencies ...
📔 Libraries found: Gala
🔨 Building package dependencies ...
✅ Created project in folder 'Arena-Playground'

Using Github shorthand syntax

You can skip the protocol and domain when refereing Github projects:

arena finestructure/Gala
➡️ Package: https://github.com/finestructure/Gala @ from(0.2.1)
🔧 Resolving package dependencies ...
📔 Libraries found: Gala
🔨 Building package dependencies ...
✅ Created project in folder 'Arena-Playground'

Import local repository

arena ~/Projects/Parser
➡️ Package: file:///Users/sas/Projects/Parser @ path
🔧 Resolving package dependencies ...
📔 Libraries found: Parser
🔨 Building package dependencies ...
✅ Created project in folder 'Arena-Playground'

Import both

arena ~/Projects/Parser finestructure/Gala
➡️ Package: file:///Users/sas/Projects/Parser @ path
➡️ Package: https://github.com/finestructure/Gala @ from(0.2.1)
🔧 Resolving package dependencies ...
📔 Libraries found: Parser, Gala
🔨 Building package dependencies ...
✅ Created project in folder 'Arena-Playground'

Specifying versions

In case you want to fetch a particular revision, range of revisions, or branch, you can use a syntax similar to the one used in a Package.swift file. Here's what's supported and the corresponding package dependecy that it will create in the generated project:

  • https://github.com/finestructure/Gala@0.1.0

    .package(url: "https://github.com/finestructure/Gala", .exact("0.1.0"))

  • https://github.com/finestructure/Gala@from:0.1.0

    .package(url: "https://github.com/finestructure/Gala", from: "0.1.0")

  • "https://github.com/finestructure/Gala@0.1.0..<4.0.0"

    .package(url: "https://github.com/finestructure/Gala", "0.1.0"..<"4.0.0")

  • https://github.com/finestructure/Gala@0.1.0...4.0.0

    .package(url: "https://github.com/finestructure/Gala", "0.1.0"..<"4.0.1")

  • https://github.com/finestructure/Gala@branch:master

    .package(url: "https://github.com/finestructure/Gala", .branch("master"))

  • https://github.com/finestructure/Gala@revision:7235531e92e71176dc31e77d6ff2b128a2602110

    .package(url: "https://github.com/finestructure/Gala", .revision("7235531e92e71176dc31e77d6ff2b128a2602110"))

Make sure to properly quote the URL if you are using the ..< range operator. Otherwise your shell will interpret the < character as input redirection.

How to install Arena


You can install Arena with Homebrew:

brew install finestructure/tap/arena


You can install Arena with Mint:

mint install finestructure/arena


Last not least, you can build and install arena via the included Makefile by running:

make install

This will copy the binary arena to /usr/local/bin.

Why Arena?

Arena – Spanish for "sand" – is where you battle-test your SPM packages and sand is, well, abundant in playgrounds, isn't it? 🙂


arena was built and tested on macOS 10.15 Catalina using Swift 5.2.

Playground books created by arena should run on macOS as well as iOS. Please bear in mind that the Swift packages you import when creating playground books will need to be iOS compatible.

Note that while creating playgrounds requires macOS 10.15 and Swift 5.2, the resulting playgrounds should be supported on a wider range of operating system and compiler versions. This will mainly depend on the packages you are importing.


Stars: 276



0.18.0 - 2020-08-28 06:27:00

  • User package-dump instead of SPM dependency to parse package
  • Allow numbers in branch names (fixes #62)

0.17.0 - 2020-08-11 13:21:01

  • Fixes #58 by removing the (unreliable) automatic build step. Please ensure that you always hit ⌘+B to build the playground.

0.16.2 - 2020-06-11 07:13:28

  • add platforms to Package.swift

0.16.1 - 2020-05-02 10:59:06

  • Fixes #53 - support whitespace in output directory and local dependency paths

0.16.0 - 2020-04-20 11:03:34

  • Improved latest revision lookup (isse #48)
  • Updated to swift 5.2.2 and added swift-gen to integration tests (#33, #43)

0.15.3 - 2020-04-01 13:54:30

  • make ArenaCore library target dynamic

- 2020-03-31 09:24:10

  • bubble up manifest loading error

0.15.1 - 2020-03-28 10:56:52

  • Add ref to repo to generated playground

0.15.0 - 2020-03-27 13:59:30

  • Support ssh protocol (in general and in particular for private repos):
arena git@github.com:finestructure/parser

0.14.0 - 2020-03-27 12:07:43

  • Swift 5.2
  • Fixes #33 and #38

0.13.1 - 2020-03-22 18:05:36

  • Fixes issue #33 importing https://github.com/pointfreeco/swift-gen.git

0.13.0 - 2020-03-22 14:00:03

  • add run overload to allow easier integration with other tools
    public func run(progress: ProgressUpdate) throws


public typealias ProgressUpdate = (Progress.Stage, String) -> ()

public enum Progress {
    public enum Stage {
        case started
        case listPackages
        case resolvePackages
        case listLibraries
        case buildingDependencies
        case showingPlaygroundBookPath
        case showingOpenAdvisory
        case completed
    public static func update(stage: Stage, description: String) { print(description) }

and the default is

    public func run() throws {
        try run(progress: Progress.update)

0.12.0 - 2020-03-13 17:14:28

  • Adds some public interfaces for re-use as a library

- 2020-03-11 14:26:33

  • For packages hosted on Github, Arena now looks up the latest release if no version is specified:
arena alamofire/alamofire
➡️  Package: https://github.com/alamofire/alamofire @ from(5.0.2)
🔧  Resolving package dependencies ...
📔  Libraries found: Gala
🔨  Building package dependencies ...
✅  Created project in folder 'Arena-Playground'

This avoids getting pinned below version 1.0.0 with the from(0.0.0) default in previous versions.

0.10.0 - 2020-03-10 06:49:09

  • Support for Github shorthand
arena finestructure/gala

equivalent to

arena https://github.com/finestructure/gala

0.9.1 - 2020-03-02 14:06:19

  • Run xcodebuild on project after assembling Package.swift file
  • Change default folder name to Arena-Playground
  • Add integration test

0.9.0 - 2020-03-01 18:05:17

  • Support for the universal Swift Playground app by creating "Playground Book" files via the --book option
  • Added --skip-open flag to suppress opening Xcode

- 2020-02-28 17:22:05

  • Makefile update to support homebrew installation

0.8.0: SPMPlayground is now Arena - 2020-02-28 15:51:34

  • renamed to Arena
  • adopted swift-argument-parser library
  • dropped -d/--deps option name, i.e.

arena -d https://github.com/finestructure/Gala


arena https://github.com/finestructure/Gala

0.7.0 - 2020-02-20 17:24:55

  • Fixes import issues when library and package name differ (like for the https://github.com/apple/swift-se0270-range-set/ )

- 2020-01-07 10:00:43

  • open Xcode project instead of containing folder

- 2020-01-06 17:10:54

User facing changes

  • added -f short flag for --force (to overwrite target folder)
  • added -o / --outputdir parameter to choose project's parent folder (instead of current working directory)
  • changed -l / --libs parameter to allow listing of multiple libraries to import

Changes under the hood

  • moved parsing code to https://github.com/finestructure/Parser dependency
  • SPM dependecy changed to from:

- 2020-01-02 08:41:12

  • now support local repository imports:
spm-playground -d ~/Projects/Parser
🔧  resolving package dependencies
📔  libraries found: Parser
✅  created project in folder 'SPM-Playground'

- 2019-12-31 13:14:56

  • import multiple dependencies
  • version spec to pick revisions, branches etc:
... -d https://github.com/johnsundell/plot@0.3.0
... -d https://github.com/johnsundell/plot@from:0.1.0
... -d "https://github.com/johnsundell/plot@0.1.0..<4.0.0"
... -d https://github.com/johnsundell/plot@branch:master
... -d https://github.com/johnsundell/plot@revision:2e5574972f83bc5cdea59662986e701b86137642

- 2019-12-22 11:16:24

  • parse dependencies from package description instead of guessing from url

- 2019-12-22 11:15:43

  • fix typo
  • update README