docs/makefile_usage.md

Makefile Usage Guide 🛠️

This guide explains how to use the Makefile in this repository to automate the setup, environment checks, and running the application. The Makefile simplifies complex tasks and ensures you have all necessary dependencies.

---

⚙️ How to Install make

If the make command is not found on your system, follow the instructions for your OS:

Windows

• Chocolatey (Recommended): choco install make
• Winget: winget install GnuWin32.Make
• MSYS2: pacman -S make
• Git Bash: make is often included with "Git for Windows SDK". Alternatively, download make.exe from a trusted source and add it to your PATH.

macOS

• Homebrew: brew install make
• Xcode Tools: Run xcode-select --install in your terminal. This will install a suite of developer tools including make.

Linux

• Ubuntu/Debian: sudo apt update && sudo apt install make
• Arch Linux: sudo pacman -S make
• Fedora: sudo dnf install make

---

📋 Quick Reference

Command	Description
make check	Check system toolchain (Python, uv, eSpeak, Docker, GPU, .env, etc.)
make setup-gpu	Full setup for GPU (Interactive dependency check + uv sync)
make setup-cpu	Full setup for CPU (Interactive dependency check + temporary dependency swap)
make demo	Run the Gradio UI application
make docker-gpu	Start Docker environment with GPU support
make docker-cpu	Start Docker environment for CPU only
make uv	Install or update uv package manager
make espeak	Install or guide for installing eSpeak NG
make clean	Clean up build artifacts, .venv, and caches

---

🔍 Detailed Command Guide

1. make check

The environment investigator. Run this first to see what's missing on your system.

• Checks Python version (≥ 3.12 required).
• Detects your GPUs (NVIDIA, Intel, AMD).
• Checks for uv, eSpeak NG, Docker, and .env file.
• Color-coded output: [OK] (Green), [WARNING] (Yellow), [ERROR] (Red/Fatal).

2. make setup-gpu / make setup-cpu

Automated setup with interactive dependency checks.

• Before installing Python packages, it verifies python, uv, and eSpeak NG.
• Interactive Prompts: If a tool is missing, it will ask if you want to install it.
  • Windows: Guidance for manual downloads or winget.
  • macOS: Uses brew.
  • Linux: Uses apt or pacman.
• Fail-Fast: If critical dependencies are missing and not installed, it stops immediately to prevent broken environment states.

3. make uv / make espeak

Standalone installation targets for the core toolchain.

• make uv: Runs the official installation script for your OS.
• make espeak: Tries automated installation (Winget/Brew/Apt) or provides direct download links.

4. make demo

Once setup is complete, use this to launch the Gradio web interface. It uses uv run to ensure it uses the correct virtual environment.

5. make docker-gpu / make docker-cpu

Simplified Docker commands.

• Automatically handles the creation of a .env file from .env.example if it's missing.
• Sets the appropriate Docker profile for your detected hardware.

---

💻 OS Support

The Makefile is designed to be cross-platform and has been tested on:

• Windows: (via Git Bash / MSYS2)
• macOS: (Intel and Apple Silicon)
• Linux: (Ubuntu, Debian, Arch Linux)

---

🧹 Cleaning up

If you need to reset your environment or clear disk space:

make clean

This removes .venv, __pycache__, and other temporary files.