Building and Packaging

Building and Packaging Guide

This guide explains how to set up a development environment, run the test suite, build standalone binaries, and produce distribution packages for Linux and Windows.

---

🛠️ Development Environment Setup

Mastui uses Poetry for dependency management and packaging.

Prerequisites

• Python 3.9 or newer (Python 3.11/3.12 recommended)
• Git
• Poetry (pip install poetry or pipx install poetry)

Clone and Install

git clone https://github.com/kimusan/mastui.git
cd mastui

# Install dependencies in an isolated virtual environment
poetry install

Running Mastui in Development

# Launch Mastui in standard TUI mode
poetry run mastui

# Launch with verbose debug logging (press F12 in-app to view logs)
poetry run mastui --debug

# Launch in Web Interface mode
poetry run mastui --web

---

🧪 Testing and Code Quality

Always ensure tests pass and code is formatted before submitting pull requests:

# Run pytest test suite
poetry run pytest

# Run specific test file
poetry run pytest tests/test_web.py

# Check code style with Ruff
poetry run ruff check .

# Auto-format sources with Ruff
poetry run ruff format .

---

📦 Building Distribution Packages

Mastui includes an automated packaging tool scripts/build_packages.py that generates standalone executables and distro packages using PyInstaller.

PyInstaller Spec File (mastui.spec)

The standalone executable bundles Python runtime, Textual, dependencies, and project assets (CSS files, logo):

• Bundles mastui/mastui.tcss into the binary.
• Configures proper hidden imports for textual_image, PIL, html2text, etc.

Building All Linux Packages

To build all Linux formats (.deb, .rpm, .AppImage, Arch .pkg.tar.zst, and SHA256SUMS.txt):

poetry run python scripts/build_packages.py --all-linux

Generated artifacts are placed in the dist/ directory:

• dist/mastui (Standalone ELF executable)
• dist/mastui_<version>_amd64.deb (Debian/Ubuntu package)
• dist/mastui-<version>-1.x86_64.rpm (RedHat/Fedora/openSUSE package)
• dist/mastui-<version>-x86_64.AppImage (Universal Linux AppImage)
• dist/mastui-<version>-1-x86_64.pkg.tar.zst (Arch Linux package)
• dist/SHA256SUMS.txt (Cryptographic SHA-256 verification sums)

Building Individual Target Packages

# Standalone binary only (dist/mastui)
poetry run python scripts/build_packages.py --target binary

# Debian package (.deb) - requires dpkg-deb on host
poetry run python scripts/build_packages.py --target deb

# RPM package (.rpm) - requires rpmbuild on host
poetry run python scripts/build_packages.py --target rpm

# AppImage (.AppImage) - auto-downloads appimagetool if not found
poetry run python scripts/build_packages.py --target appimage

# Arch Linux package (.pkg.tar.zst) - requires tar and zstd
poetry run python scripts/build_packages.py --target arch

# Windows ZIP bundle (.zip) - run from Windows host
poetry run python scripts/build_packages.py --target windows

# Re-generate SHA256 checksums
poetry run python scripts/build_packages.py --target checksums

---

🚀 Continuous Integration & Release Automation

Mastui uses GitHub Actions for automated testing and releases:

• .github/workflows/ci.yml: Runs on every push and pull request across Linux, macOS, and Windows to execute ruff check and pytest.
• .github/workflows/release.yml: Triggers whenever a version tag (v*.*.*) is pushed:
  1. Builds native Linux distribution packages on ubuntu-latest.
  2. Builds Windows .zip binary bundle on windows-latest.
  3. Computes unified SHA256SUMS.txt.
  4. Automatically extracts changelog section from CHANGELOG.md.
  5. Publishes a GitHub Release with all binary assets attached.
  6. Publishes Python wheels and sdist to PyPI.