Improve installation instructions

docs/installation/macos.md

@@ -0,0 +1,106 @@
+# Installation
+
+Of the Pepper Robot Interface on macOS.
+
+
+
+## Python 2.7
+
+Install Python 2.7.18 from the [Python website](https://www.python.org/downloads/release/python-2718/).
+
+Check that it worked by executing
+
+```shell
+python2 -V
+```
+
+Which should return Python 2.7.18.
+
+
+
+## Virtual Environment
+
+Next, cd into this repository and create (and activate) a virtual environment:
+
+```shell
+cd /path/to/project/
+python2 -m pip install virtualenv
+python2 -m virtualenv .venv
+source .venv/bin/activate
+```
+
+We depend on PortAudio for the `pyaudio` package. If on Intel, run `brew install portaudio`. If on Apple Silicon, compile manually using the steps described in [the YouTrack article](https://utrechtuniversity.youtrack.cloud/articles/N25B-A-22/Install-PyAudio-for-Python-2-on-Apple-Silicon).
+
+Then install the required Python packages with
+
+```shell
+pip install -r requirements.txt
+```
+
+
+
+## NaoQi SDK
+
+We need to manually install the NaoQi SDK into our virtual environment. There are two options:
+
+1. Install a newer version (2.8) which will make running easier, but compatibility is uncertain.
+2. Install the version expected by the robot (2.5). This will complicate running slightly.
+
+### Option 1
+
+Download the SDK from [twirre.io](https://twirre.io/files/pynaoqi-python2.7-2.8.6.23-mac64-20191127_144231.tar.gz), or find one on the Aldebaran website, or an archived version on Web Archive.
+
+Extract it to `/path/to/project/.venv/lib/python2.7/site-packages/`.
+
+We need to inform our virtual environment where to find our newly installed package:
+
+```bash
+echo "/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.8.6.23-mac64-20191127_144231/lib/python2.7/site-packages/" > /path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7.pth
+```
+
+Now continue with [verifying](#verifying).
+
+### Option 2
+
+This method of installation requires setting the `DYLD_LIBRARY_PATH` environment variable before running. How will be explained.
+
+Download the SDK from [twirre.io](https://twirre.io/files/pynaoqi-2.5.7.1-mac64-deps.tar.gz). This is a modified version of the one from Aldebaran, this one including required Choregraphe dependencies.
+
+Extract it to `/path/to/project/.venv/lib/python2.7/site-packages/`.
+
+We need to inform our virtual environment where to find our newly installed package:
+
+```shell
+echo "/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.5.7.1-mac64/lib/python2.7/site-packages/" > /path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7.pth
+```
+
+Now, anytime before running you need to set the `DYLD_LIBRARY_PATH` environment variable.
+
+```shell
+export DYLD_LIBRARY_PATH="/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.5.7.1-mac64/choregraphe_lib:${DYLD_LIBRARY_PATH}"
+```
+
+You may want to simplify environment activation with a script `activate.sh` like:
+
+```shell
+#!/bin/zsh
+
+export DYLD_LIBRARY_PATH="/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.8.6.23-mac64-20191127_144231/choregraphe_lib:${DYLD_LIBRARY_PATH}"
+source .venv/bin/activate
+```
+
+[Verify](#verifying) if it works.
+
+
+
+## Verifying
+
+Verify that the NaoQI SDK installation works with
+
+```bash
+python -c "import qi; print(qi)"
+```
+
+If so, you should now be able to run this project.
+
+See the README for how to run.