running-playscii-on-macos.md

Running Playscii on macOS

Date: Apr 15, 2023

This document describes how I got Playscii running on macOS using the following setup:

• Playscii 9.17.1
• Python 3.11.3
• macOS Ventura 13.2.1
• MacBook Air (M1)

These notes are mostly a rehash of other existing instruction, in particular:

• "MacOS local development notes" by Michael Lazar
• This issue comment by Brian Knoles

We diverge from these mainly by using pip-tools to refresh the dependencies. Note that by doing so we assume that Playscii is compatible with the latest versions of the dependencies. It worked well today, but it could potentially break in the future.

Instructions

Install the following packages with Homebrew:

brew install python3 sdl2 sdl2_mixer libjpeg libtiff

Download the source distribution from Playscii's Itch.io page and unzip it into a folder.

cd path/to/playscii

Create a virtual environment and activate it:

python3 -m venv venv

source venv/bin/activate

Install pip-tools into the virtual environment:

python3 -m pip install pip-tools

Rename the requirements.txt files as requirements.in and remove the version constraints from the depencies. The contents of the file should look something like this:

appdirs
gprof2dot
numpy
Pillow
PyOpenGL
PySDL2

Use pip-tools to generate an updated requirements.txt file:

pip-compile

Install the dependencies into the virtual environment:

pip-sync

List the dynamic library files for the SDL and SDL Mixer to find the relevant library directories:

brew list sdl2 sdl2_mixer | grep dylib

Set the environment variable PYSDL2_DDL_PATH to point to these directories:

export PYSDL2_DLL_PATH="/opt/homebrew/Cellar/sdl2/<version>/lib:/opt/homebrew/Cellar/sdl2_mixer/<version>/lib"

Test that SDL works:

python3 -c 'import sdl2; print("ok")'

Start Playscii:

python3 playscii.py