SwatPhonLab · keggsmurph21 · Oct 22, 2022 · Oct 22, 2022 · Oct 22, 2022 · Oct 22, 2022
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -1,11 +1,96 @@
-version: 2
+version: 2.1
+
+commands:
+  install-and-check:
+    parameters:
+      python:
+        type: string
+
+    steps:
+      - run:
+          name: upgrade pip and friends
+          command: |
+            << parameters.python >> -m pip install \
+                pip==22.3 \
+                setuptools==65.5.0 \
+                wheel==0.38.0
+
+      - run:
+          name: install ultratrace
+          command: |
+            << parameters.python >> -m pip install \
+                --requirement ./requirements-dev.txt
+
+      - run: nox
+
 jobs:
-  build:
+  ubuntu:
     docker:
-      - image: circleci/python:3.7.2
+      - image: ubuntu:18.04
     steps:
       - checkout
-      - run: ./install.sh
-      - run: sudo pip install boto3 mypy_boto3_s3 nox
-      - run: ./scripts/download-test-data
-      - run: nox
+
+      - run:
+          name: install system packages
+          command: |
+            export DEBIAN_FRONTEND=noninteractive
+            apt-get update
+            apt-get install --yes \
+                portaudio19-dev \
+                python3.8 \
+                python3.8-dev \
+                python3.8-venv \
+                python3-pip \
+                python3-tk
+
+      - install-and-check:
+          python: python3.8
+
+  fedora:
+    docker:
+      - image: fedora:35
+    steps:
+      - checkout
+
+      - run:
+          name: install system packages
+          command: |
+            dnf --assumeyes install \
+                https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
+                https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
+            dnf --assumeyes update
+            dnf --assumeyes install \
+                gcc \
+                portaudio-devel \
+                python3-devel \
+                python3-tkinter \
+                python3-pip
+
+      - install-and-check:
+          python: python3.10
+
+  macos:
+    macos:
+      xcode: 13.2.1  # latest for Big Sur
+    environment:
+      # https://circleci.com/docs/using-macos/#optimizing-homebrew
+      HOMEBREW_NO_AUTO_UPDATE: 1
+    steps:
+      - checkout
+
+      - run:
+          name: install system packages
+          command: |
+            brew install \
+                portaudio \
+                python-tk@3.9
+
+      - install-and-check:
+          python: python3.9
+
+workflows:
+  main:
+    jobs:
+      - ubuntu
+      - fedora
+      - macos
diff --git a/.flake8 b/.flake8
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,7 @@ data
 
 # or virtualenv/pipenv files
 Pipfile*
+venv
 
 # python caches
 __pycache__
@@ -17,5 +18,9 @@ __pycache__
 .nox
 .coverage
 
+# build artifacts
+build/
+*.egg-info
+
 # local environment setup
 .env
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
 # UltraTrace
