Cthulhu Development Guide

This document applies to the Cthulhu fork maintained by Storm Dragon. Cthulhu is forked from Orca; prior Orca maintainers and contributors are part of the upstream history, but they are not current maintainers of this fork.

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

Make changes to the code
Build locally: ./build-local.sh
Test: ./test-local.sh
Run: ~/.local/bin/cthulhu
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, tomlkit, AT-SPI2
Build: meson, ninja, gettext
Optional: dasbus (for D-Bus service), BrlTTY, speech-dispatcher, piper-tts

Install build dependencies on Arch Linux:

sudo pacman -S meson ninja gettext python-dasbus python-tomlkit

2.7 KiB Raw Blame History