# Cthulhu Development Guide

## Local Development Build

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

### Building Locally

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

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

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

### Testing the Local Build

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

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

### Running Local Cthulhu

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

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

### Cleaning Up

```bash
# 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

```bash
# 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 (`configure`, `Makefile`, etc.)
- Generated Python files (`cthulhu_bin.py`, `cthulhu_i18n.py`, etc.)
- Python bytecode (`*.pyc`, `__pycache__/`)

Before committing:
```bash
# 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**: autotools, gettext, intltool
- **Optional**: dasbus (for D-Bus service), BrlTTY, speech-dispatcher

Install build dependencies on Arch Linux:
```bash
sudo pacman -S autoconf automake intltool gettext python-dasbus
```