+
 This is a tool for [currently] manual annotation of 2D UTI (Ultrasound Tongue Imaging) data.
 
 You can have a look at our [UltraFest IX presentation](https://swatphonlab.github.io/2020-UltraTrace-presentation/presentation.html) for some details on featureset and functionality as of October, 2020.
@@ -8,39 +9,89 @@ You can have a look at our [UltraFest IX presentation](https://swatphonlab.githu
 
 ## Installation
 
-### Linux (apt or dnf)
+This tool requires the following system packages to be installed:
+
+* [`portaudio`](http://www.portaudio.com/)
+* [`python3`](https://www.python.org/) (3.7 or later)
+
+Additionally, you'll need the following Python components (which are sometimes distributed separately):
+
+* [Python development headers](https://devguide.python.org/getting-started/setup-building/#install-dependencies)
+* [`pip`](https://pypi.org/project/pip/)
+* [`tkinter`](https://docs.python.org/3/library/tkinter.html)
+* [`venv`](https://docs.python.org/3/library/venv.html)
 
-1. Download the UltraTrace source code, e.g. using `git`.
-2. Run setup in the UltraTrace directory:
-```bash
-$ ./install.sh
-$ python3 setup.py install
+See below for platform-specific installation instructions:
+* [Ubuntu](#ubuntu)
+* [Fedora](#fedora)
+* [macOS](#macos)
+* [Windows](#windows)
+
+Once these libraries are installed, you can just `pip install` the package with
+
+```sh
+$ python3 -m pip install -r ./requirements.txt
 ```
 
-### macOS
+NOTE: For hacking on `ultratrace` itself, see [Development](#development) below.
 
-1. Install [Homebrew](https://brew.sh).
-2. Download the UltraTrace source code, e.g. using `git`.
-3. Use Homebrew to install python3:
-```bash
-$ brew install python3
+NOTE: You probably want to install into a [virtual environment](https://docs.python.org/3/tutorial/venv.html) to avoid conflicts with system packages.  Alternatively, you can do a [`--user` installation](https://pip.pypa.io/en/latest/user_guide/#user-installs).
+
+### Ubuntu
+
+Supported versions: 18.04, 20.04
+
+```sh
+$ apt-get update
+$ apt-get install --yes \
+    portaudio19-dev \
+    python3.8 \
+    python3.8-dev \
+    python3.8-venv \
+    python3-pip \
+    python3-tk
 ```
-4. Run setup in the UltraTrace directory:
-```bash
-$ python3 setup.py install
+
+### Fedora
+
+Supported versions: 35, 36, 37
+
+```sh
+$ dnf --assumeyes install \
+    https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
+    https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
+$ dnf --assumeyes update
+$ dnf --assumeyes install \
+    gcc \
+    portaudio-devel \
+    python3-devel \
+    python3-tkinter \
+    python3-pip
+```
+
+### macOS
+
+Supported versions: Big Sur, Monterey
+
+These instructions use the [Homebrew](https://brew.sh) package manager.
+
+```sh
+$ brew update
+$ brew install \
+    portaudio \
+    python-tk@3.9
 ```
 
 ### Windows
 
-1. Install python3
-2. Make sure you have pip
-3. Install ffmpeg and add to PATH
-4. Run `setup.py`
+TODO
+
+## Usage
 
-## Use
+Once [installed](#installation), you can just run
 
-```bash
-$ python3 -m ultratrace /path/to/data
+```sh
+$ ultratrace path/to/data
 ```
 
 ### Data format
@@ -72,14 +123,31 @@ The theme should just look right on Mac.
 
 #### Setting the theme on linux
 
-Use pip3 to install ttkthemes.
+We use [`ttkthemes`](https://ttkthemes.readthedocs.io/en/latest/).
 
 Add the following line to your `~/.Xresources` file:
-
 ```
 *TtkTheme: arc
 ```
 
 You may select something other than clam for your theme.  Currently, the main options are something like this: `arc`, `plastik`, `clearlooks`, `elegance`, `radiance`, `equilux`, `black`, `smog`, `scidblue`, etc.  See the [ttkthemes documentation](https://ttkthemes.readthedocs.io/) for more information.
 
 Otherwise it'll fall back to `*TtkTheme`, and if that's not specified in `~/.Xresources`, it'll fall back to `clam`.
+
+## Development
+
+To hack on `ultratrace`, you should first [install all required system libraries](#installation).  Then, you can set up a development environment by running
+
+```sh
+$ source dev/env.sh
+```
+
+To lint/test `ultratrace`, use [`nox`](https://nox.thea.codes/en/stable/):
+```sh
+$ nox --help
+```
+
+To exit the development environment, just run
+```sh
+$ deactivate
+```
diff --git a/bin/install b/bin/install
diff --git a/bin/ultratrace b/bin/ultratrace
diff --git a/dev/env.sh b/dev/env.sh
@@ -0,0 +1,30 @@
+#!/bin/bash
+#
+# Set up a development environment for 'ultratrace'.
+#
+# Note that since this script is meant to be "source"d, we can't use
+# the "set -euo pipefail" idiom (since that means that we would set
+# those shell options in our host environment (this would cause bash
+# to exit if we ran any command returning a non-zero exit code)).
+
+export ULTRATRACE_ROOT="$(git rev-parse --show-toplevel)"
+export ULTRATRACE_VENV="$ULTRATRACE_ROOT/venv/ultratrace"
+export ULTRATRACE_PYTHON="${ULTRATRACE_PYTHON:-python3}"
+
+# Create a virtual environment if we don't already have one.
+if [ ! -e "$ULTRATRACE_VENV/bin/activate" ]; then
+    echo "Creating a virtual environment at '$ULTRATRACE_VENV'" >&2
+    rm -rf "$ULTRATRACE_VENV"
+    "$ULTRATRACE_PYTHON" -m venv "$ULTRATRACE_VENV"
+fi
+
+# Activate the virtual environment.
+source "$ULTRATRACE_VENV/bin/activate"
+
+pip install --upgrade \
+    pip==22.3 \
+    setuptools==65.5.0 \
+    wheel==0.38.0
+
+pip install \
+    --requirement "$ULTRATRACE_ROOT/requirements-dev.txt"