rrt/docs/setup-workstation.md

# Workstation Setup

This project targets a Linux host with Wine. The current workspace is a Debian unstable machine with
`python3`, `cargo`, `wine`, `winedbg`, `gdb`, `objdump`, `llvm-objdump`, `strings`, and Java already
present.

## Current Local State

- Ghidra install: `~/software/ghidra`
- Ghidra launcher: `~/software/ghidra/ghidraRun`
- Current Ghidra status: launches successfully in an interactive shell
- Rizin binaries: `/usr/local/bin/rizin`, `/usr/local/bin/rz-bin`, `/usr/local/bin/rz-asm`
- Project Wine prefix: `rt3_wineprefix/`
- Current prefix architecture marker: `win64`
- Preferred Wine runtime: `/opt/wine-stable/bin/wine` (`wine-11.0`)
- Current runtime status: `winedbg` works with the project prefix and RT3 launches under Wine 11 when
  started from the install directory

## Required Baseline

- Linux host with Wine capable of running the RT3 install in `rt3_wineprefix/`
- A Wine setup that can run 32-bit Windows targets through the chosen prefix
- Java 21+ for Ghidra
- Python 3.13+ with `venv`
- Rust toolchain for the long-term rewrite, validation CLI, and hook DLL
- Binutils / LLVM CLI tools for quick inspection
- 32-bit MinGW linker support for `i686-pc-windows-gnu`

## Preferred Reverse-Engineering Stack

- Ghidra as the primary GUI disassembler/decompiler
- Rizin as the secondary CLI-first analysis stack
- Existing system tools for quick checks: `objdump`, `llvm-objdump`, `strings`, `gdb`, `winedbg`

## Install Policy

- Prefer upstream Ghidra releases over distro packages on this host.
- Prefer upstream Rizin releases or source builds on this host.
- Do not commit tool project databases or local installs into the repo.
- Commit only exported analysis outputs that can be regenerated.

## Local Python Environment

Create a repo-local virtual environment for committed helper scripts and quick experiments:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -V
```

Start stdlib-only when possible. Add a dependency manifest only when a non-stdlib package becomes
necessary.

## Rust Toolchain

This host uses a user-local Rust install. Source it before running cargo or rustup:

```bash
. ~/.local/share/cargo/env
cargo --version
rustup target list --installed
```

The workspace expects:

- `x86_64-unknown-linux-gnu` for host tools such as `rrt-cli`
- `i686-pc-windows-gnu` for the `rrt-hook` DLL

The current missing piece on this host is the 32-bit linker driver. Install `i686-w64-mingw32-gcc`
and keep the workspace linker config pointed at that binary.

## Suggested Host Layout

- Ghidra install: `~/software/ghidra/`
- Rizin install: system package path such as `/usr/local/bin/`
- Repo-local Python environment: `.venv/`
- Local Ghidra projects: `ghidra_projects/` in the repo root or a sibling workspace

## Basic Verification

These commands should work before starting analysis:

```bash
java -version
/opt/wine-stable/bin/wine --version
objdump --version | head -n 1
llvm-objdump --version | head -n 1
python3 -m venv --help >/dev/null
```

Rust-specific verification:

```bash
. ~/.local/share/cargo/env
cargo test -p rrt-model -p rrt-cli
cargo build -p rrt-hook --target i686-pc-windows-gnu
```

If the hook build fails with `linker i686-w64-mingw32-gcc not found`, the Rust target is installed
but the MinGW PE32 linker is still missing from the host.

For the current end-to-end runtime smoke test, use:

```bash
tools/run_hook_smoke_test.sh
```

That script builds the `dinput8.dll` proxy, copies it into the local RT3 install, and launches RT3
briefly with `WINEDLLOVERRIDES=dinput8=n,b` so Wine prefers the native proxy before the builtin DLL.

`winedbg` is now part of the known-good runtime toolchain for this prefix. Verify it with:

```bash
env WINEPREFIX=/home/jan/projects/rrt/rt3_wineprefix winedbg --help
```

## Launch Pattern

RT3 is sensitive to its working directory because it uses relative paths under `.\Data\`, `.\Maps\`,
and `.\Saved Games\`. Launching it from the repo root can make it start and then exit cleanly without
showing a usable game window.

Use this exact pattern:

```bash
cd /home/jan/projects/rrt/rt3_wineprefix/drive_c/rt3
WINEPREFIX=/home/jan/projects/rrt/rt3_wineprefix /opt/wine-stable/bin/wine RT3.exe
```

If the game appears to fail immediately, check the working directory before assuming a Wine or wow64
regression.

## Canonical Inputs

- Analyze `rt3_wineprefix/drive_c/rt3/RT3.exe` by default.
- Treat `rt3_wineprefix/drive_c/rt3_105/RT3.exe` as a reference build for later diffs.
- Record hashes before trusting any symbol map, address note, or decompilation export.