Running and Building Chirplab

Running from source

Chirplab has a handful of system-level and PyPI package dependencies

• Python 3.10+
• SoX
  • If SoX is not found on the PATH on Windows, Chirplab will prompt the user if they want to download SoX from SourceForge and keep the binaries in a Chirplab subfolder
  • SoX is readily available on most Unix-based OS package management systems. e.g apt install sox on Linux or brew install sox on Mac.
• PortAudio
  • The pyaudio Python package works without any other dependencies on Windows
  • On Linux, apt install portaudio19-dev
  • On Mac, brew install portaudio

It is recommended to run Chirplab from and install python packages to a virtual environment

python -m venv venv
.\venv\Scripts\activate

The main Chirplab code and pip requirements.txt are located in the src folder.

cd src
pip install -r requirements.txt

Chirplab uses qtpy to automatically use whichever Python Qt bindings you have installed. Chirplab is developed, releases are built, and the requirements.txt file use PyQt5, but you should be able to use another binding like PySide6 with little to no changes to the Chirplab code.

Finally, once all the dependencies are installed:

python chirplab.py

Building

Chirplab releases are built using PyInstaller, which should be the only additional package that is needed to bundle an executable on your native OS. The CI/release build process GitHub workflow uses WINE on Ubuntu, which has an additional dependency of pywin32. Both packages are included in build\requirements.txt

A PyInstaller .spec file (build\chirplab.spec) is preconfigured to bundle Chirplab along with the examples folder in the repo. The .spec file prioritizes startup time over file clutter, so it does not use the onedir flag.

Due to a bug in the Windows 11 terminal, the .spec file is configured to launch the GUI with a console window, which is hidden as soon as the actual Chirplab python code starts. You can uncomment the console=False flag to keep the console from showing when launching the GUI, but the executable won't send any output to the console, which means the command-line interface won't generate any output and error messages from the GUI can't be captured in the console.

To bundle Chirplab:

cd build
pyinstaller chirplab.spec

The bundling process will output chirplab.exe, the PyInstaller _internal folder, and the examples folder to build\dist\chirplab\