Run from anywhere: py -3.12 -I -B S:/eclipse-build/eb.py <command> .... Below, eb stands for that. Every command
lowers its own priority to BelowNormal. Flags are taken from the argument parsers in the code.
Commands
Jobs
| Command | Flags | What it does |
|---|---|---|
eb run --mem GB [--exclusive] [--reason TEXT] -- <command ...> |
--mem required (GB, peak memory). --exclusive also takes the old .heavy-lock. --reason is the text shown in eb jobs. |
Runs the command when memory and a job slot are free. Exits with the command's exit code. |
eb jobs |
none | Running and waiting eb jobs, why each waits, free commit, holder of the old lock. |
eb free |
none | Free space on S:/ and C:/. |
Stages
| Command | Flags | What it does |
|---|---|---|
eb stage init DIR --id ID --base REL [--title T] |
--id, --base required |
Writes a stage.toml template and a README.md stub in DIR. |
eb stage make DIR |
none | Checks the build runs, copies and hashes the shipped files, writes stage.json. |
eb freeze-stages STAGE.JSON... |
one or more paths | Freezes stage folders into the store and prints the paths of the frozen copies' stage.json. |
Cache and DCX
| Command | Flags | What it does |
|---|---|---|
eb cache run --in PATH... --out PATH... [--env NAME...] [--py EXE...] [--mem GB] [--no-cache] -- <command ...> |
--out required. --mem default 2. |
Skips the command when an identical earlier run is cached; restores its outputs from the store. |
eb dcx normalize PATH... |
one or more files or folders | Re-encodes Kraken .dcx files to the canonical encoding. |
eb dcx check PATH... |
same | Reports which files would be re-encoded. Writes nothing. |
Tools
| Command | Flags | What it does |
|---|---|---|
eb tool build NAME... or eb tool build all |
names from tools/tools.toml |
Builds or restores each tool and prints <name>: <folder>. |
eb tool env |
none | Prints the --tool= overrides and environment variables the release pipeline gets. Never builds. |
Releases
eb release ARGS... passes everything after release to pipeline/release.py, after the --tool= overrides. For
build and check it first runs the provenance gate and freezes the --stages folders. build runs as a 4 GB eb job.
| Command | Flags |
|---|---|
eb release check |
--base (required), --stages ... (required), --work, --ignore-merges |
eb release build |
--base, --out, --version, --stages ... (all required), --work, --dry |
eb release compare |
--a, --b (required), --report FILE, --strict-tag |
eb release verify-fc |
--tree, --fc (required) |
eb release verify-live |
--tree, --version (required), --fc, --report |
compareprintsRESULT IDENTICALorRESULT DIFFERENT (N)for two trees. A content tag on one side only is not a difference unless--strict-tagis given. Exit code 1 when different.verify-fcre-hashes a tree against aFILES-CHANGEDfile.publishandverify-liveare the release coordinator's commands and are not covered in this wiki.- release.py itself also takes
--tool name=pathbefore the subcommand;eb releasefills that in. - Exit codes of release.py: 0 good, 1 problems found, 2 a
STOP:.
The store
| Command | Flags | What it does |
|---|---|---|
eb store ingest PATH --set NAME [--root DIR] [--copy-below BYTES] [--note TEXT] |
--set required. --copy-below default 4194304 (4 MiB). |
Hashes a folder and puts its files in the store as a named set. |
eb store verify [--set NAME]... |
--set may repeat. Default: every set. |
Re-hashes the blobs; reports missing and changed. Exit code 1 if any. |
eb store restore --set NAME --to DIR |
both required | Copies a set back out. Never links. |
eb store stat |
none | Blob count, bytes, links against copies. |
eb rescue SRC [--set NAME] [--note TEXT] [--copy-below BYTES] [--keep-bin] [--files LIST] [--index-other-volume] |
--copy-below default 4 MiB |
Freezes a folder into the store as a set. Skips bin/ (unless --keep-bin), obj/, .git/ and secret-looking files. |
Environment variables
| Variable | Read by | Default | Effect |
|---|---|---|---|
EB_STORE |
eb.py | S:/eclipse-build-store |
The store folder. |
EB_OUT |
eb.py | S:/eclipse-build-out |
Tool builds, copied-out sets, the cache. |
EB_HASH_JOBS |
eb.py | 4 | Hashing threads in ingest, verify and the cache. 1 = one file at a time. |
EB_GATE |
eb.py | unset | warn or fail forces the provenance gate's mode. |
EB_REG_IV |
Polish, TableRows | content under eb release; unset elsewhere means a random IV |
content, or 32 hex digits for a fixed IV. |
EB_JOBS_DIR |
ebjobs.py | S:/eclipse-build-out/jobs |
Where job entries are kept. |
EB_LEGACY_LOCK |
ebjobs.py | S:/eclipse-0083-stage/.heavy-lock |
The old shared lock folder. |
EB_FAKE_MEM |
ebjobs.py | unset | Tests only: limit,free in GB. |
EB_REL_JOBS |
release.py | 4 | Parallel RegQ / Polish runs. 1 = one after another. |
EB_REL_CHAIN |
release.py | on | 0 = one Polish process per rowlist. |
EB_DCX_JOBS |
dcxnorm.py | 4 (or the CPU count if lower) | Files handled at once. |
EB_OO2CORE_9 |
dcxnorm.py | set by eb dcx |
Path of the Oodle DLL. |
EB_REGQ, EB_LEDA_DIR, EB_PARAMDEFS, AI_LUA_VANILLA_DIR |
the release check scripts | set by eb release |
Pinned tool and data folders. eb tool env prints them. |
EB_TOOLS_LIVE, EB_DHP_LIVE |
tools/ds2/npmirror.py |
unset | 1 makes DS2 builds use the live souls-script-kt tool bins (all of them, or Ds2HumanPort only) instead of the eclipse-build ones. |
AI_LUA_BUDGET_SKIP |
release.py | Ignored on purpose: the AI Lua budget always runs. |
Job admission numbers (ebjobs.py)
| Name | Value |
|---|---|
| Jobs at once | 4 |
| Reserve left free | 6 GB |
| Small job (never queues behind big ones) | 1 GB or less |
| Heavy job (also takes the old lock) | 8 GB or more |
| Warm-up (a younger job's memory counts as still to come) | 120 s |
Key folders
| Path | What |
|---|---|
S:/eclipse-build |
The repo: eb.py, ebjobs.py, tools/, pipeline/, hooks/, frozen/INDEX.tsv, docs/ |
S:/eclipse-build/tools/tools.toml |
The list of shared tools |
S:/eclipse-build/tools/dotnet/<Name> |
Source of each dotnet tool |
S:/eclipse-build/pipeline/release.py |
The release pipeline that eb release runs |
S:/eclipse-build/pipeline/stage.schema.json |
The stage.json schema |
S:/eclipse-build/frozen/INDEX.tsv |
One line per store set: name, list hash, files, bytes, date, source folder |
S:/eclipse-build-store/objects/<ab>/<sha256> |
The store |
S:/eclipse-build-out/tools/<name>/<key> |
Built dotnet tools |
S:/eclipse-build-out/sets/<set>-<hash> |
Frozen tools and data copied out of the store; stage-<hash> for frozen stages during a release run |
S:/eclipse-build-out/cache |
eb cache entries |
S:/eclipse-build-out/jobs |
eb job entries |
S:/eclipse-00NN-stage/<name> |
Stage folders for release 0.0.NN |
S:/souls-script-kt/output/eclipse-release-<v>/depth6-online-mods |
A release tree. Its parent holds FILES-CHANGED-<v>.sha256.txt, RC-NOTES-<v>.md and the logs. stage make reads the base release from here. |
S:/eclipse-0083-stage/.heavy-lock |
The old shared lock. Never make or remove it by hand. |
Rules (from AGENTS.md)
- Reproducible means pinned. Every shipped file traces to a recipe in the repo or a frozen set. Tools are named by
commit or source hash, inputs by sha256. No paths into
.tmp, scratchpads or another stage's work folder. - Never delete or move originals (
S:/souls-script-kt/.tmp, stage folders,S:/_modding,S:\Smithbox-havok-pin, release trees) because they are in the store. Deleting needs Stan's explicit OK. - Never put secrets in git. The Discord webhook,
signing/and tokens. The pre-commit hook checks; do not bypass it. - Git holds only the repo's own code, docs and
frozen/INDEX.tsv. Logs, dumps, reports, copies of other repos' files, tool copies, build output and anything over 5 MiB go to the store. - Anything that uses real memory or CPU runs as an eb job, declaring its real peak memory.
- Never launch the game.
- Never discard Smithbox edits.
- No commits or pushes unless asked (
docs/AGENTS-GUIDE.md).