Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,37 +10,40 @@ archived at 0.10.6): `origin` is n-delic/decompdecomp, `upstream` the archived o

Naming: the project is **decompdecomp** in everything users read. Internal names stay as decomp.wtf left them, so
existing installs and projects keep working: the `decomp` command, the `decompnet` package and data folder,
`~/Decomp`, `.decomp.wtf.json` manifests, `.decomp-wtf/` state, the `decomp-wtf` git branch. Installs and updates
`.decomp.wtf.json` manifests, `.decomp-wtf/` state, the `decomp-wtf` git branch. Installs and updates
come from GitHub (`REPO` in app/updates.py and install.sh); the decomp.wtf domain isn't ours, so nothing may point
at it. `site/` is the website (decomp.ndelic.com, published to GitHub Pages by `.github/workflows/site.yml` on every
push to main that changes `site/public/`); `site/public/` also holds the installer, `install.sh`, which updates read
from GitHub. `main` is what users update from.

This fork defaults to `~/Decomp-RetroReversing` (checkouts: `~/Decomp-RetroReversing-dev`),
separate from upstream databases. Respect explicit `DECOMP_HOME` settings; do not auto-migrate old data.

## Commands

```bash
uv sync
uv run decomp # the development copy of the app, in its own window; projects in ~/Decomp-dev
uv run decomp # the development copy of the app, in its own window; projects in ~/Decomp-RetroReversing-dev
uv run pytest -q # the test suite; many tests skip when a compiler or tool isn't installed
uv run pytest tests/test_forks.py -q # one file
uv run ruff check src tests projects # the linter (CI runs it and the tests)
```

## Never disturb the user's own decompdecomp

