Development Guide

These instructions apply to the final Python v0.9.1 source, not the Rust checkout. Clone the archived tag into a separate directory before using the commands below:

git clone --branch v0.9.1 https://github.com/youtube-at-vach/MeasureLab.git MeasureLab-python
cd MeasureLab-python

Overview

Instructions for running from source code and setting up the development environment.

🐍 Running from Source Code

[!IMPORTANT] Python 3.12 or higher

🚀 Automated Setup Script (Recommended)

For Linux (with apt) and macOS environments, we provide a convenient script that automates everything from installing OS packages to creating a virtual environment (.venv) and installing necessary Python dependencies, Node.js, and other development tools.

Simply open your terminal and run the following command in the repository root directory:

./scripts/setup_dev_env.sh

On Linux systems without apt (for example, Gentoo) or where admin privileges are unavailable, the script skips OS package auto-install, prints manual dependency guidance, and continues with venv/pip setup. During execution on macOS, you may be prompted to confirm default settings for MacPorts.

Once the setup is complete, activate the virtual environment and launch the application using the following commands:

source .venv/bin/activate
python main_gui.py

🛠️ Manual Setup

If you prefer not to use the automated script and want to set up the environment manually, please follow the instructions below.

Linux / Ubuntu: Manual Virtual Environment (venv) Setup

While the release versions (AppImage/ZIP) work as is, when running from source code, APT (OS package) Python dependencies (e.g., PyQt6) might be too old to work. Therefore, on Linux, it is recommended to use the system Python but install dependent packages using venv + pip.

Install OS dependent libraries (minimum requirements).
- sounddevice uses PortAudio, so libportaudio2 is required at runtime.
- soundfile uses libsndfile, so libsndfile1 is required at runtime.
```
sudo apt update
sudo apt install -y python3 python3-venv python3-pip libportaudio2 libsndfile1
```
Only if you encounter build errors with pip install, install additional development headers:
```
sudo apt install -y build-essential portaudio19-dev libsndfile1-dev
```

Create and activate a virtual environment (e.g., .venv under the repository root).

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

From here on, python / pip refer to the venv (do not use sudo pip).

If you want to run without using activate, you can always call the venv Python directly:

./.venv/bin/python -m pip install -U pip
./.venv/bin/python -m pip install -c constraints.txt -r requirements.txt
./.venv/bin/python main_gui.py

Clone the repository.
Install dependencies (use constraints for reproducibility):
```
pip install -c constraints.txt -r requirements.txt
```
Launch the application:
```
python main_gui.py
```

macOS: Using MacPorts + Python 3.12 + pyFFTW

(Verified on macOS 13 or later)

When installing pyFFTW on macOS, you need to explicitly specify the FFTW library installed via a package manager (MacPorts recommended).

Update MacPorts and install required packages:

sudo port selfupdate
sudo port install python312 py312-pip fftw-3 fftw-3-single

Select Python version:

sudo port select --set python python312
sudo port select --set python3 python312

Restart the terminal after configuration.

Create and activate a virtual environment:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

Install pyFFTW (Explicitly specifying the FFTW path):

python -m pip cache remove pyfftw
PYFFTW_FFTW_PREFIX=/opt/local \
python -m pip install pyfftw --no-binary pyfftw

Install dependent packages:

python -m pip install -c constraints.txt -r requirements.txt

🛠️ Development Setup

If you want to run tests, Lint/type checks, or build the documentation, install the additional packages.

Code Development (Tests/Lint, etc.):
```
pip install -c constraints.txt -e ".[dev]"
```
- If you are using zsh, you need to enclose .[dev] in quotes (e.g., ".[dev]").

Documentation Development (MkDocs):

pip install -c constraints.txt -r requirements-docs.txt

Lint: ruff check .
Format check: ruff format --check . Do not normally run ruff format . across the repository. If the check fails, first verify whether the failure is in a file changed by the current work, then format only the necessary changed files.
Type check: mypy src
Tests: pytest (Hardware/GUI dependent tests require environment variables; skipped by default in CI)

🤖 Development Skill Extensions

The MeasureLab project provides project-level skill extensions (Slash Commands) to automate and assist with development workflows. These can be used via MCP-compatible tools like GitHub Copilot CLI.

/ci-prechecker: Runs Ruff (Lint), Mypy (Type check), translation key consistency checks, Markdown Lint, and Pytest locally to pre-verify CI requirements before creating a PR.
/multilingual-translator: Checks the consistency of translation files across the project, automatically adding missing keys and performing final verification of translations.
/pr-reviewer: Fetches code changes from a Pull Request and automatically performs a code review focusing on logic correctness, style, tests/documentation, and CI/safety.
/release-manager: Assists with release preparation, including updating the CHANGELOG, checking documentation, synchronizing version numbers, updating screenshots for UI changes, and creating release PRs.

For detailed specifications and usage of each skill, please refer to the Markdown files under the .github/extensions/ directory in the repository.

Building the Windows installer

See Windows packaging and builds (Japanese) for the packaging decision, Inno Setup build commands, data preservation, and installer lifecycle checks in CI.