Development

These are the tools you’ll need to get started building Swiftarr for yourself.

Swift

Swift runs on MacOS or Linux. If you are unfamiliar with the language we suggest the Codecademy Learn Swift course. It’s free and pretty quick for those who have experience with languages such as Java or C.

MacOS

Requirements

There are five requirements for either running an instance of swiftarr or development itself.

A recent version of Xcode is also required for development. (This is not strictly necessary, but if you walk your own Swift development path, add “self-sufficiency” to the list.)

Swiftarr also uses libjpeg directly, but libjpeg should get installed when installing libgd.

Quickstart - macOS

If running on macOS with Xcode installed, the easiest way to get an instance up and running is via Docker.

  1. Install Docker.
  2. Install libgd. With Homebrew installed, simply brew install gd.
  3. If you’re using an ARM-based Mac (and installed libgd using homebrew), add
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig"

to your .zshrc file to make xcodebuild find the ARM64 libs homebrew installs (in /opt/homebrew) instead of the X86 libs (in /usr/local/lib).

  1. Download or clone the swiftarr repository.
  2. Run scripts/instance.sh up -d redis postgres from the swiftarr directory to create and launch postgres and redis Docker containers.
  3. Create your own development.env in Sources/swiftarr/seeds/Private Swiftarr Config. See Configuration for details.
  4. Open the Package.swift file in Xcode and run the “Migrate” scheme to configure the databses, or from the command line:
xcodebuild -project "swiftarr.xcodeproj" -scheme "Migrate"
./DerivedData/swiftarr/Build/Products/Debug/Run migrate

You’ll be asked to approve a bunch of migrations; these mostly create database tables.

  1. Set the scheme to “Run/My Mac” in Xcode, hit Run, and swiftarr should shortly be available at http://localhost:8081. To shut down the Docker containers, scripts/instance.sh stop.

Yes, that’s a bunch the first time through and it does take some time. From here on out though, it’s just a matter of pulling the latest updates from the repository and regenerating the .xcodeproj file.

Using Xcode

One of the many Xcode quirks that confuses developers not used to it is that Xcode puts the built app and all the buildfiles in the /DerivedData folder. This happens whether you build using the app or from the command line using xcodebuild. The Copy Files script (part of the build process) copies all the Leaf templates, javascript, css, images, into /DerivedData on each build and the running app uses the copies, NOT the files in /Resources and /Seeds. But, the copy happens every build, even if no sources changed. So, while running the server, you can edit a Leaf template or some JS, hit command-B to build, reload the page, and see the changes.

Linux

Requirements

You will need to install the Swift compiler and runtime. This is probably available as a package via your system packager (swift-lang) or via https://www.swift.org/download/

After that you will likely want the following tools:

Consult their READMEs for installation.

Quickstart - Linux

If running on Linux with VSCode or in a terminal, the easiest way to get an instance up and running is via Docker.

  1. Install Docker.
  2. Install the various binary dependencies.
    • Fedora: gd-devel libjpeg-turbo-devel
    • Ubuntu: libgd-dev libjpeg-dev
  3. Download or clone the switarr repository.
  4. Run scripts/instance.sh up -d postgres redis from the repo directory to create and launch Postgres and Redis Docker containers. You can omit the postgres redis portion of the command to get additional instance containers.
  5. Build the codebase using VSCode or in a terminal with swift build. This could take a while if it’s the first time.
  6. Create your own development.env in Sources/swiftarr/seeds/Private Swiftarr Config. See Configuration for details.
  7. Perform an initial database migration. This only needs to be done once or whenever there are additional migrations to apply. swift run swiftarr migrate [--yes]. Note the two run’s with differing case.
  8. Start the app with swift run swiftarr serve and you should be greeted with a line akin to Server starting on http://127.0.0.1:8081.