cthulhu/README-DEVELOPMENT.md

Cthulhu Development Guide

Local Development Build

To develop Cthulhu without overwriting your system installation, use the provided build scripts:

Building Locally

# Build and install to ~/.local
./build-local.sh

# Clean build and rebuild everything
./clean-local.sh --build-only
./build-local.sh

This installs Cthulhu to ~/.local/bin/cthulhu without touching your system installation.

Testing the Local Build

# Test the local installation
./test-local.sh

# Run the local version directly
~/.local/bin/cthulhu --version

Running Local Cthulhu

# Method 1: Direct path
~/.local/bin/cthulhu

# Method 2: Add to PATH (add to ~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"
cthulhu

Cleaning Up

# Clean build artifacts only
./clean-local.sh --build-only

# Remove local installation only  
./clean-local.sh --install-only

# Clean everything (build artifacts + local installation)
./clean-local.sh

D-Bus Remote Controller

Cthulhu now includes a D-Bus service for remote control:

• Service: org.stormux.Cthulhu.Service
• Path: /org/stormux/Cthulhu/Service
• Requires: dasbus library (should be installed)

Testing D-Bus Service

# Start Cthulhu with D-Bus service
~/.local/bin/cthulhu

# In another terminal, test the service
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service org.stormux.Cthulhu.Service GetVersion

# Present a message via D-Bus
busctl --user call org.stormux.Cthulhu.Service /org/stormux/Cthulhu/Service org.stormux.Cthulhu.Service PresentMessage s "Hello from D-Bus"

Development Workflow

1. Make changes to the code
2. Build locally: ./build-local.sh
3. Test: ./test-local.sh
4. Run: ~/.local/bin/cthulhu
5. Clean when done: ./clean-local.sh --build-only

Git Repository Management

The .gitignore file is configured to exclude:

• Build artifacts (_build, _build_releasecheck, meson-private, etc.)
• Generated Python files (cthulhu_bin.py, cthulhu_i18n.py, etc.)
• Python bytecode (*.pyc, __pycache__/)

Before committing:

# Clean build artifacts to avoid committing them
./clean-local.sh --build-only

# Check what will be committed
git status

Dependencies

• Runtime: python3, pygobject-3.0, pluggy, AT-SPI2
• Build: meson, ninja, gettext
• Optional: dasbus (for D-Bus service), BrlTTY, speech-dispatcher

Install build dependencies on Arch Linux:

sudo pacman -S meson ninja gettext python-dasbus