The user usually has decompdecomp running (installed, port 6464, projects in `~/Decomp`) with agents working in it.
The user usually has decompdecomp running (installed, port 6464, in its configured data home) with agents working in it.
Testing a change must not touch it:
- A checkout is "decompdecomp dev" (app/edition.py): its own home `~/Decomp-dev`, port 6474, its own window class,
no launcher. One instance is one per home, so it never replaces the installed app. Never point it at `~/Decomp`
(`DECOMP_HOME`). For experiments, give it a throwaway home: `DECOMP_HOME=<scratch dir> DECOMP_TRAY=0 uv run decomp`
- A checkout is "decompdecomp dev" (app/edition.py): its own home `~/Decomp-RetroReversing-dev`, port 6474, its own window class,
no launcher. One instance is one per home, so it never replaces the installed app. Never point it at the live app's data home
(`DECOMP_HOME`), or at upstream's `~/Decomp`. For experiments, give it a throwaway home: `DECOMP_HOME=<scratch dir> DECOMP_TRAY=0 uv run decomp`
(`DECOMP_WINDOW=0`: no window).
- The agent CLIs the app lists (`agy models` above all) start the MCP servers in their own settings. The app finds
them outside PATH too (`~/.local/bin`, `~/.opencode/bin`, ...), so a running experiment also needs a scratch `HOME`
(with `DECOMP_WINDOW=0`); stub them in tests.
- Tests already run with a throwaway `DECOMP_HOME` and no window (tests/conftest.py). When the user's
app runs from this checkout's `.venv`, run them in another environment so uv doesn't rebuild it underneath:
`UV_PROJECT_ENVIRONMENT=<scratch venv> uv run pytest -q`.
- To try a change on a real project, work on a copy: `sqlite3 "file:$HOME/Decomp/.decomp/decomp.db?mode=ro"
- To try a change on a real project, work on a copy: `sqlite3 "file:$HOME/Decomp-RetroReversing/.decomp/decomp.db?mode=ro"
".backup <copy>/.decomp/decomp.db"`, copy the project folder, point `projects.root` in the copy at it. Read the
live database only with `?mode=ro`.
- Don't restart, update or quit the user's app, and don't change its projects, without asking.
Expand Down
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ executables, and no code, assembly or assets taken from them. That includes the
the game, and it belongs to you and the game's owner, not to this repository. Sam's request from decomp.wtf still
stands: only use decompdecomp on games you own, and respect the rules of the decomp projects you work with.

Before you attach a log (`~/Decomp/.decomp/logs/decomp.log`), read it, and cut out any code or assembly.
Before you attach a log (`~/Decomp-RetroReversing/.decomp/logs/decomp.log`), read it, and cut out any code or assembly.

## Reporting a bug

Expand All @@ -26,14 +26,14 @@ decompdecomp is Python 3.12+, managed with [uv](https://docs.astral.sh/uv/).
```bash
git clone https://github.com/n-delic/decompdecomp && cd decompdecomp
uv sync
uv run decomp # the development copy, in its own window (projects in ~/Decomp-dev, or $DECOMP_HOME)
uv run decomp # the development copy, in its own window (projects in ~/Decomp-RetroReversing-dev, or $DECOMP_HOME)
uv run pytest -q # the tests
uv run pytest tests/test_ps2.py -q # one file
uv run ruff check src tests projects # the linter
```

A checkout is a separate app, "decompdecomp dev": its own folder (`~/Decomp-dev`), port and window. It never
replaces the decompdecomp you have installed, and never touches its projects in `~/Decomp`. For an experiment, give
A checkout is a separate app, "decompdecomp dev": its own folder (`~/Decomp-RetroReversing-dev`), port and window. It never
replaces the decompdecomp you have installed, and never touches its projects in `~/Decomp-RetroReversing`. For an experiment, give
it a scratch folder: `DECOMP_HOME=/some/scratch/folder DECOMP_TRAY=0 uv run decomp`. The tests already use a folder
of their own.

Expand Down Expand Up @@ -61,7 +61,7 @@ Some things we won't merge:
the pinned ones.
- Letting agents edit a project's build setup. They're limited to source and header files on purpose.
- Links to the decomp.wtf website. That domain isn't ours. Keep the internal names (`decomp`, `decompnet`,
`~/Decomp`, `.decomp.wtf.json`): existing installs depend on them.
`.decomp.wtf.json`): existing installs depend on them.

Not sure what to work on? [ROADMAP.md](ROADMAP.md) lists what's planned and why, and has a table of which feature
works on which platform: every — in it is a gap to fill.
Expand Down
33 changes: 16 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -608,7 +608,7 @@ Changing or clearing the trusted remote address revokes browser sessions. Disabl
browser access even if the Tailscale proxy remains configured. Use `tailscale serve --https=443 off` to stop that
proxy. Remote addresses must be set from the native app; remote browsers cannot authorize a new destination.

`serve` uses the usual home (`~/Decomp` for an installed copy; `~/Decomp-dev` from a checkout). If an app is already
`serve` uses the usual home (`~/Decomp-RetroReversing` for an installed copy; `~/Decomp-RetroReversing-dev` from a checkout). If an app is already
running for that home, it refuses to replace it. Stop that app deliberately with `decomp stop`, or choose another
home and port, for example `DECOMP_HOME=/path/to/server-projects decomp serve --port 6484`. A checkout can use
`uv run decomp serve --port 6474`. Stop the server with Ctrl-C or `decomp stop` using the same home. Updates preserve
Expand Down Expand Up @@ -654,7 +654,7 @@ decomp
```

The app opens in a native Windows window. Its shortcuts appear on the desktop and in Start, and its tray icon
brings back a window closed while helpers work. Free tools use Windows builds where available. Projects stay in your Windows `Decomp` folder.
brings back a window closed while helpers work. Free tools use Windows builds where available. Projects stay in your Windows `Decomp-RetroReversing` folder.

