# Development and build notes

## Local development

Mudmouth requires Rust stable. On NixOS, the included shell also provides the
ALSA development metadata used by the Linux audio backend:

```bash
nix-shell
```

Run the normal validation suite before submitting a change:

```bash
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --release
```

Run a test build

```sh
nix develop --command cargo run --release --bin mudmouth
```

## Refreshing the PEQ NPC gender index

The checked-in `generated/peq-npc-gender-index.json` is generated data, not a
runtime database dependency. Regenerate it from an explicit ProjectEQ dump
with the tool below; it reads either `create_tables_content.sql` directly or
the `peq-dump/create_tables_content.sql` member of the supplied zip archive.
`unzip` is available in `shell.nix` for the latter.

```bash
cargo run --bin generate_peq_npc_index -- \
  --dump "$HOME/Downloads/peq-1759046415.zip" \
  --output generated/peq-npc-gender-index.json
```

The tool prints its input identity, complete conflict/neuter statistics, and
output size. Run it twice and compare the output hashes before updating the
checked-in artifact. The source archive and any temporary database files must
not be committed or included in release archives.

The parser tests cover the observed log formats, including NPC dialogue,
channel-chat exclusion, zone events, normalization, persistent/random speaker
voice policies, log truncation, and first-run log discovery.

## Running locally

Start the local Kokoro FastAPI service when necessary, then pass an EverQuest
log directly:

```bash
doas systemctl start podman-kokoro-fastapi.service
cargo run --release -- --log "$HOME/Games/EverQuestLegends/Logs/eqlog_Pleb_oggok.txt"
```

Starting without a log path opens first-time setup. Mudmouth scans common Steam
and Daybreak install folders for `eqlog_*.txt` files and lets you choose a
character; if it finds none, enter the EverQuest game directory. Use `[r]` to
rescan after enabling `/log on` in EverQuest. You can also change the log path
and Kokoro endpoint from **Settings**:

```bash
cargo run --release
cargo run --release -- --kokoro-url http://127.0.0.1:8880
```

## Release builds

Build Linux and Windows binaries locally with `release.nix`, then package them
with:

```bash
nix-build release.nix -A linux -o result-linux
nix-build release.nix -A windows -o result-windows
./scripts/package-release.sh \
  --linux result-linux/bin/mudmouth \
  --windows result-windows/bin/mudmouth.exe
```

The packager writes platform-qualified archives and `SHA256SUMS.txt` to
`dist/`. It also writes `SIZE-REPORT.txt`, recording the generated PEQ index,
the two executables, and both final archives in bytes. Before writing the
checksums, the packager verifies that each archive contains exactly its binary,
`README.md`, `LICENSE`, and `config.toml`. This excludes PEQ dumps, SQL/fixture
inputs, MariaDB data, the generator, and all source files from releases.

Keep the size report with the release/change description. When changing the
embedded index encoding, compare its archive sizes against the previous report
and record the Linux `.tar.gz` and Windows `.zip` deltas. Do not add an archive
size threshold until a stable release baseline has been established.

### PEQ index size audit — 2026-07-29

The following release builds compare pre-PEQ commit `561ace9` with the current
core mapping implementation (tasks 1–4). The after size includes the embedded
index and its resolver code.

| Artifact | Before | After | Delta |
| --- | ---: | ---: | ---: |
| Generated index | 0 B | 719,199 B | +719,199 B |
| Linux executable | 6,772,856 B | 7,535,632 B | +762,776 B |
| Linux `.tar.gz` | 2,871,605 B | 3,010,723 B | +139,118 B |
| Windows executable | 6,577,369 B | 7,332,144 B | +754,775 B |
| Windows `.zip` | 2,805,692 B | 2,944,841 B | +139,149 B |

Both archives were inspected after packaging and contained only the platform
binary, `README.md`, `LICENSE`, and `config.toml`. The compressed distribution
cost is about 139 KB per platform; retain the JSON encoding until a future
measurement establishes a material reason to optimize it.

`scripts/publish-release.sh` uploads the archive assets and checksums as a
Gitea pre-release after the worktree is committed and clean.