> [!IMPORTANT]
> **PS1, PS2 and most N64 games need WSL 2 on Windows.** Their period compilers (GCC for PlayStation, EE-GCC and
Expand Down Expand Up @@ -685,7 +685,7 @@ bash site/public/install.sh
```

The installer uses uv and Python 3.12, installs the Cocoa/WebKit bridge, gets the free tools, and creates
`~/Applications/decompdecomp.app`. Open it from Finder or run `decomp`. Projects stay in `~/Decomp`;
`~/Applications/decompdecomp.app`. Open it from Finder or run `decomp`. Projects stay in `~/Decomp-RetroReversing`;
toolchains live in `~/Library/Application Support/decompnet/toolchains`. Xcode Command Line Tools
(`xcode-select --install`) are needed on Intel Macs for N64's MIPS binutils, and on both Mac architectures to
build PS1 GCC 2.6.0, 2.6.3 and 2.8.0 from pinned source on first use. The ready-made 2.7.2 (PSX and CDK) and 2.8.1 compiler binaries are for
Expand Down Expand Up @@ -726,11 +726,11 @@ When launched from a terminal, quitting reports each shutdown stage and the proj
Stages taking more than five seconds print elapsed-time updates. Closing just the window while
keeping work running is reported explicitly; it does not mean the app has quit.

For development: `uv sync`, `uv run decomp` (separate `~/Decomp-dev` state), and `uv run pytest -q`.
For development: `uv sync`, `uv run decomp` (separate `~/Decomp-RetroReversing-dev` state), and `uv run pytest -q`.

To avoid rebuilding a packaged app for each code update, open Settings → Run from Git / update when
idle. Choose a clean `main` checkout from the configured update repository (Git and uv required).
Choose separate `~/Decomp-dev` data, or explicitly keep this app's current projects/settings. This
Choose separate `~/Decomp-RetroReversing-dev` data, or explicitly keep this app's current projects/settings. This
replaces the current process when keeping current data. Separate development data launches another
app and leaves this one running. Neither copies/migrates data nor alters the installed app bundle.
New managed agent sessions and jobs are held until existing work finishes. Continuous background
Expand Down Expand Up @@ -894,18 +894,17 @@ and reports when a size or depth limit means you should scan a smaller folder.
When you close the window while agents work, decompdecomp asks you: stop them and quit, or keep them working.
**Quit** ends the app and everything it started.

## Coming from decomp.wtf or an older version (1.0.x)
## Trying this fork alongside upstream

Your projects stay, decomp.wtf's too: decompdecomp continues decomp.wtf and reads the same folder and database. On
Linux, the new version opens the same `~/Decomp` folder, with every match, name and note in it.
The old Windows installer kept its projects inside a WSL distribution. The Windows app now runs natively and uses
`%USERPROFILE%\Decomp`; it uses WSL for some Linux-only compilers, but doesn't scan WSL for projects automatically.
The RetroReversing fork uses `~/Decomp-RetroReversing` by default on macOS and Linux,
and `%USERPROFILE%\Decomp-RetroReversing` on Windows. Source checkouts use
`~/Decomp-RetroReversing-dev`. Upstream's `~/Decomp` and `~/Decomp-dev` folders are left alone.
The fork's database format differs, so it does not automatically open or migrate upstream projects.
Start a new fork project from your own game, or use **Open a saved project** with a compatible save.

To move projects from the old Windows install, close its app, then copy the whole `Decomp` folder from
`\\wsl.localhost\decomp-wtf\home\decomp\Decomp` to `%USERPROFILE%\Decomp`. Include the hidden `.decomp` folder
inside it: that holds the project database and saved matches. The app reconnects projects to their copied folders.
Did you keep a project outside the `Decomp` folder, in `Documents` for example? Move that project's folder into
`%USERPROFILE%\Decomp` too, and keep its folder name: the app finds a moved project by its name there.
`DECOMP_HOME` still selects an explicit data folder. Existing fork users who deliberately used another
folder can keep that setting; without it, the new default starts with separate projects and settings.
Keep an upstream database separate instead of pointing both apps at the same home.

Saved-project verification uses a private compiler queue (up to four workers, within the global compiler limit),
reuses each worker's header staging, and publishes exact checks in order. The restore dialog shows verified/total
Expand Down Expand Up @@ -944,15 +943,15 @@ so you can keep it in a git repository. You can edit these files or pull another
`progress/`; decompdecomp reads them on the next project action and checks the saved functions again. GameCube, Wii
and PC projects and community decomps are git repositories already: push them.

The simplest way is to copy your whole `~/Decomp` folder to the same place on the new computer. Copy the hidden
The simplest way is to copy your whole `~/Decomp-RetroReversing` folder to the same place on the new computer. Copy the hidden
`.decomp` folder in it too: it holds the matches of every project. decompdecomp then finds every project. To take a
single N64, PlayStation or PlayStation 2 project, or to keep it in git:

**Share or commit only `progress/`.** The rest of a project's folder is made from your copy of the game, and the
game's code is its rights holder's: keep it to yourself.

```
~/Decomp/<project>/
~/Decomp-RetroReversing/<project>/
├── progress/ your work: share this, commit this
│ ├── src/ each matched function's C
│ ├── best/ the closest attempt at each function that doesn't match yet
Expand Down
4 changes: 4 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -868,6 +868,10 @@ similar C through objdiff. Other processors need an instruction reader for this

## Recently done

- **Separate fork data.** Installed copies default to `Decomp-RetroReversing` in the user home;
checkouts and separate source handoffs use `Decomp-RetroReversing-dev`. Explicit `DECOMP_HOME`
overrides still work. Upstream data is never selected or migrated automatically.

- **RetroReversing fork releases.** Tags and app versions use `X.Y.Z-rr.N`; Python packages
use `X.Y.Z+rr.N`. Updater ordering preserves fork revision numbers across Windows, macOS and Linux.

Expand Down
11 changes: 7 additions & 4 deletions docs/CONVENTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,11 @@ the feature easy to move.

## 2. Names

This fork defaults to `~/Decomp-RetroReversing` (checkouts: `~/Decomp-RetroReversing-dev`)
to keep its database separate from upstream. Explicit `DECOMP_HOME` settings remain supported.

- The project is **decompdecomp** in everything users read. Internal names stay as decomp.wtf left them, because
existing installs depend on them: the `decomp` command, the `decompnet` package, `~/Decomp`, `.decomp.wtf.json`,
existing installs depend on them: the `decomp` command, the `decompnet` package, `.decomp.wtf.json`,
`.decomp-wtf/`, the `decomp-wtf` branch. The decomp.wtf domain isn't ours: nothing points at it.
- Python: `snake_case` for functions and variables, `CapWords` for classes, `UPPER_CASE` for module constants
(`STALL_BUDGET`, `MAX_FLAG_VARIANTS`), a leading underscore for what's private to its module or class. The engine's
Expand Down Expand Up @@ -203,13 +206,13 @@ try {
People working on decompdecomp usually have it running too, with agents working in it. A test or an experiment must
not touch it.

- A checkout is a separate app, "decompdecomp dev" (`app/edition.py`): its own home `~/Decomp-dev`, port 6474 and
- A checkout is a separate app, "decompdecomp dev" (`app/edition.py`): its own home `~/Decomp-RetroReversing-dev`, port 6474 and
window class. A newer `decomp` that finds an older one running in the same home quits it and takes its place
(`app/cli.py`), so never point a checkout at your real `~/Decomp`. For an experiment, use a throwaway home:
(`app/cli.py`), so never point a checkout at your real `~/Decomp-RetroReversing`. For an experiment, use a throwaway home:
`DECOMP_HOME=<scratch> DECOMP_TRAY=0 uv run decomp`, with a PATH without agent CLIs.
- If your app runs from the checkout's `.venv`, run the tests in another environment, so uv doesn't rebuild the one
your app uses: `UV_PROJECT_ENVIRONMENT=<scratch venv> uv run pytest -q`.
- To try a change on a real project, use a copy: `sqlite3 "file:$HOME/Decomp/.decomp/decomp.db?mode=ro" ".backup
- To try a change on a real project, use a copy: `sqlite3 "file:$HOME/Decomp-RetroReversing/.decomp/decomp.db?mode=ro" ".backup
<copy>/.decomp/decomp.db"`, copy the project's folder, and point `projects.root` in the copy at it. Read a live
database only with `?mode=ro`.

Expand Down
Loading
Loading